Apple Pay Integration Guide

Offering Apple Pay requires registering with Apple on all web domains that will expose an Apple Pay button (includes TLD and subdomains). This is a requirement for production AND test environments.

Before you begin

Here are the things that you need in order to complete the steps in this guide:

  • You have a merchant profile with SumUp and have already filled in your profile details
  • For a test profile reach out to our support team through this contact form

Steps

Apple’s documentation for Apple Pay on the Web describes the specifics required from their side in order to successfully move forward with creating and processing checkouts. To begin your implementation, follow these steps:

  1. Host the domain association file at https://[YOUR_DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association. Once hosted, request our integration specialists help finalize your connection to Apple Pay
  2. Before moving on to the next steps, get familiar with Apple’s requirements
  3. Create a checkout
  4. Create an Apple Payment request
const applePaymentRequest = {
  currencyCode: 'EUR',
  countryCode: 'DE',
  merchantCapabilities: ['supports3DS'],
  supportedNetworks: ['masterCard', 'visa'],
  total: {
    label: 'Demo',
    amount: '0.00',
    type: 'final',
  },
};
  1. Initiate an Apple Pay session and call the begin method
  2. Listen for the onvalidatemerchant callback and collect the validateUrl property. Create the following payload
{
  "target": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession",
  "context": "your_domain_name"
}

and initiate a merchant session by calling

PUT https://api.sumup.com/v0.1/checkouts/${checkoutId}/apple-pay-session

  1. The response from the previous step is needed to complete the merchant validation with the completeMerchantValidation method

  2. Submitting the payment dialogue triggers the onpaymentauthorized callback, this is when you need to process the checkout. The process checkout request body needs to include a payment_type of apple_pay and an apple_pay object, containing the response from step 7

{
  "payment_type": "apple_pay",
  "id": "9be2da07-a7bd-4877-bc0a-e16cd909a876",
  "amount": 12,
  "currency": "EUR",
  "apple_pay": {
    "token": {
      "paymentData": {
        "data": "si2xuT2ArQo689SfE-long-token",
        "signature": "MIAGCSqGSIb3DQEHA-long-signature",
        "header": {
          "publicKeyHash": "PWfjDi3TSwgZ20TY/A7f3V6J/1rhHyRDCspbeljM0io=",
          "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEaBtz7UN2MNV0qInJVEEhXy10PU0KfO6KxFjXm93oKWL6lCsxZZGDl/EKioUHVSlKgpsKGin0xvgldfxeJVgy0g==",
          "transactionId": "62e0568bc9258e9d0e059d745650fc8211d05ef7a7a1589a6411bf9b12cdfd04"
        },
        "version": "EC_v1"
      },
      "paymentMethod": {
        "displayName": "MasterCard 8837",
        "network": "MasterCard",
        "type": "debit"
      },
      "transactionIdentifier": "62E0568BC9258E9D0E059D745650FC8211D05EF7A7A1589A6411BF9B12CDFD04"
    }
  }
}