Take paymentsApple Pay®Extend your integration

Add a convenience fee

View as Markdown

You can extend your Apple Pay integration to add a convenience fee to a payment.

How it works

  1. You send a request to the Apple Pay JS API that contains the amount for the payment and the amount for the convenience fee.
  2. Apple returns a cryptogram after your customer authorizes the total amount.
  3. You send a single payment request to our gateway for the total amount of the payment including the convenience fee.

Before you begin

You must use Apple Pay JS API version 14 or later.

Integration steps

  1. Update your Apple Pay integration.
  2. 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

ParameterDescription
merchantIdentifierMerchant identifier that we assigned when you set up the merchant with Apple Pay. The value is the same for both entries.
externalIdentifierID 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.
merchantNameName of the merchant that you set up with Apple Pay.
amountAmount for the sale or the convenience fee.

multiTokenContexts example

1"multiTokenContexts": [
2  { "merchantIdentifier": "PMID-2", "externalIdentifier": "PRIMARY",  "merchantName": "Merchant 1", "amount": "100.00" },
3  { "merchantIdentifier": "PMID-2", "externalIdentifier": "CONVENIENCE_FEE", "merchantName": "Merchant 1", "amount": "2.50" }
4]

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.