Auth

---

• Description： Create auth payment, for process sale payment using credit card payment method
• Path： /direct/auth
• Method： POST
• Request Header： Content-Type: application/json

Request Parameters

Parameter	Type	Required/optional	Default	Description
merchantId	string	Required		Merchant identifier
amount	number	Required		Order amount
currency	string	Optional	HKD	3-Letters ISO currency code, supports HKD, USD
merchantReference	string	Required		An unique reference to identify this order
ddcSession	string	Conditional		SessionId value obtained from the postMessage of Cardinal, only required for credit card payment
notifyUrl	string	Optional		An API URL in merchant's backend to receive notification
referer	string	Optional		The website URL where customers are visiting it from
userAgent	string	Optional		The characteristic string of the browser application, common format: User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>
postLink	string	Optional		The URL posted the payment request
merchantSite	string	Optional		Merchant's own website URL
card	object	Conditional		Credit card data object, only required for credit card payment
card.cardNumber	string	Required		Card number
card.expiryMonth	string	Required		Card expiry month, format MM
card.expiryYear	string	Required		Card expiry year, format in YYYY
card.securityCode	string	Required		3-digits CVC/CVV number, usually placed at the back of the credit card
card.nameOnCard	string	Required		Cardholder name
cardAddress	object	Optional		For AVS verification purpose, credit card issued from US or CA are highly suggested to provide
cardAddress.postalCode	string	Optional		Postal code of the card issuing location
cardAddress.countryCode	string	Optional		Country code of the card issuing location, in ISO-3166 alpha-2 format
lineItems	array	Required
lineItems[index].quantity	number	Required		Number of items, must be an integer
lineItems[index].priceData	object	Required		Price data object with details
lineItems[index].priceData.unitAmount	number	Required		Unit amount of the item
lineItems[index].priceData.name	string	Required		Name of the item

DDCSession

The ddcSession value is required for conducting 3DS process. Non-3DS payment is deprecated.

Apple Pay Parameters

Parameter	Type	Required/optional	Description
applePay	object	Conditional	Apple Pay data object, only required for Apple Pay
applePay.cardType	string	Required	Card type of the order, obtained from payment.token.paymentMethod.network, supports VISA, MASTER
applePay.data	string	Required	Apple Pay data, obtained from payment.token.paymentData
applePay.ephemeralPublicKey	string	Required	Apple Pay ephemeralPublicKey, obtained from payment.token.paymentData
applePay.publicKeyHash	string	Required	Apple Pay publicKeyHash, obtained from payment.token.paymentData
applePay.signature	string	Required	Apple Pay signature, obtained from payment.token.paymentData
applePay.transactionId	string	Required	Apple Pay transactionId, obtained from payment.token.paymentData
applePay.version	string	Required	Apple Pay version, obtained from payment.token.paymentData

Google Pay Parameters

Parameter	Type	Required/optional	Description
googlePay	object	Conditional	Google Pay data object, only required for Google Pay
googlePay.cardType	string	Required	Card type of the order, obtained from paymentData.paymentMethodData.info.cardNetwork, supports VISA, MASTER
googlePay.protocolVersion	string	Required	Google Pay protocolVersion, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signature	string	Required	Google Pay signature, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signedMessage	string	Required	Google Pay signedMessage, obtained from paymentData.paymentMethodData.tokenizationData.token

note

The applePay and googlePay object is added to the PayAPI request body as a separate key instead of added to the request key. Hence, the JSON used for signing does not include the object data.

Example request：

Credit Card

{

"request": "{\"currency\":\"HKD\",\"amount\":50,\"merchantId\":3,\"paymentType\":\"CARD\",\"merchantReference\":\"merRef1657856553027\",\"notifyUrl\":\"https://www.bbmsl.com/notify\",\"ddcSession\":\"0_96fd0b31-6f96-4a41-84c9-ef594f277db9\",\"card\":{\"cardNumber\":4000000000000002,\"expiryMonth\":10,\"expiryYear\":2023,\"nameOnCard\":\"3DS\",\"securityCode\":368},\"lineItems\":[{\"priceData\":{\"name\":\"Book\",\"unitAmount\":50},\"quantity\":1}]}",

"signature": "tvYd4uBhykzN7Q74lcGq3rA/0ZbEWRSgfrAbThyGgXZEEcjjaIB65UHHN9zCgi1G3s8SXwgLgLd2XkMK9W1VhVMAKe2X+IfaGmImNF6o8srekqbty3R2ohNUkqK3OszcDC3Q4/XyoXmlQAQNIf5OU1v5yQhwAKP1b/hFG7lMvT/gLx7WLno26LfO9vo9GrB+++x5VZyzpAjtdhV460ue1bDY9D+AdpJDlQvlwsKSDQGtiidl1680EVgGmG698Od5Fr60/JIWTP0utXQF/JrNn2onBZVmfbt0zUe9J7nrCRX7H28rvuGqRsWddOp9Gu0HXrMv46EYNd9B639sbTqnbA=="

}

Apple Pay

{

"request" : "{\"currency\":\"USD\",\"amount\":50,\"merchantId\":3,\"merchantReference\":\"merRef1663297279620\",\"notifyUrl\":\"https:\/\/www.bbmsl.com\/notify\",\"lineItems\":[{\"priceData\":{\"name\":\"Book\",\"unitAmount\":50},\"quantity\":1}]}",

"signature" : "ZWRlNTIxZmJjYjQ0ZmE4YTJkMDQ0YTg4ZGQxZmM4MTVmZTBjNDkwZGU4YzljNGNhMTY1NTAzMjZmZmZjODBlOQ==",

"applePay" : {

"data" : "Lwd9Ksty28nr3+qEVzIBnOZE7aVDyyk16fTGR56TyspllTvLZh1\/82MF\/fgCvNJndvzj1e\/tK8DU45mYYa1H+EWjX8pX4ZUkjjyev2l9ArostxvYYj7F5YfLrVqvVmLw7RaGcwy0bqS5obWZhPn8SjUWLYOIpEhsUD7uJnrYic4iIu1E9gYD1970xERdMzg7fcCU5HOsuI\/YFnem2edPVD0GjighREM3khDzDxTUfHA+JMQzysF7J6Gp6Wk5UPbJMN960Pe3+JF9ka0tMYcBK6yyPsm\/8TFb6wK2N8m8FkZQkN6B\/ScFa3bJ\/pO1ojZ54ZULNL0BUOp5AYSwalf37jpuMuKo84DVDd3Vz8kh4p+gKEGU2BY9O0s\/BtxTjyis2OfTjZmdJMSl06JR",

"cardType" : "MASTER",

"version" : "EC_v1",

"signature" : "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4zCCA4igAwIBAgIITDBBSVGdVDYwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE5MDUxODAxMzI1N1oXDTI0MDUxNjAxMzI1N1owXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O\/0komJPnwPE6OCAhEwggINMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswRQYIKwYBBQUHAQEEOTA3MDUGCCsGAQUFBzABhilodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlYWljYTMwMjCCAR0GA1UdIASCARQwggEQMIIBDAYJKoZIhvdjZAUBMIH+MIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZCBjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMDYGCCsGAQUFBwIBFipodHRwOi8vd3d3LmFwcGxlLmNvbS9jZXJ0aWZpY2F0ZWF1dGhvcml0eS8wNAYDVR0fBC0wKzApoCegJYYjaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVhaWNhMy5jcmwwHQYDVR0OBBYEFJRX22\/VdIGGiYl2L35XhQfnm1gkMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0kAMEYCIQC+CVcf5x4ec1tV5a+stMcv60RfMBhSIsclEAK2Hr1vVQIhANGLNQpd1t1usXRgNbEess6Hz6Pmr2y9g4CJDcgs3apjMIIC7jCCAnWgAwIBAgIISW0vvzqY2pcwCgYIKoZIzj0EAwIwZzEbMBkGA1UEAwwSQXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcNMTQwNTA2MjM0NjMwWhcNMjkwNTA2MjM0NjMwWjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATwFxGEGddkhdUaXiWBB3bogKLv3nuuTeCN\/EuT4TNW1WZbNa4i0Jd2DSJOe7oI\/XYXzojLdrtmcL7I6CmE\/1RFo4H3MIH0MEYGCCsGAQUFBwEBBDowODA2BggrBgEFBQcwAYYqaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZXJvb3RjYWczMB0GA1UdDgQWBBQj8knET5Pk7yfmxPYobD+iu\/0uSzAPBgNVHRMBAf8EBTADAQH\/MB8GA1UdIwQYMBaAFLuw3qFYM4iapIqZ3r6966\/ayySrMDcGA1UdHwQwMC4wLKAqoCiGJmh0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlcm9vdGNhZzMuY3JsMA4GA1UdDwEB\/wQEAwIBBjAQBgoqhkiG92NkBgIOBAIFADAKBggqhkjOPQQDAgNnADBkAjA6z3KDURaZsYb7NcNWymK\/9Bft2Q91TaKOvvGcgV5Ct4n4mPebWZ+Y1UENj53pwv4CMDIt1UQhsKMFd2xd8zg7kGf9F3wsIW2WT8ZyaYISb1T4en0bmcubCYkhYQaZDwmSHQAAMYIBjTCCAYkCAQEwgYYwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTAghMMEFJUZ1UNjANBglghkgBZQMEAgEFAKCBlTAYBgkqhkiG9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0yMjA5MTkwNDU5MzNaMCoGCSqGSIb3DQEJNDEdMBswDQYJYIZIAWUDBAIBBQChCgYIKoZIzj0EAwIwLwYJKoZIhvcNAQkEMSIEICsrjcs2Q6WbQwPnxkfyWkMI80e3bqwHxcfph6H21O5AMAoGCCqGSM49BAMCBEgwRgIhAIy+gZLyR64TyQhUE6N+TFImVR4zTZ1mgUJTyYt0Rt6qAiEAi3\/WbWvyqOl+6EMIcFlRNtmW4Iuxl0PNqM4J2o1CaUQAAAAAAAA=",

"transactionId" : "869a28f2887357639efd5f42d8cf82e72f0853c0a1b8023f0766936b60aab11e",

"ephemeralPublicKey" : "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1y4\/GOpSmXcAA7F+xMMQUe2eD1fh5aD0UgdlbBC46dfi17yYNSh8iEI1VDlp+cFC2s8fpz1Sbf\/360wTxQa6Vw==",

"publicKeyHash" : "DbeXgMq0LgvB8TH+cy64HE7M79LkLYrpzyo4Jo+qU70="

}

}

Google Pay

{

"request": "{\"currency\":\"USD\",\"amount\":50,\"merchantId\":3,\"merchantReference\":\"merRef222222\",\"notifyUrl\":\"https://www.bbmsl.com/notify\",\"lineItems\":[{\"priceData\":{\"name\":\"Book\",\"unitAmount\":50},\"quantity\":1}]}",

"signature": "O2wtG/ei9JlnFvIfpmvyXcmuVGKLvo2Qn3K5n/eVQs4zx8WiYAkTjNholdSy1WnNWnDCrXROw9W/iC1QAw2xD4MOG8UApYXAjOONX4Psp9DNO8GdH4OGuhoci+F4mgco823itLedgfa6foRFO+xA76NknNMM3BcXpVwyax1932pVTBEfL0LqpazEQIazflkNzr+kuPI8ZXY85nDTVxIQzN0zy0qVe4IbYW12aCcoc7rI3ti9QCCbRHTfWN3HrLFwdU3DmK/BPm/IUt8yT75PvrtElJm/tITam80KQNMt5a9A94NB7euf+AJVcm1bWFYqcs0FGyM1fWENDEQ6NlfgUw==",

"googlePay": {

"cardType": "VISA",

"protocolVersion": "ECv1",

"signature": "MEUCIQCqg40xVg1aPist4fT1yi4vb3nRa1u214tII02IET8irwIgbOx3ygviVVDYiRU3uMdeseUJuXxD28dFGHk0pRCS16k=",

"signedMessage": "{\"encryptedMessage\":\"/RloYJMJ0poG1MA9u2dbmFqVHF1pcelaZJFK93ZVDYj28GDYvcOiaWVj3N2/5dmmEV7ACuZBvk+j8sbzQYu2kOY6gFvJTtQXjL9AsxpjvZM8Ou0mIxLPBt4xVffHmeVx3GHI0gebGKhKsaSfefY79/cYDjFuPP30RfkLSQKlK834n+FVhAPnIYmP4Q14gJNo6rDUbnpxiaCq4yt3ON4wukqXbOJlIRst9PeN1BkYUfB/r8aeBx3oOnJsFqMEEz4TOb61P8HN/m7SwJL3VTkSKI7rsZ9xlYnQFsxp+Qk5h193DvwGTM+MHiWFTMKZppVpiF31/JvYyHM6YZH/BbZIfEu8n5LQ3JC3pel36qvASxQ1N9gw0i3pdpbzFuvofm6BlC4PXt0qn4SxSw6zv8Vp3DRbeFP5Xmf1/kT5JT9bkwLP7XfmkrACzj9b6RLpGDzWRO0y5mgdXwjDGIpNnc5Tfl081YeLpf0PWDmIXFzsjAYHBxXH4gUSAdsJLuXzzezUi0OOcg4k9fdgj5hwZer3CYq51YPu5sqBY0jTLimzfyQKiortvZGA8Jc8zMJdxxwjkcWL6AEkdnyQup3AAQ8\\u003d\",\"ephemeralPublicKey\":\"BLkUNJWs/ISX9/XZlBEkZX6Cv5m9MiRxFmXgyHRbtEyWKb7yqU6nwaLl32d0U4O5LLK39+R0umghQ0Qbf2fibfY\\u003d\",\"tag\":\"wdBgLC0Pr5MAUaGtAlggNDqSQ25rf67ZsYKZSO/FTPg\\u003d\"}"

}

}

Response Parameters

Parameter	Type	Required/optional	Description
responseCode	string	Required	Payment Gateway response code
message	string	Required	Payment Gateway response message
order	object	Required
order.id	number	Required	Order identifier
order.merchantId	number	Required	Merchant identifier which own this order
order.merchantReference	string	Required	Your reference for the order
order.currency	string	Required	3-Letters ISO currency code of the order
order.amount	number	Required	Order amount
order.netAmount	number	Required	Net amount of the order
order.cardType	string	Required	Card type of the order
order.createTime	datetime	Required	Timestamp when the order is created. Maintained by the Payment Gateway
order.updateTime	datetime	Required	Timestamp when the order is last updated. Maintained by the Payment Gateway
order.status	string	Required	Status of the order. Maintained by the Payment Gateway
order.recurring	boolean	Required	Flags the order is a recurring order or not
transaction	object	Required
transaction.id	number	Required	Transaction identifier for the recurring transaction
transaction.merchantId	number	Required	Merchant identifier which own this transaction
transaction.type	string	Required	Transaction type
transaction.currency	string	Required	Transaction currency
transaction.amount	number	Required	Transaction amount
transaction.status	string	Required	Status of the transaction. Maintained by the Payment Gateway
transaction.maskedPan	string	Required	Masked card number of the transaction if supported by the payment method
transaction.stan	string	Required	System trace audit number for the transaction
threeDSChallengeDetails	object	Optional	3DS Challenge details object, will be used for API /direct/complete-authentication

Example:

{

"responseCode": "5000",

"order": {

"id": 4545,

"merchantId": 3,

"merchantReference": "merRef1657856553027",

"currency": "HKD",

"amount": 50,

"netAmount": 0,

"cardType": "VISA",

"createTime": "2022-07-15T03:42:33.715+00:00",

"updateTime": "2022-07-15T03:42:38.258+00:00",

"status": "OPEN",

"recurring": false

},

"transaction": {

"id": 1719,

"merchantId": 3,

"type": "SALE",

"amount": 50,

"currency": "HKD",

"status": "NONE",

"maskedPan": "400000XXXXXX0002",

"stan": "D1719"

},

"threeDSChallengeDetails": {

"threeDSVersion": "1.0.2",

"transactionId3DS": "DUtfji4vdlcmfamx7j30",

"acsURL": "https://merchantacsstag.cardinalcommerce.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",

"payload": "eNpVUctuwjAQvPsrItRz7LwagbaWoBEPtUEISqVyM4kpoTgJjgOkX187QGlvOzte78wsvG0l59GCJ7XkFGJeVeyTW1n61ImWarPL/GO6T8SGiXO480iHwqw/5wcKRy6rrMipYxPbBXyDSH8hky3LFQWWHAaTKfV933EcwFeIQHA5iWi0jOMPwBeAIGeC08EgXrxaM9YInitrxBQ/sQZwyyFIijpXsqFhoBfeAIJa7ulWqbKH8el0stdrUe3tpBCADYMA3xXNalNV2ug5S+l8+E5Woiyn49XXejRVKzFUPEoP8Xf/CbB5gSDVGqhLXJeETmARr+e7Pe8RcNtHwISRQccvDwGxCdEmLw0EpVnVv6CAGOpvR5uppeR50lDP97WbG0LAz2WRa/tUm/yttYu79uexyTZROrcg7Lqk65twW9yOZzoW13NIO5+1GWEzg6+nw9cr6+rf9X8AxKKrFQ=="

}

}