Enable Apple Pay

Integrate Apple Pay in the Rainforest Payment Component

You can implement Apple Pay to your existing Rainforest integration in four steps:

  • Host the Apple Pay verification file on your platform
  • Register your domain where the Payment Component is embedded
  • Configure the Apple Pay button in the Payment Component
  • Handle the Apple Pay payment method in your platform

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:

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 send 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.

Event listeners

If Apple Pay is requested via the allowed-methods prop, we'll let you know if it is supported and available for the specified merchant via events.

The loaded event will return a payload in the following format:

type ValidatedACHPartner = 'PLAID';

type LoadedPayload = {
    apple_pay: {
        is_supported: boolean;
    };
    validated_ach: {
        partner: Nullable<ValidatedACHPartner>;
        is_supported: boolean;
    };
};

Listen to this event and parse the event data to know if Apple Pay is supported:

const component = document.getElementById('payment-component');
component.addEventListener('loaded', function (data) {
    if (data.detail[0].apple_pay.is_supported) {
        console.log('Apple Pay is supported!');
    }
});

The Payment 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 Apple Pay 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.