Apple Pay™

The purpose of this guide is to help merchants integrate Apple Pay and provide a fast, easy, and secure way for users to buy goods and services in your app or your website. Merchants who have implemented Apple Pay using best practices have substantially increased their checkout conversion rates, increased customer loyalty, purchase frequency, and reduced checkout time.

These guidelines are for businesses that wish to incorporate Apple Pay into their websites Acceptable Use Guidelines for Apple Pay on the Web

Before You Begin

These instructions explain how to add Apple Pay to your existing API-only integration. The API-only integration works the same way for all payment methods. If you have not yet done this integration, refer to our API only integration guide .

We recommend using Bluefin’s Apple Pay certificate which makes it quicker to set up Apple Pay, or you can use your own Apple Developer account and certificate which will require extra configuration steps.

Merchants who want to integrate Apple Pay through Bluefin’s Apple Pay Certificate must set up their server for secure communication with Apple Pay.

All pages that include Apple Pay must be served over HTTPS.
Your domain must have a valid SSL certificate.
Shop website: your main website URL, for example https://www.mystore.com.
Additional shop websites: Optional. Add any other domains you use for your shop website, for example https://www.mystore1.com, or https://www.mystore2.com.
You cannot use https://localhost to test.

📘
Note
The option to use Bluefin’s Apple Pay certificate is only available on the web.

Build Your Payment Form for Apple Pay

After you have finished enabling Apple Pay, you can show Apple Pay as an available payment method. Click here to learn about Apple Pay Human Interface Guidelines.

When the shopper selects Apple Pay, they are presented with a prompt to verify the payment using Touch ID or Face ID. If the shopper is using a Mac without Touch ID, they will be prompted to verify the payment using an iPhone or Apple Watch registered to the same iCloud account.

Make a `/paymentMethods` Request

In the request, you must specify the following:

countryCode: Country where Apple Pay is supported. For example, NL.
amount.currency: Any supported currency. For example, EUR.
channel: Set this to Web if the payment is being initiated from Safari, or iOS for in-app payments.

In the response, you will receive:

paymentMethod.type: applepay.
merchantId and merchantName: If you are using Bluefin’s Apple Pay certificate, you will need to complete Apple Pay Session Validation.

Complete the Apple Pay Session Validation

When the shopper selects payment via Apple Pay, this opens the event handler. You then need to complete the Apple Pay session validation using the completeMerchantValidation method which you can lear more about here. You can do this while using Bluefin’s Apple Pay certificate or you can use your own.

Make an `/applePay/session` Call to Retrieve the Payment Session

Below is a a code example of an /applePay/session request:

const getApplePayPaymentSession = async () => {
    const headers = new Headers({
      'Content-Type': 'application/json'
    });
    const getApplePaySessionParams = {
      display_name: displayName,
	referrer: ‘example.com’,
	merchant_id: ‘000000000001’
    }
    return (await fetch('https://secure.payconex.net/api/v1/apple_pay/get_apple_pay_session', {
      method: 'POST',
      body: JSON.stringify(getApplePaySessionParams),
      headers
    })).json();
  }

Pass the decoded data as an object to the completeMerchantValidation method to complete the Apple Pay session validation. Please click here to learn more about merchant validation.

If the Apple Pay session is successfully validated, Apple Pay prompts the shopper to authorize the payment using Touch ID or Face ID.

Make a payment

After the shopper authorizes the payment, get the token from the Apple Pay framework.
Stringify and base64 encode the entire paymentData object.
From your server, make a /payments request specifying paymentMethod.type: applepay.

The following is a request in cURL, followed by the JSON response:

curl --location --request POST 'https://secure.payconex.net/api/qsapi/3.8' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=220614988001' \
--data-urlencode 'api_accesskey=6b0b0239844940fa817647713ad63345' \
--data-urlencode 'response_format=JSON' \
--data-urlencode 'transaction_type=SALE' \
--data-urlencode 'tender_type=APay' \
--data-urlencode 'transaction_amount=10' \
--data-urlencode 'apay_payload={"paymentData":{"data":"pJDf000FLiXGEmTHQkE092L4c8DXSqsQavIDoKdBYLPod0Sbe6ZQ5qKBR9SKI2yLbU9SUynFBzC03UaOvSiCa2mlSU7P5GR2AQYGSZCadDNzgllttJ+TS6FsfEntk7ZN/vHavjVIsBCkUf2gj8IX3QGiCf4FLuwLLzHdpD0Q3ZK/aSFuq7DS6U/DQ89PTbN9b7uEteZZfuJkOm9cImYpU5+9oCrFPOpCsJK+A09Lb+TffcFyW6VNyE9nN0x5b03yeqRTHMYiflBEy/X57qtPOcVsXaMWqbUQpb/ThO1xu1GHRZCSByW+TNFQx27I7Z/x3NONrSu5pWfs+qPay9a6vD8GXA361YcActO/mZa64fre8raFvlnGud5VE5K2jm+dDS8ZXFNKyx96+Q7wqzofyyPS65imEj3dZTO3zOaMV2c=","signature":"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","header":{"publicKeyHash":"LfT8NhajbyOZdSZ5fWF9tJjQk9ZUoy+CnI5PZsD/e7M=","ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEhqMCGz4i/t6RttDR7q05CDpFRR2psP5ioAQd+S1zCq+OevgOe5spQp1tJe/cmLpj45uxhsHy2j6lxbdxewtodw==","transactionId":"d66cad3ca13e65dc88a2769fda530e37de03abd2b13548e6d7c7e902f55ef63d"},"version":"EC_v1"},"paymentMethod":{"displayName":"Visa 0326","network":"Visa","type":"debit"},"transactionIdentifier":"D66CAD3CA13E65DC88A2769FDA530E37DE03ABD2B13548E6D7C7E902F55EF63D"}'

{
    "transaction_id": "000000002621",
    "tender_type": "CARD",
    "transaction_timestamp": "2021-11-17 03:57:37",
    "card_brand": "VISA",
    "transaction_type": "SALE",
    "last4": "8423",
    "card_expiration": "1223",
    "authorization_code": "427270",
    "authorization_message": "APPROVED",
    "request_amount": 10,
    "transaction_amount": 10,
    "keyed": true,
    "swiped": false,
    "entry_mode": "keyed",
    "transaction_approved": true,
    "currency": "USD",
    "error": false,
    "error_code": 0,
    "error_message": null,
    "error_msg": null
}

Present the Payment Result

p
Present the payment result to your shopper using the resultCode you received in response to your /payments call.

resultCode	Description	Action
Authorized	The payment was successful.	Inform the shopper that the payment has been successful.
Refused	The payment was refused by the shopper's bank.	Ask the shopper to try the payment again using a different payment method.

Testing

Use Apple's test card numbers to test your integration.

Card Brand	Card Number	Expiration Date	CVC/CID
Discover	6011 0009 9446 2780	11/2022	111
Mastercard	5204 2452 5000 1488	11/2022	111
Visa	4761 1200 1000 0492	11/2022	533

For a full list of test cards and instructions on how to add these to your test device, see 'Sandbox Testing' on Apple's Developer website.

To create an Apple Pay sandbox environment and test payments, you need an Apple Developer account. This also applies if you are using Bluefin’s Apple Pay certificate.

Going Live

To process live Apple Pay payments, your API credential needs to have the API Client Side Encryption Payments role.

Make sure you follow Apple's guidelines on:

Enable Apple Pay using either Bluefin’s Apple Pay certificate, which is quicker, or your own Apple Developer account and certificate, which will require the extra configuration steps listed below:

Download and unzip the domain association file.
Host the domain association file with the name apple-developer-merchantid-domain-association on each domain you want to use, including subdomains, under /.well-known/apple-developer-merchantid-domain-association.

The file must have the following characteristics:

It must have Content-Type: text/plain in the header.
It must be externally accessible.
It must not be password protected.
It cannot be behind a proxy or redirect.

Before You Begin

📘Note

Build Your Payment Form for Apple Pay

Make a /paymentMethods Request

Complete the Apple Pay Session Validation

Make an /applePay/session Call to Retrieve the Payment Session

Make a payment

Present the Payment Result

Testing

Going Live

📘
Note

Make a `/paymentMethods` Request

Make an `/applePay/session` Call to Retrieve the Payment Session