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