Apple Pay

Apple Pay is a mobile and online purchasing experience for customers with supported iOS and macOS devices. For more details on compatibility and availability, see our Apple Pay support article.

This guide explains how to process Apple Pay payments with Braintree GraphQL APIs.

Configuration

iCloud account setup

When testing, you will need to be logged into an iCloud account that corresponds to your environment. Testing in sandbox requires you to be logged into an iTunes Connect sandbox tester account, which you can create with an Apple Developer account. Similarly, you will need to be logged into a production iCloud account when testing in production.

Specify an Icon

When using Apple Pay on the web, users will be presented with your site's apple-touch-icon, if present. It is recommended that you add an apple-touch-icon to your website if you do not already have one. Consult Apple's guidelines on configuring web applications for more information.

Domain registration

In order to test and accept Apple Pay on the web, you'll need to register any domains you plan to use with Apple. You can do this through the Braintree Control Panel using the instructions below.

You should not register your domain through the Apple Developer Portal. Additionally, you will not need to generate and upload a Payment Processing Certificate for Apple Pay on the web, as these transactions will be processed using our shared certificate.

Sandbox Environment

Register your sandbox domain name in the Braintree Control Panel:

1. Log into your sandbox Control Panel
2. Click on the gear icon in the top right corner
3. Click Processing from the drop-down menu
4. Scroll to the Payment Methods section
5. Next to Apple Pay, click the Options link
6. Scroll to the Web Domains (Safari) section
7. Click the +Add link to the right
8. Enter your fully qualified sandbox domain name
   • The value you enter must match your fully qualified domain name exactly – including the www. if applicable
9. Click the Agree & Add Domain button

Production Environment

1. Log into your production Control Panel
2. Click on the gear icon in the top right corner
3. Click Processing from the drop-down menu
4. Scroll to the Payment Methods section
5. Next to Apple Pay, click the Options link
6. Scroll to the Web Domains (Safari) section
7. Click the +Add link to the right
8. Enter your fully qualified production domain name
   • The value you enter must match your fully qualified domain name exactly – including the www. if applicable
9. Download the domain association file and host it at /.well-known/apple-developer-merchantid-domain-association on your site
10. Click Agree & Add Domain

When Apple verifies a domain, it makes a request to retrieve the domain verification file. Ensure that:

• The file is not served with a 3xx status code. Apple does not support HTTP URL redirects for the domain association file.
• This file is served via HTTPS 1.1
• The HTTP response for this request returns this file as a binary object and not as HTML or plain text
  IMPORTANT

  This file should be served with Content-Type: application/octet-stream to indicate that this is a binary file download.

• Access to this file is not behind a firewall (see Apple documentation on allowing Apple IP addresses)

Creating transactions

You will receive a single-use payment method ID when your user successfully authorizes payment. Once you send this single-use payment method ID to your server, you can create a transaction by passing it into a chargePaymentMethod call.

Collect device data from the client and include the collected client device data via the deviceData parameter inside riskData.

mutation ChargePaymentMethod($input: ChargePaymentMethodInput!) {
  chargePaymentMethod(input: $input) {
    transaction {
      id
      createdAt
      status
      amount {
        value
        currencyCode
      }
      merchantAccountId
      paymentMethodSnapshot {
        ... on CreditCardDetails {
          brandCode
          last4
          expirationMonth
          expirationYear
          cardholderName
          origin {
            type
            details {
              ... on ApplePayOriginDetails {
                bin
                paymentInstrumentName
              }
            }
          }
        }
      }
    }
  }
}

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "1.00",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "deviceData": "device_type"
      }
    }
  }
}

{
  "data": {
    "chargePaymentMethod": {
      "transaction": {
        "id": "id_of_transaction",
        "createdAt": "created_at_date",
        "status": "SUBMITTED_FOR_SETTLEMENT",
        "amount": {
          "value": "1.00",
          "currencyCode": "USD"
        },
        "merchantAccountId": "id_of_merchant_account",
        "paymentMethodSnapshot": {
          "brandCode": "brand_code",
          "last4": "last_4_digits_of_a_account_number",
          "expirationMonth": "MM",
          "expirationYear": "YYYY",
          "cardholderName": "name_of_cardholder",
          "origin": {
            "type": "APPLE_PAY",
            "details": {
              "bin": "bin_number",
              "paymentInstrumentName": "name_of_payment_instrument"
            }
          }
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

The amount you specify in your client-side payment request object should reflect the actual amount you authorize and submit for settlement; transactions will still process in cases where the amount changes during order fulfillment.

Vaulting Apple Pay cards

Apple Pay cards can only be saved to your Vault for specific use cases; see the support article for details. If your use case is supported, you can store a customer's Apple Pay card in your Vault in a few different ways:

• Using the vaultPaymentMethod mutation.
• Including the vaultPaymentMethodAfterTransacting input in your chargePaymentMethod call