Token Create
Allows merchants to generate tokens by calling server-to-server via API and sending card information to return tokens
EndPoint
POST /credit-card/token
Header Params
{
Content-Type: "application/json",
X-APPOTAPAY-AUTH: "your_auth_token",
Language: "en", // option vi | en, default vi
X-Request-ID: "your_request_id" // optional - easy to debug request
}
Request Params
| Parameters | Requirement | Data type | Description | Note |
|---|---|---|---|---|
| card | required | Object | Card information | |
| card.number | required | String | Card number | 16 numbers |
| card.holderName | required | String | Card holder | Min: 1 Max: 50 Including: 0- 9, a-z, A-Z, Space |
| card.expirationMonth | required | String | Card expiration month, including leading 0 (E.g.: 03 for March) | Format: MM |
| card.expirationYear | required | String | Card expiration year (E.g.: 25) | Format: YY |
| card.cvv | required | String | Card verification number, also known as CVV The card's secret code includes 3 or 4 numbers | |
| tokenType | required | String | Tokens can be used once or many times SINGLE: token can only be paid once MULTIPLE: token can be paid many times | |
| merchantRefId | required | String | Reference ID you can use to identify the transaction. | Min: 1 Max: 40 |
| customer | optional | Object | Customer information If entered customer information, you need to enter all information. | |
| customer.browser | optional | Object | Customer's browser information. | |
| customer.browser.clientIp | optional | String | IP address of the customer device | IPv4 Min: 7 Max: 45 |
| customer.browser.userAgent | optional | String | User Agent of customer. Information is collected from header sent from the client's device Used for risk management E.g: | Max: 500 |
| customer.browser.referrer | optional | String | The previous address is redirected to the merchant page Used for risk management | Min: 1 Max: 500 |
| customer.browser.acceptLanguage | optional | String | Customer device language E.g: vi-VN, en-US Used for risk management | Min: 2 Max: 10 |
| billing | optional | Object | Billing details of the cardholder. If entered, should correspond with billing details registered by the cardholder with their issuer. If entered billing information, you need to enter all information and correspond as registered to your issuing bank. | |
| billing.firstName | optional | String | First name of cardholder Useful with frictionless 3DS 2.0 | Min: 1 Max: 50 |
| billing.lastName | optional | String | Last name of cardholder Useful with frictionless 3DS 2.0 | Min: 1 Max: 50 |
| billing.email | optional | String | Cardholder’s email address on record with issuer Useful with frictionless 3DS 2.0 | Min: 1 Max: 255 |
| billing.phoneNumber | optional | String | Cardholder’s mobile phone number on record with issuer Useful with frictionless 3DS 2.0 | Min: 8 Max: 20 |
| billing.province | optional | String | Use this to enter province, state or region of residence. If the user is USA citizen, make sure to use state code (e.g put CA instead of California) Useful with frictionless 3DS 2.0 | Min: 1 Max: 100 |
| billing.city | optional | String | City, village or town as appropriate Useful with frictionless 3DS 2.0 | Min: 1 Max: 100 |
| billing.country | optional | String | 2-letter ISO 3166-2 country code for the customer's country of residence Useful with frictionless 3DS 2.0 | Min: 2 Max: 2 |
| billing.addressLine1 | optional | String | Building name and apartment unit number Useful with frictionless 3DS 2.0 | Min: 1 Max: 100 |
| billing.addressLine2 | optional | String | Building name and apartment unit number Useful with frictionless 3DS 2.0 | Min: 1 Max: 100 |
| billing.postalCode | optional | String | Postal, zip or rural delivery code, if applicable Useful with frictionless 3DS 2.0 | Min: 1 Max: 10 |
Example Request
{
"merchantRefId": "PdWghqjDT",
"tokenType": "SINGLE",
"card" : {
"holderName": "HOANG NHUNG",
"number": "4000000000000010",
"expirationMonth": "12",
"expirationYear": "29",
"cvv": "123"
},
"customer" : {
"browser": {
"clientIp": "192.11.11.11",
"userAgent": "ui",
"referrer": "https://appotapay.com/",
"acceptLanguage": "en-US"
}
},
"billing" : {
"firstName": "NHUNG",
"lastName": "HOANG",
"email": "nhunghoang@email.com",
"phoneNumber": "02345686432",
"alternatePhoneNumber": "02345686432",
"province": "VP",
"country": "MM",
"city": "VT",
"addressLine1": "81 Lang Ha",
"addressLine2": "17 Mai Anh Tuan",
"postalCode": "10000"
}
}
Response Params
{
"tokenId": "01hqhr4qqnk66d7tg3pk5md08c",
"merchantRefId": "PdWghqjDT",
"card": {
"number": "400000XXXXXX0010",
"type": "CREDIT",
"brand": "MASTERCARD",
"country": "VN"
},
"billing": {
"firstName": "NHUNG",
"lastName": "HOANG",
"email": "nhunghoang@email.com",
"phoneNumber": "02345686432",
"alternatePhoneNumber": "",
"country": "MM",
"province": "VP",
"city": "VT",
"addressLine1": "81 Lang Ha",
"addressLine2": "17 Mai Anh Tuan",
"postalCode": "10000"
},
"createdAt": "2024-02-26T10:43:08+07:00",
"updatedAt": "2024-02-26T10:43:09+07:00"
}
Success
Http Status Code
200-OK
| Parameters | Data type | Description | Note |
|---|---|---|---|
| tokenId | String | Unique AppotaPay Token ID returned upon a successful Tokenization request | Min:1 Max: 32 |
| merchantRefId | String | Your reference ID for identifying the transaction, sent in the Create Token request | Min:1 Max: 40 |
| card | Object | Card information is stored in the token | |
| card.number | String | 1st 6 and last 4 digits of the tokenized card. (E.g. 123456xxxxx1234) | Min:16 Max: 19 |
| card.type | String | Card type, include: CREDIT / DEBIT / PREPAID / UNKNOWN | |
| card.brand | String | Card brand, include: VISA / MASTERCARD / JCB / AMEX | |
| card.country | String | Country of the card issuing bank in ISO 3166-1 alpha-2 format (E.g.: VN, US) | |
| billing | Object | Params as sent in the request (see above under Create Token request) | |
| createdAt | String | Transaction creation time according to RFC-3339 standard, time zone UTC+7 | |
| updatedAt | String | Last updated time according to RFC-3339 standard, time zone UTC+7 |
Error
HTTP Status Code !=
200