Apple Pay integration guide

Apple PayApple Pay Apple Pay is a payment provider allowing consumers to pay using their payment methods saved to their Apple Pay account. This section is intended to help you implement Apple Pay based on your preferred integration workflow.

Services and compatibility

Payment method gateway nameApple Pay through Authorize.net
Apple Pay through Cybersource
Supported transaction types
Supported integration methods
Supported processing currenciesFor Apple Pay through Authorize.net:
  • CAD, USD
For Apple Pay through Cybersource:
  • AUD, CAD, USD
Webhook event types
  • TRANSACTION_AUTHORIZED
  • TRANSACTION_CAPTURED
  • TRANSACTION_REFUNDED
  • TRANSACTION_SETTLED
  • TRANSACTION_VOIDED
Supported devicesDevices compatible with Apple Pay

Configuration

In order to use Apple Pay with your merchant account, you must first work with integrations to add it to your account.

Then, you must go through the following information and steps.

Prerequisites

In order to configure your account for use with Apple Pay, you need the following:

Configuration tasks

After you complete the above prerequisites, you are ready to begin the configuration tasks:

Note: When integrating Apple Pay to multiple environments, you need to verify the domain for each environment. However, you only need to complete the first three tasks one time.

Create an Apple Pay merchant ID

Follow these steps to create an Apply Pay merchant ID.

  1. Go to the Apple Developer portal.
  2. Sign in to your account.
  3. Select Certificates, IDs & Profiles.
  4. Select Identifiers.
  5. On the Identifiers screen, click the + (plus sign) button.
  6. Click the Merchant ID radio button, then click Create.
  7. Fill in the required fields.
  8. Copy or note the Merchant ID. You need it when you create the payment processing certificate and the merchant identity certificate.

Create a payment processing certificate

Contact Integrations Support to provision a supported gateway and get a payment processing certificate.

Follow these steps to upload the certificate to Apple Pay.

  1. Go to the Apple Developer portal.
  2. Sign in to your account.
  3. Select Certificates, IDs & Profiles.
  4. Click the Upload button and upload the certificate.

Create a merchant identity certificate

In this task, you create the certificate signing request (CSR) for a Merchant Identity Certificate. (The steps below are adapted from Apple's tutorial on how to create a certificate signing request.)

  1. Launch Keychain Access located in /Applications/Utilities.
  2. Choose Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority.
  3. In the Certificate Assistant dialog, type an email address in the User Email Address field. (Any email address works.)
  4. Type the Common Name. You may pick a common name of your choice. For example, "Nexio Apple Pay Merchant Cert".
  5. Leave the CA Email Address field empty.
  6. Choose Saved to disk, and click Continue.
  7. The default Save As name is something like CertificateSigningRequest.certSigningRequest. You can name it whatever you want. For example, NexioApplePayMerchant.certSigningRequest.

Successful completion of the above steps creates the following files:

  • CSR (saved to the location you selected with the name you chose in step 7)
  • A private key (saved to the KeyChain tool, with the same name as the Common Name you chose in step 4)
  • A public key (saved to the KeyChain tool, with the same name as Common Name you chose in step 4)

Upload the CSR to Apple's developer portal

  1. Go to the Apple Developer Portal.
  2. Click to expand the App IDs dropdown menu (in the top right).
  3. Select Merchant IDs.
  4. Select the desired merchant ID. (If you do not see the merchant ID, create it now).
  5. Under "Apple Pay Merchant Identity Certificate", click Create Certificate.
  6. Upload the merchant identity certificate you created previously.
  7. Download the certificate. Name it NexioApplePayMerchant.cer.

Export the private key

  1. Go back to the KeyChain tool on your Apple computer.

  2. Right-click on the private key and select Export.

  3. Export as 'NexioApplePayMerchantKey.p12'.

    Note: If "p12" is grayed out, you chose the wrong key. Select a different key.

Convert the format of the private key

Convert the format of the private key you downloaded in step 3 of Export the private key. Convert it first to a PEM certificate, then to a Base64 string.

  1. Open the terminal.

  2. Navigate to the directory where the private key is saved (Documents, by default): cd Documents.

  3. Create the privatePem by typing the following in the terminal:

    openssl pkcs12 -in NexioApplePayMerchantKey.p12 -out NexioApplePayMerchantKey.pem -nodes -clcerts

  4. Convert .pem file to a Base64 string: base64 NexioApplePayMerchantCRT.pem

Convert the format of the Apple Pay certificate

Convert the format of the certificate you downloaded in step 3 of Convert the format of the private key. Convert it first to a PEM certificate, then to a Base64 string.

  1. Navigate to the directory where the private key is saved (Downloads, by default): cd Downloads.

  2. Create the certPem by typing the following in the terminal:

    openssl x509 -inform DER -outform PEM -in NexioApplePayMerchant.cer -out NexioApplePayMerchantCRT.pem

  3. Convert the files to base64 strings: base64 NexioApplePayMerchantCRT.pem

Verify your domain

Follow these steps to verify the domain to be used with Apple Pay. If you have multiple domains (for example, for development environments) repeat these steps for each.

  1. Go to the Apple Developer portal.
  2. Click Merchant Domains.
  3. Click Add Domain.
  4. Enter the URL of the domain you plan to use. Click Save.
  5. Apple Pay will provide you with a text file to download and a URL. Download the file and copy the URL, you will use both in the next step.
  6. Host the text file at the exact URL provided by Apple.

Provide your configuration settings to Integrations Support

After you have completed all of the previous tasks, contact Integrations Support to provide them with the following:

If you have multiple verified domains for testing purposes, you can dynamically choose the domain by providing the appropriate value for the data.applePayDomain parameter when you request a one-time-use token. (For more information, see step 4 of the Button Iframe URLs tutorial).

Troubleshoot the configuration or platform

Apple Pay and Apple Developer use different platforms. You need to accept the terms and conditions on each account separately.

If you are experiencing difficulties on one of the platforms, please contact the appropriate support:

Required fields

The following table shows the required and optional fields for Apple Pay transactions in the Create APM one-time-use token request.

FieldRequired?Description
data.amountYesThe transaction amount.
data.currencyYesThe three-character ISO currency code for the transaction.
For Apple Pay through Authorize.net (applePayAuthNet), supported currencies are CAD and USD.
For Apple Pay through Cybersource (applePayCyberSource), supported currencies are AUD, CAD, and USD.
data.customer.orderNumberYesThe order number.
data.customer.firstNameYesThe customer's first name, as it is set for the payment method.
data.customer.lastNameYesThe customer's last name, as it is set for the payment method.
data.customer.emailYesThe customer's email address.
data.applePayDomainConditionalAllows you to run a transaction through a verified domain other than the default (for example, for a test environment). For specific details related to this parameter, see the Create APM one-time-use token endpoint.
data.descriptionConditionalA description of the transaction.
Required for applePayCyberSource.
Optional for applePayAuthNet.
data.customer.billToAddressOneConditionalThe street address for the customer.
Required for applePayCyberSource.
Optional for applePayAuthNet.
data.customer.billToCityConditionalThe city for the address record.
Required for applePayCyberSource.
Optional for applePayAuthNet.
data.customer.billToStateConditionalThe state or province on file with the payment provider. (If in the US, this must be the two-character state abbreviation).
Required for applePayCyberSource.
Optional for applePayAuthNet.
data.customer.billToPostalConditionalThe postal code on file.
Required for applePayCyberSource.
Optional for applePayAuthNet.
data.customer.billToCountryConditionalThe two-character (Alpha-2) ISO country code.
data.customer.billToAddressTwoNoAdditional street address information, if required.
data.customer.billToPhoneNoThe billing phone number.
data.customer.shipToAddressOneNoThe shipping address, if different from the billing address.
data.customer.shipToAddressTwoNoAdditional shipping address information, if required.
data.customer.shipToCityNoThe shipping city.
data.customer.shipToStateNoThe shipping state or province. (If in the US, this must be the two-character state abbreviation).
data.customer.shipToPostalNoThe shipping postal code.
data.customer.shipToCountryNoThe two-character (Alpha-2) ISO shipping country code.
data.customer.shipToPhoneNoThe shipping phone number.
data.cart.items[n].descriptionNoA description of the item.
data.cart.items[n].priceNoThe price per item
data.cart.items[n].quantityNoThe quantity sold.
data.cart.items[n].itemNoItem number or code.
data.cart.items[n].typeNoThe transaction type.
data.customerRefNoCustomer identifier. You can use this field to pass a customer ID to the APM or to manage user subscriptions.
data.descriptorNoInclude this parameter to dynamically change the descriptor on the customer's statement.
Optional for applePayCyberSource.
Not allowed for applePayAuthNet.
data.paymentMethodNoThe identifier for the alternative payment method. Use this parameter when you want to only return the Apple Pay iframe button URL (rather than data for all payment methods associated with the account).

The value to use is applePayAuthNet or applePayCyberSource, depending on your integration.
isAuthOnlyNoSet to true to run an auth only transaction.
processingOptions.merchantIdNoThe Nexio merchant ID (MID).
processingOptions.paymentOptionTagNoA custom value used to route transactions to a specific gateway or merchant account.
uiOptions.cssNoThe URL where your custom CSS file is hosted.

Example requests

The following are example one-time-use token requests for Apple Pay.

Example Request for Apple Pay through Authorize.net
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "paymentMethod": "applePayAuthNet",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  }
}'
Example Request for Apple Pay through Cybersource
curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "description": "test purchase",
    "paymentMethod": "applePayCyberSource",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "billToAddressOne": "123 Test St",
      "billToCity": "Testerville",
      "billToState": "UT",
      "billToPostal": "12345",
      "billToCountry": "US"
    }
  }
}'

A successful request returns a response similar to the following:
Example 200 Response with several payment methods
{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [...],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
    },
    {
      "paymentMethod": "applePayAuthNet",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayAuthNet"
    },
    {
      "paymentMethod": "applePayCyberSource",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayCyberSource"
    }
  ]
}

For the multi iframe integration method: You use the expressIFrameUrl value in the steps for the transaction.

For the individual iframe option: You use the buttonIFrameUrls.url of the Apple Pay APM for the transaction. Also, you use the scriptUrl.

Transaction types and integration methods

Regardless of the integration method workflow you implement, consumers are redirected to Apple Pay to complete their transactions.

Nexio supports the following transaction types for Apple Pay:

Testing Data

For testing data, see Apple Pay’s Sandbox Testing page.

Response handling

In the one-time-use token request, Apple Pay gets returned in the paymentMethod parameter as applePayAuthNet or applePayCyberSource.

Nexio responds with transaction results in event messages.

In addition to event messages, if your merchant account is configured to receive webhooks, Nexio provides responses to the webhook URLs that have been registered. For further explanation of the webhook event types, see the webhook Event types table.

For Apple Pay, these are the possible webhook event types:

  • TRANSACTION_AUTHORIZED
  • TRANSACTION_CAPTURED
  • TRANSACTION_REFUNDED
  • TRANSACTION_SETTLED
  • TRANSACTION_VOIDED

For information about how to run each of the integration workflows, see Transaction types and integration methods above.

Status workflows

The status of a successful transaction with Apple Pay varies, depending on the options you choose.

SaleWhen isAuthOnly is false, successful sale transactions have the following statuses:
  • pending*
  • settled
Auth onlyWhen isAuthOnly is true, successful sale transactions have the following statuses:
  • authOnlyPending
  • authOnly
CaptureSuccessful capture transactions have the following status:
  • settled
VoidSuccessful void transactions have the following status:
  • voided
RefundSuccessful refund transactions have the following status:
  • settled

*Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the table).

Next steps

Now, you are ready to get started with running transactions:

If you have any additional questions or feedback, see Contact us.


Did this page help you?