API Explanation

Request Type

POST

Request URI

/api/v1/payment/local-card/tokenized

Request

When using bank card information to pay: (Token is returned after successful payment, and subsequent payments can be made using token)
Parameter Type Required Sample Data Description
amount Number Yes 20000 Transaction Amount. Cent is the unit, “100” means a dollar
callBackURL String <= 255 characters Yes https://pay.ottpay.com/paymentResult Callback URL. After the payment is completed, the system sends a notification to this URL.
accountNumber String Yes 4000620000000123 Card number
accountName String Yes Jack Smith Card holder name
accountExpire String Yes 0625 Card expiry date. Format: MMYY
cvn2 String Yes 732 CVV2 secure code
sslAvsAddress String <= 50 characters Yes 3032920100 CORPORATE SQ Card holder address.
sslAvsCity String <= 40 characters Yes Atlanta Card holder’s city where the address is located.
sslAvsProvince String >= 2 characters, <= 40 characters Yes Georgia Card holder’s province where the address is located.
sslAvsCountry String =2 characters Yes US/CA Card holder’s country where the address is located. See Country Codes ISO 3166
sslAvsZip String <= 10 characters Yes 30327 Card holder postal code.
sslEciInd String No 3DS ECI value. This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated
ssl3dsecureValue String <= 64 characters No 3DS secure value. 3DS authentication value returned by 3DS authentication process.
sslDirServerTranId String <= 64 characters No 3DS secure transaction ID. This is the identifier of a 3DS authentication returned by the 3DS authentication process.
reference String No MJG498J89TGLNK45 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
sessionId String No The OTT Pay risk control DDC session ID.
email String No The consumer’s email.
When paying directly with token:
Parameter Type Required Sample Data Description
amount Number Yes 20000 Transaction Amount. Cent is the unit, “100” means a dollar
callBackURL String <= 255 characters Yes https://pay.ottpay.com/paymentResult Callback URL. After the payment is completed, the system sends a notification to this URL.
cardTokenId String Yes NFctuV7400 Identifier of card Token in OTT Pay system. The token is generated from a successful payment that includes the cardholder’s information for the first time.
sslAvsAddress String <= 50 characters No 3032920100 CORPORATE SQ Card holder address.
sslAvsCity String <= 40 characters No Atlanta Card holder’s city where the address is located.
sslAvsProvince String >= 2 characters, <= 40 characters No Georgia Card holder’s province where the address is located.
sslAvsCountry String =2 characters No US/CA Card holder’s country where the address is located. See Country Codes ISO 3166
sslAvsZip String <= 10 characters No 30327 Card holder postal code.
sslEciInd String No 3DS ECI value. This is the Electronic Commerce Indicator code, which gets returned by the card issuer indicating whether the cardholder was successfully authenticated
ssl3dsecureValue String <= 64 characters No 3DS secure value. 3DS authentication value returned by 3DS authentication process.
sslDirServerTranId String <= 64 characters No 3DS secure transaction ID. This is the identifier of a 3DS authentication returned by the 3DS authentication process.
reference String No MJG498J89TGLNK45 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
sessionId String No The OTT Pay risk control DDC session ID.
email String No The consumer’s email.
Request Example：
When using bank card information to pay:
{
  "accountNumber": "4000620000000123",
  "accountName": "Jack Smith",
  "accountExpire": "0625",
  "cvn2": "733",
  "sslAvsAddress": "3032920100 CORPORATE SQ",
  "sslAvsCity": "Atlanta",
  "sslAvsProvince": "Georgia",
  "sslAvsCountry": "US",
  "sslAvsZip": "30329",
  "amount": 2500,
  "cardTokenId": "",
  "callBackURL": "https://uatqrpay.ottpay.com/ac/paymentResult",
  "sslEciInd": "",
  "ssl3dsecureValue": "",
  "sslDirServerTranId": "",
  "reference": "MJG498J89TGLNK45",
  "sessionId": "B61E6B38AFBF79C76A101E0F8CC26A3",
  "email": "coustomer@email.com"
}
When paying directly with token:
{
  "cardTokenId": "NFctuV7400",
  "amount": 4500,
  "callBackURL": "https://uatqrpay.ottpay.com/ac/paymentResult",
  "reference": "MJG498J89TGLNK45"
}

Response

Parameter Type Sample Data Description
reference String MJG498J89TGLNK45 The reference number from 3rd party. This can be used for order IDs that generated by integrate merchant.
ccType String VISA Card Schema VISA / MASTERCARD / AMEX
paymentId String 1694723098440263 Payment ID. A unique identifier associated with the payment transaction.
amount String 20000 Payment amount, i.e. purchase amount. The payment amount of purchase, cent is the unit, “100” means a dollar.
receiptAmount String 20000 Amount on the payment receipt, i.e. purchase amount +tips + fees - discount. The value of amount appears on receipt, include fees and tips, cent is the unit, “100” means a dollar.
totalAmount String 20000 Total amount of the transaction, i.e. purchase amount + tips + fees. The value of amount include fees and tips before applying coupon or discount, cent is the unit, “100” means a dollar.
tradeTime String Format： yyyy-MM-dd HH:mm:ssz 2023-09-14 16:25:00 EDT Payment time. The timestamp when the transaction or the query was initiated by the client. Time zone is always calculated/displayed in DST irrespective of the merchant location.
paymentStatus String authorised Payment Status. Please see Payment Status Query API for detail.
cardTokenId String dkefkD5535 Identifier of card Token in OTT Pay system. The token is generated from a successful payment that includes the cardholder’s information for the first time.

Response Example：

{
  "status":"SUCCESS",
  "result":{
    "reference": "K8MX7D2PHVTFWR82",
    "ccType": "VISA",
    "cardTokenId": "dkefkD5535",
    "paymentId":"1694878141303593",
    "amount": "1000",
    "receiptAmount": "1000",
    "totalAmount": "1000",
    "tradeTime": "2024-01-05 10:34:33 CST",
    "paymentStatus": "authorised"
  }
}

API Response error code

code message description
10005 Invalid parameter Parameter format incorrect
10200 Gateway error OTT gateway’s error response.
20004 Database error Transaction data induced database error.
20005 No permission for the merchant 1) The entered pre-authorization code is invalid, or 2) The merchant account you provided cannot be found, or 3) The merchant account you provided is disabled, or 4) Your merchant account is not configured for the transaction you attempted.
20007 Insufficient balance 1) Card balance is insufficient to cover the payment, or 2) not enough funds for refund
20008 Unsupported card The card type was not recognized, or The card was removed too quickly and the approval process was interrupted POS terminal was unable to encrypt the message and process the transaction
20019 Original payment not exist Original transaction/payment ID you provided cannot be found
20030 Payment failed Your request has been declined due to no financial impact - original transaction already declined
20034 Other case Any other errors that not include in the list
50001 Failure Payment Failed
50002 Timeout Your request has been declined due to a timeout OR The authorization message is approved. The error occurs if: 1) the transaction was declined by the card afterwards, or 2) timeout on the terminal. As a result, the transaction is reversed.
50003 System error No response received for the sent request
90000 Unauthorized The entered access token is invalid

Payment Result

After the OTT Pay API server obtains the payment result from the payment channel, it will immediately send the payment result to the specified callbackURL. Of course, the merchant system can also actively query through Payment Status Query API.