🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

You can easily accept payments Apple Pay in Rainforest's payment component.

Apple Pay is a convenient option for paying online when using an Apple device and it can increase conversion rates.

How to enable Apple Pay

You can add Apple Pay to your existing Rainforest integration in three steps.

Host Apple Pay verification file

Apple requires verification of all domains that process Apple Pay payments. This verification is performed by hosting a file on the domain where Apple Pay payments will be collected. Download one or both of the Apple Pay domain verification files below:

• Sandbox Apple Pay domain verification file
• Production Apple Pay domain verification file

You must host the sandbox Apple Pay domain verification file in your sandbox environment and the production Apple Pay domain verification file in your production environment.

Host the corresponding domain verification file at:

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

The file must be publicly accessible at the URL above to be successfully verified by Apple.

Register payment method domain

Once the Apple Pay verification file has been hosted, you are ready to create and verify your domain for payment processing with Apple Pay.

Create payment method domain

First, create a payment method domain. When making this request, provide the full hostname of where you will be offering Apple Pay payments via the Rainforest payment component.

For example, if the Rainforest payment component is hosted at https://pay.yourdomain.com/, you must use pay.yourdomain.com as the domain_name.

Note the payment_method_domain_id value in the response as you will need it to verify your payment method domain.

The payment method domain domain_name must be a unique value. If you need to re-verify your domain, then you can delete the payment method domain and re-create and verify it.

Verify payment method domain

Once the Apple Pay verification file has been hosted and the payment method domain has been created, you are ready to verify the payment method domain.

Verify the payment method domain by providing the payment_method_domain_id value in the URI of the request.

If the request results in a 200 OK response with a status of VERIFIED, your payment method domain has been successfully verified by Apple.

If the request results in a 400 Bad Request, your Apple Pay verification file could not be verified by Apple. Ensure that your Apple Pay verification file is publicly accessible at:

https://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

You may sned the verify payment method domain API request repeatedly until verification has succeeded.

Once your payment method domain has been verified, you are ready to configure the Rainforest payment component.

Configure the component

When rendering the payment component, add APPLE_PAY to the list of allowed-methods :

  <rainforest-payment
    session-key='REPLACE_ME'
    payin-config-id='REPLACE_ME'
-   allowed-methods="CARD,ACH"
+   allowed-methods='CARD,ACH,APPLE_PAY'
  ></rainforest-payment>

Rainforest will render an Apple Pay button at the top of the component, above the payment fields, if it is supported.

Your platform must have at least one verified payment method domain for the Apple Pay capability to be available. If your platform does not have at least one verified payment method domain present, the Apple Pay button will not be present. Note that a browser console log message will be logged making you aware of this condition.

If the customer uses Apple Pay, the component will emit the same events as it does for other payment methods. You can continue to handle those as you do already.

Handle the new payment method type

Cards collected via Apple Pay behave differently from raw cards, so they are represented in the API as a separate type of payment method. For many integrations, this won’t impact you, but in some cases you may need to make integration changes to handle this type.

Check if you have any code that looks at a Rainforest Payin or PaymentMethod and gets data from the card sub-object. In the Apple Pay case, the following will be different:

• method_type will be APPLE_PAY instead of CARD
• card will be null
• apple_pay will be populated with relevant information on the payment method

{
  // ...
  "method_type": "APPLE_PAY",
  "card": null,
  "apple_pay": {
    "type": "CREDIT",
    "brand": "VISA",
    "brand_desc": "Visa",
    "description": "Visa 1366"
  }
}

If you currently save cards for future use by using the card object, we recommend that for Apple Pay you should save the apple_pay.description as the way you show the card to the customer when they want to select it again.

Where is Apple Pay supported?

Rainforest supports “Apple Pay on the Web”, a payment flow that runs inside a web browser for a customer to make a card payment to a merchant. (This is different from Apple Pay in native apps, tap-to-pay, peer-to-peer payments, and several other kinds of “Apple Pay”.)

For Apple Pay on the Web to be shown to customers, a few requirements need to be met:

• Browser support: the customer needs to be viewing the page in Safari, not in incognito mode, on a device that has a secure element, with a recent version of macOS or iOS.
• Domain support: your platform needs to register each domain where you want to initiate Apple Pay transactions via Rainforest’s API.
• Payment Component support: the Payment Component showing the Apple Pay button needs to be on the top-level page (not an iframe), on a domain that has been registered.

Apple Pay also has a few unique characteristics compared to a manually-entered card number:

• Card-on-file: while most issuers allow Apple Pay tokens to be reused for future transactions, some will only allow the token to be used once, or for a limited window of time, and many issuers will only allow the token to be used on the same merchant where it was initially collected. Each issuer determines Apply Pay eligibility for payins with stored payment methods and your flow should require the payer to come back and select a new card to complete payment if the card-on-file payment declines.
• 3DS: Cards collected via Apple Pay cannot also go through 3D Secure.