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

ParameterTypeRequired/optionalDefaultDescription
merchantIdstringRequiredMerchant identifier
amountnumberRequiredOrder amount
currencystringOptionalHKD3-Letters ISO currency code, supports HKD, USD
merchantReferencestringRequiredAn unique reference to identify this order
ddcSessionstringConditionalSessionId value obtained from the postMessage of Cardinal, only required for credit card payment
notifyUrlstringOptionalAn API URL in merchant's backend to receive notification
refererstringOptionalThe website URL where customers are visiting it from
userAgentstringOptionalThe characteristic string of the browser application, common format: User-Agent: Mozilla/5.0 (<system-information>) <platform> (<platform-details>) <extensions>
postLinkstringOptionalThe URL posted the payment request
merchantSitestringOptionalMerchant's own website URL
cardobjectConditionalCredit card data object, only required for credit card payment
card.cardNumberstringRequiredCard number
card.expiryMonthstringRequiredCard expiry month, format MM
card.expiryYearstringRequiredCard expiry year, format in YYYY
card.securityCodestringRequired3-digits CVC/CVV number, usually placed at the back of the credit card
card.nameOnCardstringRequiredCardholder name
cardAddressobjectOptionalFor AVS verification purpose, credit card issued from US or CA are highly suggested to provide
cardAddress.postalCodestringOptionalPostal code of the card issuing location
cardAddress.countryCodestringOptionalCountry code of the card issuing location, in ISO-3166 alpha-2 format
lineItemsarrayRequired 
lineItems[index].quantitynumberRequiredNumber of items, must be an integer
lineItems[index].priceDataobjectRequiredPrice data object with details
lineItems[index].priceData.unitAmountnumberRequiredUnit amount of the item
lineItems[index].priceData.namestringRequiredName of the item
DDCSession

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

Apple Pay Parameters

ParameterTypeRequired/optionalDescription
applePayobjectConditionalApple Pay data object, only required for Apple Pay
applePay.cardTypestringRequiredCard type of the order, obtained from payment.token.paymentMethod.network, supports VISA, MASTER
applePay.datastringRequiredApple Pay data, obtained from payment.token.paymentData
applePay.ephemeralPublicKeystringRequiredApple Pay ephemeralPublicKey, obtained from payment.token.paymentData
applePay.publicKeyHashstringRequiredApple Pay publicKeyHash, obtained from payment.token.paymentData
applePay.signaturestringRequiredApple Pay signature, obtained from payment.token.paymentData
applePay.transactionIdstringRequiredApple Pay transactionId, obtained from payment.token.paymentData
applePay.versionstringRequiredApple Pay version, obtained from payment.token.paymentData

Google Pay Parameters

ParameterTypeRequired/optionalDescription
googlePayobjectConditionalGoogle Pay data object, only required for Google Pay
googlePay.cardTypestringRequiredCard type of the order, obtained from paymentData.paymentMethodData.info.cardNetwork, supports VISA, MASTER
googlePay.protocolVersionstringRequiredGoogle Pay protocolVersion, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signaturestringRequiredGoogle Pay signature, obtained from paymentData.paymentMethodData.tokenizationData.token
googlePay.signedMessagestringRequiredGoogle 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

ParameterTypeRequired/optionalDescription
responseCodestringRequiredPayment Gateway response code
messagestringRequiredPayment Gateway response message
orderobjectRequired 
order.idnumberRequiredOrder identifier
order.merchantIdnumberRequiredMerchant identifier which own this order
order.merchantReferencestringRequiredYour reference for the order
order.currencystringRequired3-Letters ISO currency code of the order
order.amountnumberRequiredOrder amount
order.netAmountnumberRequiredNet amount of the order
order.cardTypestringRequiredCard type of the order
order.createTimedatetimeRequiredTimestamp when the order is created. Maintained by the Payment Gateway
order.updateTimedatetimeRequiredTimestamp when the order is last updated. Maintained by the Payment Gateway
order.statusstringRequiredStatus of the order. Maintained by the Payment Gateway
order.recurringbooleanRequiredFlags the order is a recurring order or not
transactionobjectRequired 
transaction.idnumberRequiredTransaction identifier for the recurring transaction
transaction.merchantIdnumberRequiredMerchant identifier which own this transaction
transaction.typestringRequiredTransaction type
transaction.currencystringRequiredTransaction currency
transaction.amountnumberRequiredTransaction amount
transaction.statusstringRequiredStatus of the transaction. Maintained by the Payment Gateway
transaction.maskedPanstringRequiredMasked card number of the transaction if supported by the payment method
transaction.stanstringRequiredSystem trace audit number for the transaction
threeDSChallengeDetailsobjectOptional3DS 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=="
  }
}