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 that implemented Apple Pay using best practices have substantially increased checkout conversion rates, customer loyalty and purchase frequency, and reduced checkout time.

Please refer to these guidelines 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 haven't yet done this integration, refer to our API only integration.

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

Merchants that want to integrate Apple Pay through Bluefin’s Apple Pay Certificate have to 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 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 check out 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 will have to 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 receive:

  • paymentMethod.type: applepay.
  • merchantId and merchantName: If you're using Bluefin’s Apple Pay certificate, you'll need to complete Apple Pay Session Validation

Complete the Apple Pay Session Validation

When the shopper selects to pay with Apple Pay, you get 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 also use your own.

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

Below is a a code example of an /applePay/sessions 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

  1. After the shopper authorizes the payment, get the token from the Apple Pay framework.
  2. Stringify and base64 encode the entire paymentData object.
  3. 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

Use the resultCode that you received in response to your /payments call to present the payment result to your shopper.

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're 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:

  1. Download and unzip the domain association file
  2. 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 Content-Type: text/plain in the header.
  • Be externally accessible.
  • Not be password protected.
  • The file cannot be behind a proxy or redirect.

Did this page help you?