Apple Pay

Initialize and authorize Apple Pay payments.

Note:

  • These messages are not needed when using the menu.
  • Authentication is not required.

For more details see Apple Pay.

Initialize an Apple Pay session

Initialize a new merchant session for a payment with Apple Pay. The session is only valid for 5 minutes and should be started when the shopper clicks on the Apple Pay button.

POST /mobile/applepay/merchants/{merchant_key}/payments/{order_key}/initialize

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

Field Type M Description
validationUrl Url M The validation URL that is generated by the Apple device.
displayName String(1, 255) M The name to display on the the payment sheet.
domainName String(1, 255) M The domain of the website on which the payment will occur. The value must match the domain from which the request is started. If there is a mismatch between this field and the domain that the Apple device determined, then the Apple Pay session will be terminated by the Apple device (with a generic error message or nothing happens).

Response

The returned response is the opaque Apple Pay merchant session in string format. This string needs to be converted to a JavaScript object before it can be passed to the Apple device.

HTTP Status

Status Meaning
201 (Created) Apple Pay merchant session was created successfully.
400 (Bad Request) The request was not valid or no certificate for registration was found.
503 (Service Unavailable) The merchant key and/or order key was incorrect, or requesting the payment session using the validation url failed.

Initialize Apple Pay example Command line:

>  curl \
    -X POST \
    --header 'Content-Type: application/json' \
    https://testsecure.docdatapayments.com/mobile/applepay/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/initialize \
    -d '{
        "validationUrl" : "https://...",
        "displayName"   : "My Shop",
        "domainName"    : "www.myshop.com"
    }'

< Http 201 Created
<    '{
          "..." : "...",
    }'

JavaScript:

function initializeSession(event) {
        var xhttp = new XMLHttpRequest();
        xhttp.onreadystatechange = function() {
            if (this.readyState === 4) {
                if (this.status === 201) {
                    session.completeMerchantValidation(JSON.parse(this.responseText));
                } else {
                    session.abort();
                }
            }

        };

        xhttp.open("POST", "https://testsecure.docdatapayments.com/mobile/applepay/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/initialize", true);
        xhttp.setRequestHeader("Content-type", "application/json");
        xhttp.send('{ "validationUrl":"' + event.validationURL + '"' +
                   ', "displayName": "' + merchantDisplayName + '"' +
                   ', "domainName": "' + window.location.hostname + '"}');
}

Authorize an Apple Pay payment

Performs the authorization via the Payment Service to complete the payment.

POST /mobile/applepay/merchants/{merchant_key}/payments/{order_key}/authorize

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

The request data is passed on as-is received from the Apple device in the on authorize payment event. Modifications are not allowed.

Response

Not applicable.

HTTP Status

Status Meaning
200 (OK) The payment is successfully authorized.
400 (Bad Request) The request was not valid or no payment could not be authorized.

Initialize Apple Pay example

Command Line:

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    https://testsecure.docdatapayments.com/mobile/applepay/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/authorize \
    -d '{
        "..." : "...",
    }'

< Http 200 Ok

JavaScript:

function authorizePayment(event) {
        var xhttp = new XMLHttpRequest();
        xhttp.onreadystatechange = function() {
            if (this.readyState === 4) {
                if (this.status === 200) {
                    session.completeMerchantValidation(JSON.parse(this.responseText));
                } else {
                    session.abort();
                }
            }

        };

        xhttp.open("POST", "https://testsecure.docdatapayments.com/mobile/applepay/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/authorize", true);
        xhttp.setRequestHeader("Content-type", "application/json");
        xhttp.send('{ "validationUrl":"' + event.validationURL + '"' +
                   ', "displayName": "' + merchantDisplayName + '"' +
                   ', "domainName": "' + window.location.hostname + '"}');
}

Initialize an Apple Business Chat session

Initialize a new merchant session for a payment with Apple Business Chat. The session is only valid for 5 minutes and should be started when the shopper requests payment via Apple Business Chat.

POST /mobile/applepay/business/merchants/{merchant_key}/payments/{order_key}/initialize

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

Field Type M Description
displayName String(1, 255) M The name to display on the the payment sheet.

Response

Field Type M Description
merchantSessionAsString String(1, 4096) M The returned response is the opaque Apple Pay merchant session in string format.
paymentGatewayUrl Url M The URL called by Apple Pay to process the payment through the payment provider.
merchantIdentifier String(1, 255) M A unique identifier that represents a merchant for Apple Pay.

HTTP Status

Status Meaning
201 (Created) Apple Pay merchant session was created successfully.
400 (Bad Request) The request was not valid or no certificate for registration was found.
503 (Service Unavailable) The merchant key and/or order key was incorrect, or requesting the payment session using the validation url failed.

Initialize Apple Pay example Command line:

>  curl \
    -X POST \
    --header 'Content-Type: application/json' \
    https://testsecure.docdatapayments.com/mobile/applepay/business/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/initialize \
    -d '{
        "displayName"   : "My Shop"
    }'

< Http 201 Created
<    '{
          "merchantSessionAsString" : "...opaque JSON Object...",
          "paymentGatewayUrl" : "https://testsecure.docdatapayments.com/mobile/applepay/business/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/authorize",
          "merchantIdentifier" : "merchant.demo.cmtelecom.com"
    }'

Authorize an Apple Business Chat payment

Performs the authorization via the Payment Service to complete the payment.

NOTE: This endpoint is called by Apple directly as the Payment Gateway URL.

POST /mobile/applepay/business/merchants/{merchant_key}/payments/{order_key}/authorize

Identifiers

Name Type Description
merchant_key MerchantKey The key of the merchant.
order_key OrderKey The key of the order.

Parameters

Not applicable.

Request

The request data is passed on as-is received from Apple. No modifications are allowed.

Response

Field Type M Description
status Enum(16) M Indicates the status of the transaction. Valid values are STATUS_SUCCESS and STATUS_FAILURE.

HTTP Status

Status Meaning
200 (OK) The payment is successfully authorized.
400 (Bad Request) The request was not valid or no payment could not be authorized.

Authorize Apple Pay example

Command Line:

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    https://testsecure.docdatapayments.com/mobile/applepay/business/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/payments/94D261BBF80E4AC7212B127D3BD2E279/authorize \
    -d '{
        "..." : "...",
    }'

< Http 200 Ok
<    '{
          "status" : "STATUS_SUCCESS"
      }'