Native API

Our Native API integration allows you to handle your front-end interactions completely, this gives you the desired flexibility. However, this also means that you need to handle a few interactions with Apple in order to support Apple Pay.

Events & functions you need to handle in integration with MacOS:

1. CanMakePayments : This function is used to know if the consumer has a card configured on the wallet
2. Create ApplePayPaymentRequest and pass it in ApplePaySession : Request for payment from consumer. You need to provide ‘supports3DS’ in parameter ‘merchantCapabilities’
3. onValidateMerchant Event : Provide your PaymentIntent ID as input and make a call to initiate payment session
4. completeMerchantValidation : Data returned from above step to be used here to complete Merchant validation
5. onPaymentAuthorized Event : Initiate confirm PaymentIntent request as indicated with payment token information.

Below are the steps you need to follow to integrate Apple pay via Native API:

1. Create a payment Intent Create a Payment Intent through the Airwallex API - see full details here API.

2. Start an Apple Pay session Request a valid session for each transaction from the Apple Pay server.

Endpoint: POST pci-api-demo.airwallex.com/api/v1/pa/payment_session/start

Sample request

• X-on-behalf-of (header) : If you are a partner using our PA for platforms solution and you are enabling your connected accounts to collect payments with their own domains, then you need to use this in the header with the open identifier of the connected account. If your connected accounts do not have a separate domain each or if you manage all of the domains used by connected accounts then you need not use this.
• Payment_intent_id : Payment Intent Identifier, Received in response to Create PaymentIntent request
• Validation_Url : ApplePay Merchant validation URL. the value can be obtained from ApplePayValidateMerchantEvent object in onvalidatemerchant event handler.
• Initiatitive_Context : DOMAIN_NAME of e-commerce which is verified by ApplePay.

Sample response

This response should be used further as a merchantSession parameter in completeMerchantValidation which is expected to be handled at your front-end.

3. Confirm the payment Intent Confirm a Payment Intent through the Airwallex API - see full details here API.

Endpoint: POST pci-api-demo.airwallex.com/api/v1/pa/payment_intents/{{payment_intent_id}}/confirm

Sample request

• applepay.payment_data_type: Type of the payment data details. One of tokenized_card or encrypted_payment_token.
• applepay.encrypted_payment_token:Payment data from ApplePayPaymentToken
• Payment_method.applepay.card_brand: the value can be obtained from ApplePayPaymentToken.paymentMethod.network
• Payment_method.applepay.card_type: the value can be obtained from ApplePayPaymentToken.paymentMethod.type
• Payment_method.applepay.data: the value can be obtained from ApplePayPaymentToken.paymentData.data
• Payment_method.applepay.ephemeral_public_key: the value can be obtained from ApplePayPaymentToken.paymentData.header.ephemeralPublicKey
• Payment_method.applepay.public_key_hash: the value can be obtained from ApplePayPaymentToken.paymentData.header.publicKeyHash
• Payment_method.applepay.transaction_id: the value can be obtained from ApplePayPaymentToken.paymentData.header.transactionId
• Payment_method.applepay.signature: the value can be obtained from ApplePayPaymentToken.paymentData.signature
• Payment_method.applepay.version: the value can be obtained from ApplePayPaymentToken.paymentData.version

After the payment is finished, call completePayment to make sure that the Apple Pay widget is closed.

Subscription payments

Airwallex allows you to create a PaymentConsent with the shopper to initiate future payments using shopper’s saved payments details. For more information, see Save payment details for future payments. You need to add additional information about the order & terms of the payment to display this information on the payment sheet.

Save payment details without payment

1. Create customer - You need to create customer API if it is a new customer

2. Get available payment method types - If applepay payment method is active with recurring transaction mode, the merchant can choose Apple Pay as payment methods for subscriptions. Refer sample response below

Endpoint : GET /api/v1/pa/config/payment_method_types

3. Apple Pay payment request - As explained at the start of this page, you need to create ApplePayPaymentRequest and include the information about subscription payment along with lineitem details. See below samples :

Fixed Subscription Payment with deferred start

Variable Subscription Payment with deferred start

4. Start a Payment session - Make a sessions call to retrieve the payment session for Apple Pay. Refer below requests & response samples

Endpoint : POST pci-api-demo.airwallex.com/api/v1/pa/payment_intents/{{payment_intent_id}}/confirm

Request

Response

5. Create a Payment Method - Create a Payment method through the Airwallex API - see full details here API. Sample below:

6. Create a Payment consent - Create a Payment consent through the Airwallex API - see full details here API. See sample request below:

   JSON

7. Verify Payment consent - Verify the Payment consent through the Airwallex API - see full details here API. See sample below:

Save payment details with payment

1. Create customer - You need to create customer API if it is a new customer

2. Get available payment method types - If applepay payment method is active with recurring transaction mode, the merchant can choose Apple Pay as payment methods for subscriptions. Refer sample response below

Endpoint : GET /api/v1/pa/config/payment_method_types

3. Apple Pay payment request - As explained at the start of this page, you need to create ApplePayPaymentRequest and include the information about subscription payment along with lineitem details. See below samples :

Fixed Subscription Payment with immediate start

Variable Subscription Payment with immediate start

3. Start a Payment session - Make a sessions call to retrieve the payment session for Apple Pay. Refer below requests & response samples

Endpoint : POST pci-api-demo.airwallex.com/api/v1/pa/payment_intents/{{payment_intent_id}}/confirm

Request

Response

4. Create a Payment Method - Create a Payment method through the Airwallex API - see full details here API. Sample below:

5. Create a Payment consent - Create a Payment consent through the Airwallex API - see full details here API. See sample request below:

6. Create a Payment Intent - for the order with the customer ID. This step is only needed for shopper wishes to pay for the first order in the payment method binding process.

7. Confirm Payment Intent - Confirm the Payment intent through the Airwallex API - see full details here API. This request should refer to PaymentConsent ID created in Step#5, see sample request below: