Initialize and authorize Apple Pay payments or Apple Business Chat payments.

Note:

These API requests/interactions are not needed when using the provided menu by CM.com.
Authentication is not required for these API resources.

For more details see Apple Pay and Apple Messages for Business.

Initialize 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 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.

Authorize 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 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 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"
      }'