From 580a77996d734aa0ba5dea28f8a2edf1852eab96 Mon Sep 17 00:00:00 2001
From: "Pimm \"de Chinchilla\" Hogeling" <pimmhogeling@gmail.com>
Date: Thu, 28 Jan 2021 13:04:29 +0100
Subject: [PATCH] Applied third round of documentation copying after rebasing
 on master.

(See 410d4a577fc3abeef5e8ef6ebc4a9dae6dfcfc29)
---
 src/resources/applePay/ApplePayResource.ts | 23 ++++++++++++++++++++++
 src/resources/applePay/parameters.ts       | 12 ++++++++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/resources/applePay/ApplePayResource.ts b/src/resources/applePay/ApplePayResource.ts
index e724bd37..67ea4a41 100644
--- a/src/resources/applePay/ApplePayResource.ts
+++ b/src/resources/applePay/ApplePayResource.ts
@@ -7,6 +7,29 @@ import renege from '../../plumbing/renege';
 export default class ApplePayResource {
   constructor(protected readonly networkClient: NetworkClient) {}
 
+  /**
+   * For integrating Apple Pay in your own checkout on the web, you need to [provide merchant
+   * validation](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/providing_merchant_validation). This is normally done using Apple's [Requesting Apple Pay
+   * Session](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api/requesting_an_apple_pay_payment_session). The merchant validation proves (to Apple) that a validated
+   * merchant is calling the Apple Pay Javascript APIs.
+   *
+   * When integrating Apple Pay via Mollie, you cannot call Apple's API but you should call this API instead. The response of this API call should be passed as-is to the the completion method,
+   * [completeMerchantValidation](https://developer.apple.com/documentation/apple_pay_on_the_web/applepaysession/1778015-completemerchantvalidation).
+   *
+   * Before requesting an Apple Pay Payment Session, you must place the [domain validation file](http://www.mollie.com/.well-known/apple-developer-merchantid-domain-association) on your server at:
+   * `https://[domain]/.well-known/apple-developer-merchantid-domain-association`. Without this file, it will not be possible to use Apple Pay on your domain.
+   *
+   * The guidelines for working with a payment session are:
+   *
+   * -   Request a new payment session object for each transaction. You can only use a merchant session object a single time.
+   * -   The payment session object expires five minutes after it is created.
+   * -   Never request the payment session from the browser. The request must be sent from your server.
+   *
+   * For the full documentation, see the official [Apple Pay JS API](https://developer.apple.com/documentation/apple_pay_on_the_web/apple_pay_js_api) documentation.
+   *
+   * @since 3.5.0
+   * @see https://docs.mollie.com/reference/v2/wallets-api/request-apple-pay-payment-session
+   */
   public requestPaymentSession(parameters: RequestPaymentSessionParameters): Promise<ApplePaySession>;
   public requestPaymentSession(parameters: RequestPaymentSessionParameters, callback: Callback<ApplePaySession>): void;
   public requestPaymentSession(parameters: RequestPaymentSessionParameters) {
diff --git a/src/resources/applePay/parameters.ts b/src/resources/applePay/parameters.ts
index b64642bb..5d50966c 100644
--- a/src/resources/applePay/parameters.ts
+++ b/src/resources/applePay/parameters.ts
@@ -1,11 +1,17 @@
 export interface RequestPaymentSessionParameters {
   /**
-   * The validationUrl you got from the ApplePayValidateMerchant event
-   * https://developer.apple.com/documentation/apple_pay_on_the_web/applepayvalidatemerchantevent
+   * The `validationUrl` you got from the [ApplePayValidateMerchant event](https://developer.apple.com/documentation/apple_pay_on_the_web/applepayvalidatemerchantevent).
+   *
+   * A [list of all valid host names](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server#3172427) for merchant validation is available. You should white list these
+   * in your application and reject any `validationUrl` that have a host name not in the list.
+   *
+   * @see https://docs.mollie.com/reference/v2/wallets-api/request-apple-pay-payment-session?path=validationUrl#parameters
    */
   validationUrl: string;
   /**
-   * The domain of your web shop, that is visible in the browser’s location bar. For example pay.myshop.com.
+   * The domain of your web shop, that is visible in the browser's location bar. For example `pay.myshop.com`.
+   *
+   * @see https://docs.mollie.com/reference/v2/wallets-api/request-apple-pay-payment-session?path=domain#parameters
    */
   domain: string;
 }