Prerequisites: Add Apple Pay to your integration · Set up Apple Pay for a merchant
You can extend your Apple Pay integration to add a convenience fee to a payment.
How it works
You send a request to the Apple Pay JS API that contains the amount for the payment and the amount for the convenience fee.
Apple returns a
cryptogram
after your customer authorizes the total amount.
You send a single payment request to our gateway for the total amount of the payment including the convenience fee.
Before you begin
- Integrate with Apple Pay.
- Set up Apple Pay for the merchant and store their merchant identifier.
You must use Apple Pay JS API version 14 or later.
Integration steps
- Update your Apple Pay integration.
- Send a payment request.
Step 1. Update your Apple Pay integration
Update your Apple Pay integration to include the multiTokenContexts array with two entries in the ApplePayPaymentRequest. One entry is for the sale amount, and the other entry is for the convenience fee.
If your request is successful and the customer authorizes the payment, Apple Pay returns a cryptogram that you need to include in the payment request to our gateway.
Request parameters
| Parameter | Description |
|---|---|
| merchantIdentifier | Merchant identifier that we assigned when you set up the merchant with Apple Pay. The value is the same for both entries. |
| externalIdentifier | ID that our gateway uses to identify the payment and the convenience fee. The value depends on the entry: • For the sale amount, send PRIMARY. • For the convenience fee, send CONVENIENCE_FEE. |
| merchantName | Name of the merchant that you set up with Apple Pay. |
| amount | Amount for the sale or the convenience fee. |
multiTokenContexts example
"multiTokenContexts": [
{ "merchantIdentifier": "PMID-2", "externalIdentifier": "PRIMARY", "merchantName": "Merchant 1", "amount": "100.00" },
{ "merchantIdentifier": "PMID-2", "externalIdentifier": "CONVENIENCE_FEE", "merchantName": "Merchant 1", "amount": "2.50" }
]
Step 2. Send a payment request
After you receive the cryptogram from the Apple Pay JS API, send a payment request to our Payments endpoint to run the sale. In the payment request, the value for the order.amount parameter is the total amount of the payment including the convenience fee.
If your request is successful, our gateway splits the total amount between the sale amount and the convenience fee.