References

Available Transaction Statuses for Checkout

Transaction Status	Description	Terminal State?	HTTP Status Code
CREATED	Transaction is created and waiting for the redirectUrl to be accessed.	N	200
PROCESSING	User is redirected to checkout redirectUrl.	N	200
AUTHORIZED	Transaction is authorized with the processor but not yet captured.	N	200
AUTHORIZATION_FAILED	Transaction is not authorized by processor due to technical issues at processor.	Y	200
AUTHORIZATION_DECLINED	Transaction is declined by processor.	Y	200
CAPTURE_PENDING	Transaction is waiting to be captured by gateway/processor. This status is applicable when transactionType is PURCHASE or CAPTURE.	N	200
CAPTURED	Transaction is captured successfully. This status is applicable when transactionType is PURCHASE or CAPTURE.	N	200
CAPTURED_PARTIALLY	Transaction is partially captured. This status is only applicable when transactionType is AUTH. It denotes the status of your original auth transaction.	N	200
PROCESSED	Transaction is fully captured. This status is only applicable when transactionType is AUTH. It denotes the status of your original auth transaction.	N	200
CANCEL_PENDING	Transaction is requested to be cancelled (voided) at processor but not yet cancelled. This status is applicable for all the transactionType i.e. AUTH, PURCHASE, CAPTURE, REFUND	N	200
CANCELLED	Transaction is cancelled (voided). This status is applicable for all the transactionType i.e. AUTH, PURCHASE, CAPTURE, REFUND	Y	200
REFUNDED	Transaction is refunded successfully.	Y	200
ALREADY_REFUNDED	In case of full refund, when refund has already been processed for transaction, but requesting again for refund for same transaction.	Y	200
ABORTED	This is returned in case transaction is cancelled/aborted by customer at gateway page.	Y	200
ERROR_FROM_PG	This is returned in case of any HTTP code other than 200,404 received from processor	N	400, 404, 500
ERROR_CONNECTING_PG	Checkout facing timeout or connectivity issues with processor	N	503
DECLINED	Capture is declined by processor	Y	200
TRANSACTION_NOT_FOUND	The transaction is not found	Y	400
REJECTED	The transaction is rejected by checkout before creating it.	Y	400
INTERNAL_PROCESSING_ERROR	There is an unknown exception occurred in the checkout which wasn’t handled gracefully.	N	500
FAILED	The transaction failed at processor.	Y	200
TRANSACTION_EXPIRED	The redirectUrl of the transaction is expired as user did not access redirect URL of checkout within stipulated time.	Y	400
SETTLED	The transaction is settled.	Y	200

Webhook Events

Below is the list of valid events which can be subscribed to receive webhook call. For subscription of event(s), these needs to be passed in Create Transaction API.

Event
CREATED
PROCESSING
AUTHORIZED
AUTHORIZATION_FAILED
AUTHORIZATION_DECLINED
CAPTURED_PARTIALLY
CAPTURED
CANCELLED
PROCESSED
REFUNDED
ALREADY_REFUNDED
FAILED
ABORTED

Payment Methods

Below is the list of available payment methods that are currently supported in checkout. Permitted payment methods may differ across various APIs.

Available Payment Methods
CARD
SAMSUNGPAY
APPLEPAY

Ecommerce Indicators

Indicator	Description
00	Mastercard not authenticated
01	Mastercard partially authenticated
02	Mastercard Successfully authenticated
05	VISA card successfully authenticated
06	VISA card partially authenticated
07	VISA card not authenticated

Samsung Pay Integration

This section provides the Samsung Pay direct integration steps involved for passing the request to Checkout. Pre-Requisites

Samsung Pay certificates are generated by following the steps mentioned in Overview | Samsung Developer and uploaded into Emirates NBD Pay merchant portal (OneApp).

Integrating Samsung Pay Web Checkout Reference: Web Checkout Integration | Samsung Developer

To process a Samsung Pay Web checkout Transaction, the merchant's client-side application (web browser) interacts directly with the Samsung Pay SDK. Upon user authorization, the SDK provides an encrypted payment payload. This payload is then securely sent to the merchant's backend, which in turn calls the Checkout API to process the transaction. Finally, the client-side application notifies the Samsung Pay SDK of the transaction result. The overall flow involves:

Client-Side SDK Interaction: The merchant's web application loads the Samsung Pay SDK and initiates the payment sheet (SamsungPay.PaymentClient.loadPaymentSheet).
Encrypted Payload Transmission: The encrypted payment credential received from the Samsung Pay SDK is sent from the client-side to the merchant's backend.
Backend API Call: The merchant's backend calls the Create Transaction (Pay by Wallets) API (/checkout/apis/v2/transactions/xpay) with the encrypted payload received from the SDK.
Client-Side SDK Notification: After the backend processes the transaction, the client-side application notifies the Samsung Pay SDK of the final transaction status (SamsungPay.PaymentClient.notify).

Sandbox/ UAT verification: Samsung Pay sandbox app will be provided by Samsung relationship manager and the registered sandbox Samsung pay email will have to be whitelisted for the test service.

Create Transaction (Pay by Wallets) API The merchant's backend initiates the transaction with Checkout using the Create Transaction (Pay by Wallets) API. This API is specifically designed for wallet payments like Samsung Pay and Apple Pay.

Endpoint: [Base Endpoint]/checkout/apis/v2/transactions/xpay

HTTP Method: POST Request Body (Specific to Samsung Pay): The request body for the Create Transaction (Pay by Wallets) API is the same as the standard 'Create Transaction' API, with the following crucial additions/modifications for Samsung Pay:

paymentMethod: This field is mandatory and must be set to SAMSUNGPAY.
payload: This is a mandatory string field. Its value is the entire encrypted payment credential object received directly from the Samsung Pay SDK's SamsungPay.PaymentClient.loadPaymentSheet method. This object should be JSON.stringify'd before being sent in this field.

Example payload structure (as received from Samsung Pay SDK and stringified before sending to your backend):

{ "method": "3DS", "recurring_payment": false, "card_brand": "mastercard", "card_last4digits": "7975", "3DS": { "type": "S", "version": "100", "data": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiJOTjR0ZDZkZE1sNE1QK1RsMjMydXAwUENaeXlLcVhhcGcyVEkxc2g3dzlnPSIsInR5cCI6IkpPU0UiLCJjaGFubmVsU2VjdXJpdHlDb250ZXh0IjoiUlNBX1BLSSIsImVuYyI6IkExMjhHQ00ifQ.AcoO80BsEdCpbYKGbGsxU8XjxokiJlWECvRaWe9CFF7-l2j8pgVaCPpKy5tQfXs_fxm AHSJqvNcK_sdYf3BtzFPTuuvdiSr4qVr4zQfCcMzcMqa8Upf6qi8- UfLiyGeSXel7fOo6X5FinQOPqEoTWUSMToJ478c_TZ2iSD05JaV uFSXKV0Bbi0KGKgRWbw68io_vV4vAXHqTLZiM8BJyWMOlh9wC9jJO4We28AEWytNMsY3AN05odhj4- dw1l6ZQdvsp1ofho7Dfliyw_89FcSYGnc58FKHcLDg_jjYTethReW gydl4WaE7S1l_MQDGEzNAkJPkynHA9qBaZcVA.p2GGovRUP0gs6bpk.y6UeeFxk8fzF-gW9g5JXZBW5dJX xSkxdkU1FZrQNanAzv1RaqrR3oFjRyUG9IU78ga84j_7UJiwIeK6zGWPYzISvyQi5BjevAnXfwhyjQJw3wgNqFH0KmZBHWjMFAr Q5aGlKIjnuL-9U1WzdTV1nPLsvPZqvMOz1PaDkXoDLJnlIH7iSa-M9ODTBUHIhyHUldBsDJYv 15dBBsOHrBjxpAXlDEp0ahEDxt4WYnzKu-sawViDgA.-VB8E7ZNkVzGrdjwzGQCXQ" }, "certificates": [ // ... (array of certificate objects) ] }

(Note: The actual payload content is an encrypted object provided by the Samsung Pay SDK, and its internal structure is typically opaque to the merchant's backend, which simply forwards it to Checkout.) Response Body: Refer to Page 27 for the response format of the 'Create Transaction (Pay by Wallets)' API."

Apple Pay Integration

This section provides the direct integration of Apple Pay with the Checkout APIs.
Pre-Requisites Reference: Apple Pay on the Web | Apple Developer Documentation Merchant has a Apple pay developer account and payment processing certificates are created in Apple pay. Merchant uploads the payment processing certificate on Emirates NBD Pay merchant portal (OneApp). Merchant has verified their website.

Integrating Apple Pay on web Refer Apple Pay on the Web Demo for sample integration options.

Apple Pay JS could be used for loading the Apple Pay payment sheet on the merchant website. Once the encrypted payload is received from Apple Pay JS the merchant’s backend can pass that payload to Checkout API for completing the payment.

Following are the detailed description of Payment object data received from Apple Server.

Key	Value	Description
Data	payment data dictionary, Base64 encoded as a string.	Encrypted payment data.
Header	header dictionary	Additional version-dependent information is used to decrypt and verify the payment.
signature	detached PKCS #7 signature, Base64 encoded as string.	Signature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm.
Version	String	Version information about the payment token. The token uses EC_v1 for ECC-encrypted data, and RSA_v1 for RSA-encrypted data.

The header contains the following keys and values:

Key	Value	Description
applicationData	SHA–256 hash, hex encoded as a string	Optional. Hash of the applicationData property of the original PKPaymentRequest object. If the value of that property is zero, this key is omitted.
ephemeralPublicKey	X.509 encoded key bytes, Base64 encoded as a string	Ephemeral public key bytes. EC_v1 only.
wrappedKey	A Base64 encoded string	The symmetric key wrapped using your RSA public key. RSA_v1 only.
publicKeyHash	SHA–256 hash, Base64 encoded as a string	Hash of the X.509 encoded public key bytes of the merchant’s certificate.
transactionId	A hexadecimal identifier, as a string	Transaction identifier, generated on the device.

Sample Apple Pay request payload

{
    "amount": "400",
    "currency": "AED",
    "notes": {
        "location": "Dubai"
    },
    "description": "Demo Payment",
    "app": {
        "appUtr": "merc5984444545545801",
        "redirectUrl": "https://www.pinelabs.com",
        "webhook": "https://pinelabs.com/transactions/testwebhook",
        "events": [
            "AUTHORIZED",
            "CANCELLED",
            "CAPTURED",
            "PROCESSED",
            "REFUNDED"
        ]
    },
    "paymentMethod": "APPLEPAY",
    "transactionType": "AUTH",
    "orderId": "ORDER9876",
    "refundConfig": {
        "type": "PARTIAL",
        "minAmount": "100"
    },
    "customerDetails": {
        "firstName": "Ranjit",
        "lastName": "Das",
        "isdCode": "+91",
        "mobileNumber": "9876543434",
        "email": "[email protected]",
        "shippingAddress": {
            "firstName": "John",
            "lastName": "Joe",
            "isdCode": "+91",
            "mobileNumber": "9876543434",
            "email": "[email protected]",
            "addressLine1": "19",
            "addressLine2": "Unterschweinstiege 8",
            "city": "Frankfurt",
            "state": "hamburg",
            "countryCode": "DE",
            "pinCode": "60549"
        },
        "billingAddress": {
            "addressLine1": "19",
            "addressLine2": "Unterschweinstiege 8",
            "city": "Frankfurt",
            "state": "hamburg",
            "countryCode": "DE",
            "pinCode": "60549",
            "isShippingAddressSame": false
        }
    },
    "payload": "{\"data\":\"pqg2udpVzF3reoc3ZRNlftsontQeRgGhv7PGv2xZEUWDu6VJ+k99wJS4sddX3bETBKs9uTDbxIISSThVo7YFR+uh5g0RD2fdVj/lpl2vlcbJWULacTVRi3/Qf1m0ongycPughIeR7a6SKbvAYjeO7z+87NV3QwUPOgdJAeDJf2ErdlITRsFxSZdLrkrOHeKjuG/Mlp0WoksHqptIZHx3h8/GVoJqknWGd/hYlG0P6/ihYLkS3wxfSDH5XE7tJrytVG8E4UZS8yXSoMlS0YcL6dhnpuQ6h3wmjmRO21eyvC1zmX7ZKzbvBcvlbaRRr10YT5gqvmWqZP10bodmaT2NyHqeVm6gdzoOKVOZEubwUL+FNQUdzPdLHPn4oao388i948EeZbDdvoxCZApZWw==\",\"signature\":\"MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgAYJKoZIhvcNAQcBAACggDCCA+QwggOLoAMCAQICCFnYobyq9OPNMAoGCCqGSM49BAMCMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0yMTA0MjAxOTM3MDBaFw0yNjA0MTkxOTM2NTlaMGIxKDAmBgNVBAMMH2VjYy1zbXAtYnJva2VyLXNpZ25fVUM0LVNBTkRCT1gxFDASBgNVBAsMC2lPUyBTeXN0ZW1zMRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABIIw/avDnPdeICxQ2ZtFEuY34qkB3Wyz4LHNS1JnmPjPTr3oGiWowh5MM93OjiqWwvavoZMDRcToekQmzpUbEpWjggIRMIICDTAMBgNVHRMBAf8EAjAAMB8GA1UdIwQYMBaAFCPyScRPk+TvJ+bE9ihsP6K7/S5LMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDIwggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMB0GA1UdDgQWBBQCJDALmu7tRjGXpKZaKZ5CcYIcRTAOBgNVHQ8BAf8EBAMCB4AwDwYJKoZIhvdjZAYdBAIFADAKBggqhkjOPQQDAgNHADBEAiB0obMk20JJQw3TJ0xQdMSAjZofSA46hcXBNiVmMl+8owIgaTaQU6v1C1pS+fYATcWKrWxQp9YIaDeQ4Kc60B5K2YEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggGHMIIBgwIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCFnYobyq9OPNMAsGCWCGSAFlAwQCAaCBkzAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yNTA4MjIwNzI2MTdaMCgGCSqGSIb3DQEJNDEbMBkwCwYJYIZIAWUDBAIBoQoGCCqGSM49BAMCMC8GCSqGSIb3DQEJBDEiBCD2rE/yDJRn7tzq+P1ufO/1/xySMZ0epl+ZtDSato9KnDAKBggqhkjOPQQDAgRGMEQCIC3t2u4JD4Nl044cT/qPjViNGD7aVXrtnTRqgiio7CusAiBD9NBMltA+21zHSfsgJkDu15KdtBTDp1NUdrMiMOTvAwAAAAAAAA==\",\"header\":{\"publicKeyHash\":\"7ylnTXmqDoiE7uwKOHSGY6IIvMdTXlGZenEBCkd5OPQ=\",\"ephemeralPublicKey\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEnIhhaM5+CfF9EnfjfaASZfVLZr92qwE8x87DNEN3MBaaKEA7n7OT7D8UOIcqw/Tl529dSJ9z5n2dEltfjV0Fcg==\",\"transactionId\":\"a79ccbcaab2218f6ec6aa0293ff436123f93e26133863ad064948ceb3c26486e\"},\"version\":\"EC_v1\",\"paymentMethod\":{\"displayName\":\"MasterCard 0049\",\"network\":\"MasterCard\",\"type\":\"credit\"},\"transactionIdentifier\":\"A79CCBCAAB2218F6EC6AA0293FF436123F93E26133863AD064948CEB3C26486E\"}"
}

Response Body: Refer to the response format of the 'Create Transaction (Pay by Wallets)' API."

Test cards

Card Brand	Number	CVV
Visa	4111 1111 1111 1111	123
Visa	4622 9431 2701 3705	838
Visa	4622 9431 2701 3713	043
Visa	4622 9431 2701 3721	258
Visa	4622 9431 2701 3739	942
Visa	4622 9431 2701 3747	370
Mastercard	2222 4200 0000 1113	123
Mastercard	2222 6300 0000 1125	123
Mastercard	5555 5555 5555 4444	123
American Express	3782 8224 6310 005	123