Phiên bản: Lastest

Get authentication

Có thể sử dụng API này đế lấy kết quả xác thực và dựa vào trạng thái xác thực 3DS để quyết định có tiếp tục thực hiện thanh toán giao dịch hay không.

EndPoint

POST /credit-card/enrollment/validate/:authenticationId

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 ý
authenticationId	required	String	authenticationId lấy từ URL query khi người dùng được điều hướng về trang của Merchant

Response Params

{
    "authenticationId": "01HQHR9W32E2RDSF6KM51PSJ92",
    "merchantRefId": "HJ1OsUcDI",
    "status": "PENDING",
    "amount": 1000000,
    "currency": "VND",
    "tokenId": "01hqhr8vgdw64qhqgvm2tsbpew",
    "deviceDataCollectionUrl": "https://acpg.dev.appotapay.com/credit-card/authenticate?id=01HQHR9W32E2RDSF6KM51PSJ92&signature=cf6e30824b5e66e0c401701f3416e72c5b069a01c3a80a316cf9e54f9b855675",
    "card": {
        "number": "400000XXXXXX0010",
        "expirationMonth": "12",
        "expirationYear": "29",
        "cardBrand": "MASTERCARD",
        "cardType": "CREDIT",
        "country": "VN"
    }
}

Thành công

Http Status Code 200 - OK

Tham số	Kiểu dữ liệu	Mô tả	Lưu ý
authenticationId	String	Mã định danh authentication được gửi trong URL
merchantRefId	String	Mã tham chiếu	Min:1 Max:40
card	String	Thông tin thẻ
card.number	String	Số thẻ	16 numbers
card.expirationMonth	String	Tháng hết hạn của thẻ, bao gồm cả số 0 ở đầu (VD: 03)	Format: MM
card.expirationYear	String	Năm hết hạn của thẻ (VD.: 25)	Format: YY
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)
amount	Float	Số tiền thanh toán (VD: 1000)	Hỗ trợ VND
status	String	Trạng thái của xác thực có thể trả về: `CARD_ENROLLED` thẻ đã check enroll và chờ xác thực từ phía người dùng `ENROLLMENT_CHECK_FAILED` không thể check enroll do issuer hoặc card network `CARD_NOT_ENROLLED` thẻ chưa được enroll `VERIFIED` xác minh 3DS đã thành công, khi nhận trạng thái đã xác thực này, giá trị eci có thể là một trong những giá trị sau: 05, 02, 06, 01, có thể tiến hành authorization `FAILED` kiểm tra 3DS thất bại `PENDING` khi giao dịch thẻ có 3DS 2.0 hoặc phía xử lý là MIGS. Điều hướng user tới trang xác thực 3DS để tiếp tục quá trình thanh toán
deviceDataCollectionUrl	String	Nếu trạng thái là `CARD_ENROLLED`, có thể khách hàng đến URL này để thực hiện xác thực 3DS
eci	String	Electronic Commerce Indicator (ECI) mã code cho thẻ đã enroll. ECI có thông tin khi xác thực 3DS thành công hoặc thất bại: 05 hoặc 02 - Xác thực thành công, tiến hành authorization 06 hoặc 01 - Thẻ không được enroll hoặc đã bị bỏ qua do luồng frictionless, tiến hành authorization 07 hoặc 00 - Xác thực thất bại
threeDsVersion	String	Phiên bản 3DS Ví dụ: -2.1.0 - 3DS 2.0 / EMV 3DS: - 1.0.2 - 3DS 1.0

Thất bại

HTTP Status Code != 200

Authentication Callback

Sau khi có kết quả xác thực 3DS, AppotaPay sẽ gửi callback đến merchant qua callback URL mà merchant đã gửi trước đó trong quá trình tích hợp

Event Schema

Tham số	Kiểu dữ liệu	Mô tả
event	String	Loại event Event xác thực là event: `credit_card.authentication`
responseTime	String	Thời gian phản hồi event theo chuẩn RFC-3339, time zone UTC+7
data	String	Dữ liệu của event, xem chi tiết tại Event Object structure Để kiểm tra nội dung data, bạn nên sử dụng - Base64 Decode data string - Then, JSON Decode data string from string was Base64 Decoded Ví dụ: - dataJson = JSON_Decode(Base64_Decode(data))
signature	String	Chữ ký để xác minh dữ liệu signature = HMACSHA256(data, secret_key) - data: tham số data từ trong yêu cầu - secret_key: từ application đã đăng ký với AppotaPay

Event Object structure


authenticationId	String	Mã định danh authentication
merchantRefId	String	Mã tham chiếu	Min:1 Max:40
card	String	Thông tin thẻ
card.number	String	Số thẻ	16 numbers
card.expirationMonth	String	Tháng hết hạn của thẻ, bao gồm cả số 0 ở đầu (VD: 03)	Format: MM
card.expirationYear	String	Năm hết hạn của thẻ (VD.: 25)	Format: YY
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)
amount	Float	Số tiền thanh toán (VD: 1000)	Hỗ trợ VND
status	String	Trạng thái của xác thực có thể trả về: `CARD_ENROLLED` thẻ đã check enroll và chờ xác thực từ phía người dùng `ENROLLMENT_CHECK_FAILED` không thể check enroll do issuer hoặc card network `CARD_NOT_ENROLLED` thẻ chưa được enroll `VERIFIED` xác minh 3DS đã thành công, khi nhận trạng thái đã xác thực này, giá trị eci có thể là một trong những giá trị sau: 05, 02, 06, 01, có thể tiến hành authorization `FAILED` kiểm tra 3DS thất bại `PENDING` khi giao dịch thẻ có 3DS 2.0 hoặc phía xử lý là MIGS. Điều hướng user tới trang xác thực 3DS để tiếp tục quá trình thanh toán
eci	String	Electronic Commerce Indicator (ECI) mã code cho thẻ đã enroll. ECI có thông tin khi xác thực 3DS thành công hoặc thất bại: `05` hoặc `02` - Xác thực thành công, tiến hành authorization `06` hoặc `01` - Thẻ không được enroll hoặc đã bị bỏ qua do luồng frictionless, tiến hành authorization `07` hoặc `00` - Xác thực thất bại
threeDsVersion	String	Phiên bản 3DS Ví dụ: - `2.1.0` - 3DS 2.0 / EMV 3DS: - `1.0.2` - 3DS 1.0

Example event callback data

{
  "event": "credit_card.authentication",
  "responseTime": "2023-12-12T11:54:23+07:00",
  "data": "eyJhdXRoZW50aWNhdGlvbklkIjoiMDFISEU2MDJYMzVNV1ZHWUtBREo5UVdNNEciLCJtZXJjaGFudFJlZklkIjoiYXV2ekVla1FRIiwic3RhdHVzIjoiVkVSSUZJRUQiLCJhbW91bnQiOjEwMDAwLCJjdXJyZW5jeSI6IlZORCIsImNhcmQiOnsibnVtYmVyIjoiNTIwMDAwWFhYWFhYMjE1MSIsImV4cGlyYXRpb25Nb250aCI6IjAxIiwiZXhwaXJhdGlvblllYXIiOiIyNCIsImNhcmRCcmFuZCI6Ik1BU1RFUkNBUkQiLCJjYXJkVHlwZSI6IkNSRURJVCIsImNvdW50cnkiOiJNWSJ9LCJlY2kiOiIwMiIsInRocmVlRHNWZXJzaW9uIjoiMi4yLjAifQ",
  "signature": "3d82e6b73cc8ebaa433137d74700422163fc1851d260b879aa7b6041f5bcefbf"
}

Khi bạn giải mã data, bạn có thể xem được dữ liệu trong callback event

{
  "event": "credit_card.authentication",
  "responseTime": "2023-12-12T11:54:23+07:00",
  "data": {
    "authenticationId": "01HHE602X35MWVGYKADJ9QWM4G",
    "merchantRefId": "auvzEekQQ",
    "status": "VERIFIED",
    "amount": 10000,
    "currency": "VND",
    "card": {
      "number": "520000XXXXXX2151",
      "expirationMonth": "01",
      "expirationYear": "24",
      "cardBrand": "MASTERCARD",
      "cardType": "CREDIT",
      "country": "MY"
    },
    "eci": "02",
    "threeDsVersion": "2.2.0"
  },
  "signature": "3d82e6b73cc8ebaa433137d74700422163fc1851d260b879aa7b6041f5bcefbf"
}

Để xác minh dữ liệu bằng chữ ký, bạn có thể sử dụng secret_key từ JWT (application đã được đăng ký)

data = "eyJhdXRoZW50aWNhdGlvbklkIjoiMDFISEU2MDJYMzVNV1ZHWUtBREo5UVdNNEciLCJtZXJjaGFudFJlZklkIjoiYXV2ekVla1FRIiwic3RhdHVzIjoiVkVSSUZJRUQiLCJhbW91bnQiOjEwMDAwLCJjdXJyZW5jeSI6IlZORCIsImNhcmQiOnsibnVtYmVyIjoiNTIwMDAwWFhYWFhYMjE1MSIsImV4cGlyYXRpb25Nb250aCI6IjAxIiwiZXhwaXJhdGlvblllYXIiOiIyNCIsImNhcmRCcmFuZCI6Ik1BU1RFUkNBUkQiLCJjYXJkVHlwZSI6IkNSRURJVCIsImNvdW50cnkiOiJNWSJ9LCJlY2kiOiIwMiIsInRocmVlRHNWZXJzaW9uIjoiMi4yLjAifQ";
secret_key = "Your_secret_key_was_resigtered"
signature = HMACSHA256(data, secret_key)

Link tham khảo để tạo Chữ ký: Free online Hash Hmac tool using algorithm SHA1, SHA256, SHA512 and more - Devtool

Ví dụ Code

curl --location 'https://gateway.dev.appotapay.com/credit-card/enrollment/validate/01HQHR9W32E2RDSF6KM51PSJ92' \
  --header 'X-APPOTAPAY-AUTH: JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-ID: Your_Unique_id' \
  --header 'Language: vi' \
  --header 'X-Account-Ref-ID: 9723f73b-9295-4acb-884b-ab6310c2e653'

Request

REQUEST

Base URL

Development server

Path

Auth REQUIRED

Bearer Token

Language — header

Giá trị tương ứng với payment link có thể là tiếng Việt hoặc tiếng Anh (mặc định: vi)

Parameters

authenticationId — path REQUIRED

EndPoint​

Header Params​

Request Params​

Response Params​

Thành công​

Thất bại​

Authentication Callback​

Event Schema​

Event Object structure​

Example event callback data​

Ví dụ Code​

Request​