Methods for Apple Pay
| Method | Description |
|---|---|
| applepay/echo | Getting parameters for Apple Pay payment initialisation. |
| applepay/init | Initialisation of an Apple Pay payment for applepay@shop. |
| applepay/process | Start of the Apple Pay payment processing. |
The diagram below indicates the progress of Apple Pay payment:
The customer pays for his order on the e-shop. The merchant offers the customer the option to pay using Apple Pay payments, while obtaining the parameters for initialization by calling the operation applepay/echo (0).
When the customer chooses an Apple Pay payment, an ApplePay session is first initialised (the e-shop merchant communicates on Apple servers), then the e-shop initiates a payment at the payment gateway using the applepay/init operation.
Unlike the standard card payment at the gateway, the customer stays at the merchant's e-shop when making an Apple Pay payment; the payment gateway decrypts the necessary payment data (card number and expiry) from the payload sent as part of the applepay/init operation.
The payment gateway performs so-called device fingerprint (2) for some payments. This sends the data from the customer's browser to the card issuer, who subsequently uses this data for the payment authentication. The merchant starts further processing by calling the operation applepay/process (3). The merchant is obliged to make the device fingerprint on the e-shop side within a 1px iframe.
For some payments, a authentication is required from customer payment confirmation (5). As with the device fingerprint, the merchant is obliged to confirm the payment on the e-shop side, opening the iframe or redirecting to top.location based on the parameters received from the payment gateway.
The merchant continuously checks the status of the payment by calling the operation payment/status (4). In case that the payment confirmation is required, after completing the authentication and payment authorization the customer is redirected via returnMethod to e-shop’s returnUrl. After completing the authentication and completing the payment authorization, the merchant displays the payment result to the customer.
The parameters displayed in bold are mandatory for calls.
POST https://api.platebnibrana.csob.cz/api/v1.9/applepay/echo
This operation allows you to get the parameters to initialise Apple Pay payment. The merchant can cache the parameters and use them repeatedly to display the page with the option to pay using Apple Pay.
| Item | Type | Description |
|---|---|---|
| merchantId | String | Merchant ID assigned by the payment gateway. |
| dttm | String | Date and time the request was sent in the format YYYYMMDDHHMMSS. |
| signature | String | Request signature, encoded in BASE64. |
Example of request:
{
"merchantId":"M1MIPS0000",
"dttm":"20220125131559",
"signature":"base64-encoded-signature-of-payment-request"
}| Item | Type | Description |
|---|---|---|
| dttm | String | Date and time of the response in the format YYYYMMDDHHMMSS. |
| resultCode | Number | The result of the operation, see list. |
| resultMessage | String | Text description of the operation result. |
| initParams | Object | Parameters for initialising javascript for Apple Pay, filled in if resultCode is 0. |
| signature | String | Response signature, encoded in BASE64. |
Description of the parameters of the initParams object, the merchant fills in the given value in the unchanged form into js (see below) for Apple Pay initialization.
| Item | Type | Description |
|---|---|---|
| countryCode | Number | ISO 3166-1 alpha-2 country code in which the payment is processed. |
| supportedNetworks | String | The list of accepted card brands that Apple Pay will accept from the customer will be pre-filled by the payment gateway, for example: [ "visa", "masterCard", "maestro" ]. |
| merchantCapabilities | String | List of supported payment authentication methods. It will be pre-filled based on the payment gateway settings, for example: [ "supports3DS" ]. |
Example of return values for applepay/echo operation (applepay@shop has merchant enabled):
{
"dttm":"20220125131601",
"resultCode": 0,
"resultMessage":"OK",
"initParams": {
"countryCode": "CZ",
"supportedNetworks": ["visa", "masterCard", "maestro"],
"merchantCapabilities": ["supports3DS"]
},
"signature":"base64-encoded-response-signature"
}Example of return values for applepay/echo operation (applepay@shop has merchant disabled):
{
"dttm":"20220125131601",
"resultCode": 160,
"resultMessage":"Payment method disabled",
"signature":"base64-encoded-response-signature"
}After the merchant obtains the parameters passed in initParams in response to the applepay/echo call, it inserts/generates a javascript on the e-shop side to initialise the Apple Pay payment.
See also description of payment method Apple Pay.
POST https://api.platebnibrana.csob.cz/api/v1.9/applepay/init
| Item | Type | Description |
|---|---|---|
| merchantId | String | Merchant ID assigned by the payment gateway. |
| orderNo | String | The reference number of the order used for matching payments, which will also be stated on the bank statement. Numeric value, maximum length is 10 digits. |
| dttm | String | Date and time the request was sent in the format YYYYMMDDHHMMSS. |
| clientIp | String | IP address of the customer (his browser) accessing the merchant's e-shop, ipv4 or ipv6 format. |
| totalAmount | Number | Total price in hundredths of the base currency. This value will be displayed on the payment gateway as the total amount to be paid. |
| currency | String | Currency code. Allowed values: CZK, EUR, USD, GBP, HUF, PLN, RON, NOK, SEK. |
| closePayment | Boolean | Indicates whether the payment should be automatically included in the closing and paid. Allowed values: true / false. Optional parameter from version 1.9, default value: true. |
| payload | String | JSON data received by Apple Pay merchant (paymentData attribute in received data from Apple Pay). The merchant encodes as BASE64 and then passes in the payload parameter. |
| returnUrl | String | URL address to which the client will be redirected back to the e-shop after payment is completed if the payment requires confirmation within the payment Authentication. Maximum length 300 characters. When redirecting back to the e-shop, the same parameter set is passed as in the case of returning from the payment gateway when paying by card. |
| returnMethod | String | The method of returning to the e-shop URL. Allowed values POST, GET. The recommended method is POST. |
| customer | Object | Additional purchase data related to the customer. See detailed description of the structure customer. |
| order | Object | Additional purchase data related to the order. See detailed description of the structure order. |
| sdkUsed | Boolean | Indicates whether payment authentication is performed via 3DS SDK (in case of mobile application) or not (payment via browser). Allowed values: true / false. Default value: false. |
| merchantData | String | Any auxiliary data that the merchant passes to the gateway, must be BASE64 encoded. The maximum length after encoding is 255 characters. In case of the "Marketplace" business model, the merchant must identify his retailer using the ID company number. This identifier must be enclosed in square brackets [] and can be placed arbitrarily within the merchantData item. If several retailers participate in the purchase, the ID number values are separated by a comma - e.g. [12345678,87654321]. |
| language | String | Preferred language version to be used in case the payment confirmation is required. Allowed values: cs,en,de,fr,hu,it,ja,pl,pt,ro,ru,sk,es,tr,vi,hr,sl,sv. |
| ttlSec | Number | Payment life setting, in seconds, min. allowed value 300, max. allowed value 1800 (5-30 min). Default value: 1800. Payment lifetime is calculated from the moment of applepay/init call. |
| signature | String | Request signature, encoded in BASE64. |
Example of request:
{
"merchantId":"M1MIPS0000",
"orderNo":"51966",
"dttm":"20220125131559",
"clientIp":"192.0.2.2",
"totalAmount":12300,
"currency":"CZK",
"payload":"base64-encoded-payload-from-applepay",
"returnUrl":"https://shop.example.com/return",
"returnMethod":"POST",
"signature":"base64-encoded-signature-of-payment-request"
}Example of request:
{
"merchantId":"M1MIPS0000",
"orderNo":"51966",
"dttm":"20220125131559",
"clientIp":"192.0.2.2",
"totalAmount":12300,
"currency":"CZK",
"closePayment":false,
"payload":"base64-encoded-payload-from-applepay",
"returnUrl":"https://shop.example.com/return",
"returnMethod":"POST",
"customer": {
"name":"Jan Novák",
"email":"[email protected]",
"mobilePhone":"+420.800300300"
},
"order": {
"Type":"purchase",
"availability":"now",
"delivery":"digital",
"deliveryMode": "0",
"deliveryEmail": "[email protected]"
},
"signature":"base64-encoded-signature-of-payment-request"
}| Item | Type | Description |
|---|---|---|
| payId | String | Unique payment ID (assigned by the payment gateway in the applepay/init operation, contains a 15-character string). |
| dttm | String | Date and time of the response in the format YYYYMMDDHHMMSS. |
| resultCode | Number | The result of the operation, see list. |
| resultMessage | String | Text description of the operation result. |
| paymentStatus | Number | Payment status, see payment lifecycle. |
| statusDetail | String | Detailed status of payment (detailed status), contains, for example, the reason for the refusal to pay, see descriptiom. |
| actions | Object | Structure for transmitting the necessary data for performing device fingerprint. See structure actions. |
| signature | String | Response signature, encoded in BASE64. |
Example of return values for applepay/init operation -- payment successfully initialised:
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131601",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 1,
"signature":"base64-encoded-response-signature"
}Example of return values for applepay/init operation -- payment successfully initialised, including parameters for device fingerprint:
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131601",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 1,
"actions": {
"fingerprint": {
"browserInit": {
"url":"https://example.com/3ds-method-endpoint"
}
}
},
"signature":"base64-encoded-response-signature"
}Example of return values for applepay/init operation -- payment successfully initialised, including parameters for initialising the 3DS SDK for payment authentication:
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131601",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 1,
"actions": {
"fingerprint": {
"sdkInit": {
"directoryServerID":"A000000003",
"schemeId":"Visa",
"messageVersion":"2.2.0"
}
}
},
"signature":"base64-encoded-response-signature"
}In the event of an invalid request, the payment gateway returns a response containing a description of the error. A detailed description is provided on the page API Integration.
POST https://api.platebnibrana.csob.cz/api/v1.9/applepay/process
The operation starts processing an Apple Pay payment.
| Item | Type | Description |
|---|---|---|
| merchantId | String | Merchant ID assigned by the payment gateway. |
| payId | String | PayID obtained when creating an Apple Pay payment using the applepay/init operation. |
| dttm | String | Date and time the request was sent in the format YYYYMMDDHHMMSS. |
| fingerprint | Object | Additional data for payment authentication. See structure fingerprint. |
| signature | String | Request signature, encoded in BASE64. |
Example of request: (applepay@shop, payment performed from the customer's browser)
{
"merchantId":"M1MIPS0000",
"payId":"7624c5e60252@HA",
"dttm":"20220125131615",
"fingerprint": {
"browser": {
"userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.99 Safari/537.36",
"acceptHeader":"text/html,application/xhtml+xml,application/xml;",
"language":"en",
"javascriptEnabled":false
}
},
"signature":"base64-encoded-request-signature"
}Example of request: (applepay@shop, payment performed from a mobile application with integrated 3DS SDK)
{
"merchantId":"M1MIPS0000",
"payId":"7624c5e60252@HA",
"dttm":"20220125131615",
"fingerprint": {
"sdk": {
"appID":"198d0791-0025-4183-b9ae-900c88dd80e0",
"encData":"encrypted-data",
"ephemPubKey": "encoded-public-key",
"maxTimeout": 5,
"referenceNumber":"sdk-reference-number",
"transID":"7f101033-df46-4f5c-9e96-9575c924e1e7"
}
},
"signature":"base64-encoded-request-signature"
}| Item | Type | Description |
|---|---|---|
| payId | String | Unique payment ID (assigned by the payment gateway in the applepay / init operation, contains a 15-character string) |
| dttm | String | Date and time of the response in the format YYYYMMDDHHMMSS. |
| resultCode | Number | The result of the operation, see list. |
| resultMessage | String | Text description of the operation result. |
| paymentStatus | Number | Payment status, see payment lifecycle. |
| statusDetail | String | Detailed status of payment, contains, for example, the reason for the refusal to pay, see description. |
| actions | Object | The structure for transmitting the necessary data for the execution of confirmation within payment authentication. See structure actions. |
| signature | String | Response signature, encoded in BASE64. |
Example of return values for applepay/process operation (without having to make a payment authentication confirmation)
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131618",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 2,
"signature":"base64-encoded-response-signature"
}Example of return values for applepay/process operation (including parameters for confirmation within the payment authentication in the customer's browser)
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131618",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 2,
"actions": {
"authenticate": {
"browserChallenge": {
"url":"https://example.com/challenge-endpoint"
}
}
},
"signature":"base64-encoded-response-signature"
}Example of return values for applepay/process operation (including parameters for confirmation within the payment authentication using the 3DS SDK)
{
"payId":"7624c5e60252@HA",
"dttm":"20220125131618",
"resultCode": 0,
"resultMessage":"OK",
"paymentStatus": 2,
"actions": {
"authenticate": {
"sdkChallenge": {
"threeDSServerTransID":"eeddda80-6ca7-4b22-9d6a-eb8e84791ec9",
"acsReferenceNumber":"3DS_LOA_ACS_201_13579",
"acsTransID":"7f3296a8-08c4-4afb-a3e2-8ce31b2e9069",
"acsSignedContent":"base64-encoded-acs-signed-content"
}
}
},
"signature":"base64-encoded-response-signature"
}The result of authentication and subsequent authorization must be found by a subsequent call to payment/status. Processing times may vary depending on whether payment confirmation is required as part of its authentication:
- if no confirmation is required, the recommended call time is 2-3 seconds after calling
applepay/process, if the payment status is still2(payment in progress), it is recommended to call periodically at intervals of 5 seconds (the total authorisation time depends on the processing of the request in VISA/MC systems and in the worst case it can be up to 60 seconds). - if confirmation is required, it may take several minutes for the customer to confirm the payment and the card issuer completes the authentication. In this case, we recommend calling
payment/statusperiodically at longer intervals, e.g. 30 seconds.