Version: Lastest

Token Create

Allows merchants to generate tokens by calling server-to-server via API and sending card information to return tokens. You can use the tokenId in Authentication API and Charge API to perform payment process.

EndPoint

POST /credit-card/token

Header Params

Param	Required	Type	Description	Note
X-APPOTAPAY-AUTH	required	String	How to generate JWT_TOKEN
Content-Type	required	String	Value: `application/json`
X-Request-ID	optional	String	UUIDv4 format. Request ID to check when a problem occurs	max:42
Language	optional	String	The value `vi` or `en` corresponding to the payment link will be Vietnamese or English, (default: vi)	in:vi,en
X-Account-Ref-ID	optional	String	Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

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: `Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/92.0.4512.0 Safari/537.36`	Max: 500
customer.browser.referrer	optional	String	The previous address is redirected to the merchant page Used for risk management E.g: https://appotapay.com/	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 The token can be used in authentication API and charge API.	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

Token Create

EndPoint​

Header Params​

Request Params​

Example Request​

Response Params​

Success​

Error​