Phiên bản: Lastest

Token Create

Cho phép merchant tạo token bằng cách gọi server-to-server thông qua API và gửi thông tin thẻ để trả về token. Token này có thể sử dụng trong các API thanh toán tiếp theo.

EndPoint

POST /credit-card/token

Header Params

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả	Lưu ý
X-APPOTAPAY-AUTH	required	String	Cách tạo JWT_TOKEN
Content-Type	required	String	Giá trị: `application/json`
X-Request-ID	optional	String	Định dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cố	max:42
Language	optional	String	Giá trị `vi` hoặc `en` tương ứng với link thanh toán sẽ là tiếng việt hoặc tiếng anh, (mặc định: `vi`)	in:vi,en
X-Account-Ref-ID	optional	String	Mã định danh của tài khoản Sub account do AppotaPay cung cấp. Bắt buộc truyền khi thanh toán giao dịch của Sub account loại owner

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

Tham số	Yêu cầu	Kiểu dữ liệu	Mô tả	Lưu ý
card	required	Object	Thông tin thẻ
card.number	required	String	Số thẻ	16 số
card.holderName	required	String	Tên chủ thẻ	Min: 1 Max: 50 bao gồm: 0- 9, a-z, A-Z, khoảng trắng
card.expirationMonth	required	String	Tháng hết hạn của thẻ, bao gồm cả số 0 ở đầu (VD: 03)
card.expirationYear	required	String	Năm hết hạn của thẻ (VD.: 25)
card.cvv	required	String	Card verification number, hay CVV Mã số bí mật của thẻ, gồm 3 hoặc 4 số
tokenType	required	String	Loại token - sử dụng 1 lần hoặc nhiều lần SINGLE: token chỉ thanh toán 1 lần MULTIPLE: token thanh toán được nhiều lần
merchantRefId	required	String	Mã tham chiếu, định danh cho yêu cầu khởi tạo từ merchant	Min: 1 Max: 40
customer	optional	Object	Thông tin khách hàng Nếu có thông tin khách hàng, bạn cần truyền đầy đủ tất cả thông tin
customer.browser	optional	Object	Thông tin trình duyệt customer
customer.browser.clientIp	optional	String	Địa chỉ IP của thiết bị khách hàng thanh toán	IPv4 Min: 7 Max: 45
customer.browser.userAgent	optional	String	User Agent của khách hàng. Thông tin được thu thập từ header được gửi từ thiết bị của khách hàng Được sử dụng cho quản lý rủi ro VD: `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	Địa chỉ trước đó được điều hướng đến trang thanh toán của merchant Được sử dụng cho quản lý rủi ro VD: AppotaPay - The leading online payment company in Vietnam	Min: 1 Max: 500
customer.browser.acceptLanguage	optional	String	Ngôn ngữ thiết bị của khách hàng VD: vi-VN, en-US Được sử dụng cho quản lý rủi ro	Min: 2 Max: 10
billing	optional	Object	Thông tin thanh toán của chủ thẻ đã đăng ký với tổ chức phát hành thẻ Nếu truyền thông tin billing, bạn cần truyền đầy đủ tất cả thông tin và tương ứng với thông tin đã đăng ký với ngân hàng phát hành
billing.firstName	optional	String	Tên của chủ thẻ Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 50
billing.lastName	optional	String	Họ và tên đệm của chủ thẻ Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 50
billing.email	optional	String	Email khách hàng đã đăng ký với issuer Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 255
billing.phoneNumber	optional	String	Số điện thoại khách hàng đã đăng ký với issuer Hữu ích với frictionless 3DS 2.0	Min: 8 Max: 20
billing.province	optional	String	Tỉnh, tiểu bang, khu vực cư trú. Nếu khách hàng thuộc tiểu bang của Mỹ, bắt buộc phải nhập mã tiểu bang (VD: nhập CA thay cho California) Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 100
billing.city	optional	String	Thành phố, thị trấn Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 100
billing.country	optional	String	2 ký tự trong bảng mã quốc gia theo chuẩn ISO 3166-2 Hữu ích với frictionless 3DS 2.0	Min: 2 Max: 2
billing.addressLine1	optional	String	Địa chỉ thanh toán thứ nhất mà khách đã đăng ký với issuer Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 100
billing.addressLine2	optional	String	Địa chỉ thanh toán thứ hai mà khách đã đăng ký với issuer Hữu ích với frictionless 3DS 2.0	Min: 1 Max: 100
billing.postalCode	optional	String	Mã bưu điện Hữu ích với 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"
}

Thành công

Http Status Code 200 - OK

Tham số	Kiểu dữ liệu	Mô tả	Lưu ý
tokenId	String	Mã token Có thể sử dụng trong các API thanh toán tiếp theo	Min:1 Max: 32
merchantRefId	String	Mã tham chiếu, merchant gửi trong request	Min:1 Max: 40
card	Object	Thông tin thẻ được lưu trữ trong token
card.number	String	6 số đầu - 4 số cuối của thẻ (VD 123456xxxxx1234)	Min:16 Max: 19
card.type	String	Loại thẻ, gồm: `CREDIT / DEBIT / PREPAID / UNKNOWN`
card.brand	String	Thương hiệu thẻ, gồm: `VISA / MASTERCARD / JCB / AMEX`
card.country	String	Quốc gia phát hành thẻ, bao gồm 2 chữ cái theo bảng mã ISO 3166-2 (VD: VN, US)
billing	Object	Tham số đã gửi ở trong request tạo token
createdAt	String	Thời gian khởi tạo giao dịch theo chuẩn RFC-3339, time zone UTC+7
updatedAt	String	Thời gian cập nhật giao dịch gần nhất theo chuẩn RFC-3339, time zone UTC+7

Thất bại

HTTP Status Code != 200

Token Create

EndPoint​

Header Params​

Request Params​

Example Request​

Response Params​

Thành công​

Thất bại​