Skip to main content

Authenticate and authorise a payment

Use this endpoint to create an authenticated payment in the Direct Model using a credit card, Apple Pay, or Google Pay. For credit card payments, a 3-D Secure (3DS) challenge may be required before the transaction completes.

Endpoint summary​

Path: /direct/auth
Method: POST
Content-Type: application/json

Request parameters​

ParameterTypeMandatoryDefaultDescription
merchantIdStringMMerchant identifier
amountNumber(9,2)MOrder amount
currencyStringOHKD3-Letters ISO currency code, supports HKD, USD
merchantReferenceString(64)MAn unique reference to identify this order
ddcSessionStringCSessionId value obtained from the postMessage of Cardinal, only mandatory for credit card payment
notifyUrlStringOAn API URL in merchant's backend to receive notification
refererStringOThe website URL where customers are visiting it from
userAgentStringOThe characteristic string of the browser application, common format: User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>
postLinkStringOThe URL posted the payment request
merchantSiteStringOMerchant's own website URL
cardObjectCCredit card data object, only mandatory for credit card payment
card.cardNumberStringMCard number
card.expiryMonthStringMCard expiry month, format MM
card.expiryYearStringMCard expiry year, format in YYYY
card.securityCodeStringM3-digits CVC/CVV number, usually placed at the back of the credit card
card.nameOnCardStringMCardholder name
cardAddressObjectOFor AVS verification purpose, credit card issued from US or CA are highly suggested to provide
cardAddress.postalCodeStringOPostal code of the card issuing location
cardAddress.countryCodeStringOCountry code of the card issuing location, in ISO-3166 alpha-2 format
lineItemsArrayM 
lineItems[index].quantityNumber(8)MNumber of items, must be an integer
lineItems[index].priceDataObjectMPrice data object with details
lineItems[index].priceData.unitAmountNumber(9,2)MUnit amount of the item
lineItems[index].priceData.nameStringMName of the item

Apple Pay parameters​

ParameterTypeMandatoryDescription
applePayObjectCApple Pay data object, only mandatory for Apple Pay
applePay.cardTypeStringMCard type of the order, obtained from payment.token.paymentMethod.network, supports VISA, MASTER
applePay.dataStringMApple Pay data, obtained from payment.token.paymentData
applePay.ephemeralPublicKeyStringMApple Pay ephemeralPublicKey, obtained from payment.token.paymentData
applePay.publicKeyHashStringMApple Pay publicKeyHash, obtained from payment.token.paymentData
applePay.signatureStringMApple Pay signature, obtained from payment.token.paymentData
applePay.transactionIdStringMApple Pay transactionId, obtained from payment.token.paymentData
applePay.versionStringMApple Pay version, obtained from `payment.token.paymentData

Google Pay parameters​

ParameterTypeMandatoryDescription
googlePayObjectCGoogle Pay data object, only mandatory for Google Pay
googlePay.cardTypeStringMCard type of the order, obtained from paymentData.paymentMethodData.info.cardNetwork, supports VISA, MASTER
googlePay.protocolVersionStringMGoogle Pay protocolVersion, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signatureStringMGoogle Pay signature, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signedMessageStringMGoogle Pay signedMessage, obtained from paymentData.paymentMethodData.tokenizationData.token
note
  • The ddcSession value is mandatory for conducting the 3DS process. Non-3DS payment flows are deprecated.
  • The applePay and googlePay objects are added to the PayAPI request body as separate top-level keys and must not be included in the request field used for request signing.
  • When a 3DS challenge is required, the gateway returns response code 5000 and populates threeDSChallengeDetails. Pass the returned orderId and stan to the Complete 3DS authentication endpoint after the challenge completes.

Request example​

{
  "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=="
}

Response parameters​

ParameterTypeMandatoryDescription
responseCodeStringMPayment Gateway response code
messageStringMPayment Gateway response message
orderObjectM 
order.idNumberMOrder identifier
order.merchantIdNumberMMerchant identifier which own this order
order.merchantReferenceStringMYour reference for the order
order.currencyStringM3-Letters ISO currency code of the order
order.amountNumberMOrder amount
order.netAmountNumberMNet amount of the order
order.cardTypeStringMCard type of the order
order.createTimeDatetimeMTimestamp when the order is created. Maintained by the Payment Gateway
order.updateTimeDatetimeMTimestamp when the order is last updated. Maintained by the Payment Gateway
order.statusStringMStatus of the order. Maintained by the Payment Gateway
order.recurringBooleanMFlags the order is a recurring order or not
transactionObjectM 
transaction.idNumberMTransaction identifier for the recurring transaction
transaction.merchantIdNumberMMerchant identifier which own this transaction
transaction.typeStringMTransaction type
transaction.currencyStringMTransaction currency
transaction.amountNumberMTransaction amount
transaction.statusStringMStatus of the transaction. Maintained by the Payment Gateway
transaction.maskedPanStringMMasked card number of the transaction if supported by the payment method
transaction.stanStringMSystem trace audit number for the transaction
threeDSChallengeDetailsObjectO3DS Challenge details object, will be used for API /direct/complete-authentication

Response 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=="
  }
}