Skip to main content

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​

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
DDCSession

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

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 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：

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

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