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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

FieldTypeMDescription
validationUrlUrlMThe validation URL that is generated by the Apple device.
displayNameString(1, 255)MThe name to display on the the payment sheet.
domainNameString(1, 255)MThe 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

StatusMeaning
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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe 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

StatusMeaning
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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

FieldTypeMDescription
displayNameString(1, 255)MThe name to display on the the payment sheet.

Response

FieldTypeMDescription
merchantSessionAsStringString(1, 4096)MThe returned response is the opaque Apple Pay merchant session in string format.
paymentGatewayUrlUrlMThe URL called by Apple Pay to process the payment through the payment provider.
merchantIdentifierString(1, 255)MA unique identifier that represents a merchant for Apple Pay.

HTTP Status

StatusMeaning
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

NameTypeDescription
merchant_keyMerchantKeyThe key of the merchant.
order_keyOrderKeyThe key of the order.

Parameters

Not applicable.

Request

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

Response

FieldTypeMDescription
statusEnum(16)MIndicates the status of the transaction. Valid values are STATUS_SUCCESS and STATUS_FAILURE.

HTTP Status

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