Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

Apple Pay

Apple Pay provides a secure payment method that can simplify your customer's checkout experience both in-app and on the web. Apple Pay stores payment information on the user's device and authenticates the user via Face ID or Touch ID.

Apple Pay is PSD2 SCA-compliant meaning you don't need to utilise 3-D Secure before authorising the payment. The user will be presented with a payment sheet, here they can choose which of their stored cards to use and provide contact, billing and shipping data without needing to fill out any forms.

Apple Pay works with many of the major credit and debit cards from the leading banks on specific devices and browsers. Refer to Apple's documentation for:

How it works

  1. You request the encrypted payload from your app or browser
  2. Apple returns a token value that contains an encrypted payload
  3. You send the token to your server and Base64 encode it
  4. You submit a request into Acquired’s Card API containing the token value
  5. Acquired processes the payment and returns a payment response
  6. You inform the customer of the transactions outcome

Setup

Before you get started you will need:

  1. A direct integration into the Acquired API
  2. For Apple Pay on the Web, you can use our certificate or you can use your own
  3. For in-App, you are required to create a payment processing certificate

Certificate Management

Use our certificate (Web Only)

When processing Apple Pay on the Web, you can use our certificates. This means you do not require an Apple Developer account and can avoid the complex process of certificate management.

Step 1. Login to the Hub

Step 2. Navigate to the Settings tab, select Payment Methods and then Apple Pay

Step 3. Under Web Domains, hit "+ Add Domain"

Step 4. Follow the instructions in the pop-up and select "Register Domains"

In the Apple Pay developer documentation, since you don't have a merchantIndentifier, Merchant Certificate or Payment Processing Certificate you will need to do the following:

For testing of Apple Pay Web using our certificate you must ensure your device is setup for Sandbox Testing or payments will fail.

Setting the merchantIdentifier

When we register your domains with Apple, we will set an internal merchantIdentifier for your account.

When setting the merchantIdentifier for canMakePaymentsWithActiveCard('') or any other request where it is required please use your assigned company_id value.

Providing Merchant Validation

On your onvalidatemerchant event handler, as you do not have a merchant or payment processing certificate, we will perform Requesting an Apple Pay Payment Session. You will instead request the merchantSession from us via API:

Endpoints:
Testing (https://qaapi.acquired.com/api.php/status)
Production (https://gateway.acquired.com/api.php/status)
Request Hash:
Concatenate: timestamp + status_request_type + company_id + company_hashcode. 
{
  "timestamp": "20210722034034",
  "company_id": "113",
  "company_pass": "secret",
  "request_hash": "775fcafe9dd.....",
  "transaction": {
    "status_request_type": "APPLE_SESSION",
    "domain": "mystore.example.com",
    "display_name": "myStore",
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession"
  }
}
Parameter Format Length Description
status_request_type
Required		 enum Value should be set to APPLE_SESSION.
domain
Required		 string 1-254 The domain you are completing the Apple Pay request from - it should already be registered with us.
display_name string 1-64 A string of 64 or fewer UTF-8 characters containing the canonical name for your store, suitable for display.
validation_url
Required		 string The URL from the event’s validationURL property
Response Hash:
Concatenate: timestamp + response_code + company_id + company_hashcode. 
{
  "timestamp": "20210722034035",
  "response_code": "1",
  "response_message": "Success"
  "company_id": "113",
  "response_hash": "0d38bb26ed6485.....",
  "merchant_session": "{{Base64}}"
}

When you Base64 decode the "merchant_session" value you will find the merchantSession which you can pass in your completeMerchantValidation method. You can use the merchant session object a single time. It expires 5 minutes after it is created.

Create a payment processing certificate

If you are processing Apple Pay in-App, including through the Acquired SDK, before getting started you will require an Apple Developer account and to configure your environment.

Once you have created your Merchant Identifier, to create a payment processing certificate follow these steps:

Step 1. In your Apple Developer account navigate to here

Step 2. Under Services, select to create an Apple Pay Payment Processing Certificate and select a Merchant ID

Step 3. When it asks you to Upload a Certifiate Signing Request, login to the Hub and navigate to Setting > Payment Methods > Apple Pay

Step 4. under iOS Certificates select Add Certificate

Step 5. enter the Merchant ID selected in Step 2 and follow the instructions on the pop-up

Integrate with Apple Pay

Apple Pay > Web

Support Apple Pay on your website.

Get Started

Android Apple Pay > in-App

Support Apple Pay on your iOS App.

Get Started

Set the supportedNetworks property

Acquired supports Apple Pay payments from Visa, MasterCard and Amex cards, you can define these accepted card networks in the ‘supportedNetworks’ property when integrating with Apple Pay.

supportedNetworks: ['visa', 'masterCard', 'amex'];

Set the merchantCapabilities property

Acquired only supports the 3DS ‘merchantCapabilities’ option, you should define this within your Apple Pay integration.

merchantCapabilities: ['supports3DS'];
For Apple Pay on the Web if you are using our certificate you need to follow these steps for onvalidatemerchant..

Integrate with Acquired.com

Once you’ve successfully integrated your web application or app with Apple Pay and are able to send the returned payload to your server then you’re capable of submitting Apple Pay transactions to Acquired via our API.

Making a Payment

Step 1: at the end of the Apple Pay process an encrypted payload will be returned to your application, an example of this can be found below:

{"version":"EC_v1","data":"Xnt8nkb239ci1iTWXbR1v7JvIN6YiaMNVpdwTAZad6WG1WttpkDSEpJ2fl3/taLrDic8najgOFUbtdgBfX2Nj3Hpd6ztAHzfSN6THEVxsOaQq3MVna7SsL6cAcnXuTfGvZdBOFWrXRfxkKC4Xksq3vvi8SepeF5aeF01FeAz8CltIgQjh2d3RFQcUkSkjyhNZcLo0Of50lQ/1dIWQ+cpqdjYPbpFWHLjYHBoSgdmKbaZ61+CoahJsATjT04+ojV60jzTPtctDkNE4Ua1F1GYdgZTRys2HYYNLh8ygPRdj6BY2m5VdDSbAkyL5Pb99s0ren3KeW0XOUrL1GT9+xZL3Th1hRMcvwkSuwFYb/h7ytBNslWM3FqYqmdOKm7wctEiLxfRLg/rX0Ql5jTZHcyuPyXAaVK7IjrcbvE3FqiNhO2+z4Mk341eEVmlOLLR/CaKwGZv7uaS73F/jTITDB2tElQ1ottoLS3S9d2p9ktcnbZHKk/kB73VG0p70HH3h/NCtfFeUR3gs7zzvrbNEDWmSn73b4p4R4VkICM5+buJhG11E0LOnb5WHEtiOb8=","signature":"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","header":{"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8AQ5oAod5t77APoHAz9Oly50EZ0JKE3h7TWS5TUiG45v6gS4/b1Gc9QJmxcVRYTG+TK1Zcs1o5gUqImNiqBCLQ==","publicKeyHash":"6UZk8/cmKAy6cieeTDk7rCXxMR6LPUowgjUb4+vpomI=","transactionId":"7bc651793cf69c1ff73c7a13dc8ed00952d124d85289277cf92457a88574ee48"}}

To simplify the integration process, base64 this entire payload which you can then pass through to us in the API in the payment.token field to be decrypted by us.

Step 2: using the Acquired API in the same way as a card payment, submit the base64 encoded string value through to us in the payment.token field of your request.

{
  "timestamp": "20210512203331",
  "company_id": "113",
  "company_pass": "secret",
  "request_hash": "f0a18260b08a0bfacb.....",
  "transaction": {
    "merchant_order_id": "2021051208333182906",
    "transaction_type": "auth_capture",
    "amount": "20.00",
    "currency_code_iso3": "GBP"
  },
  "payment": {
    "method": "apple_pay",
    "token": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiWG50OG5rYjIz....",
    "card_category": "debit",
    "display_name": "Visa 1233",
    "network": "visa"
  }
}
Parameter Format Length Description
method
Required		 enum Value should be set to apple_pay.
token
Required		 string Base64 encoded payments as detailed in Step 1.
card_category enum The "type" value passed back from Apple detailed here.
display_name string 0-50 The "displayName" value passed back from Apple detailed here.
network string 0-20 The "network" value passed back from Apple detailed here.
Note: if you want to process your card authorisation request including AVS data, you will need to request requiredBillingContactFields in your Apple Pay request when loading the payment sheet - see here.

Step 3: we will respond in the normal way so if you have an existing card payments integration, nothing will change just handle the response_code value and display a response to your customer.

Testing Apple Pay

In simulate different responses from our API to test Apple Pay, you will need to update the "amount" value in your request as detailed below:

For a successful response - you can submit any other value..
Amount Response Code Response Message
11.02 101 Declined
11.03 301 Declined: Insufficent Funds
11.04 402 Declined: Lost or Stolen Card