Charge Create
Bạn có thể yêu cầu thực hiện thanh toán qua token (đã tạo trước đó) hoặc thông tin thẻ. Một giao dịch Charge sẽ gồm 2 giai đoạn
-
Authorization: xác nhận với Issuing bank về thẻ đủ điều kiện thực hiện giao dịch. Đồng thời, số tiền giao dịch bị giữ lại và việc thanh toán chưa bắt đầu.
-
Capture: quá trình thành toán sẽ được bắt đầu.
EndPoint
POST /credit-card/charge
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_if | Object | Required nếu tham số tokenId không truyền lên 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) | Format: MM |
| card.expirationYear | required | String | Năm hết hạn của thẻ (VD.: 25) | Format: YY |
| card.cvv | required | String | Card verification number, hay CVV Mã số bí mật của thẻ, gồm 3 hoặc 4 số | |
| tokenId | required_if | String | Required nếu tham số card không truyền lên Token ID để thanh toán thay thông tin thẻ | |
| amount | required | Float | Số tiền thanh toán (VD: 1000) | Hỗ trợ VND |
| capture | optional | Boolean | Mặc định: false true: thực hiện Authorization, sau đó thực hiện capture false : chỉ thực hiện Authorization (uỷ quyền - hold tiền người dùng), capture sẽ được thực hiện sau khi call API Capture Charge Lưu ý: Authorization có hiệu lực trong vòng 7 ngày | |
| merchantRefId | required | String | Mã tham chiếu, định danh cho yêu cầu khởi tạo từ merchant | Min: 1 Max: 40 |
| authenticationId | required_if | String | Mã authentication được AppotaPay trả khi thực hiện Xác thực 3DS Nếu bạn muốn thực hiện Authorization hoặc Capture không có 3DS, có thể không cần truyền trường này Lưu ý: Bắt buộc truyền khi cấu hình 3ds là bắt buộc | Min: 1 Max: 40 |
| currency | required | String | Loại tiền thanh toán. Bao gồm 3 ký tự theo chuẩn ISO-4217 | Hỗ trợ: VND |
| 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": "hi8xGfznb",
"authenticationId": "01HQHRPNYW78CQJK7CAW1SJP9F",
"tokenId": "01hqhrp3yhff7z7bvtq6whwz8t",
"amount": 1000000,
"currency": "VND",
"capture": false,
"billing" : {
"firstName": "NHUNG",
"lastName": "HOANG",
"email": "nhunghoang@email.com",
"phoneNumber": "02345686432",
"province": "VP",
"country": "MM",
"city": "VT",
"addressLine1": "81 Lang Ha",
"addressLine2": "17 Mai Anh Tuan",
"postalCode": "10000"
}
}
Response Params
{
"id": "01HQHRS9P9J5YPCJ09D94VW84F",
"authenticationId": "01HQHRPNYW78CQJK7CAW1SJP9F",
"merchantRefId": "hi8xGfznb",
"status": "AUTHORIZED",
"authorizedAmount": 1000000,
"currency": "VND",
"approvalCode": "831000",
"eci": "02",
"bankReconciliationId": "7089196646896845103954",
"tokenId": "01hqhrp3yhff7z7bvtq6whwz8t",
"card": {
"number": "520000XXXXXX2151",
"expirationMonth": "12",
"expirationYear": "29",
"cardBrand": "MASTERCARD",
"cardType": "CREDIT",
"countryCode": "VI"
},
"chargeType": "BY_MULTIPLE_TOKEN",
"createdAt": "2024-02-26T10:54:22+07:00",
"updatedAt": "2024-02-26T10:54:25+07:00"
}
Thành công
Http Status Code
200-OK
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| merchantRefId | String | Mã tham chiếu |
| card | String | Thông tin thẻ |
| card.number | String | Số thẻ |
| card.expirationMonth | String | Tháng hết hạn của thẻ, bao gồm cả số 0 ở đầu (VD: 03) |
| card.expirationYear | String | Năm hết hạn của thẻ (VD.: 25) |
| 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) |
| reconciliationId | String | Mã giao dịch được dùng để đối soát với AppotaPay |
| bankReconciliationId | String | Mã giao dịch được dùng để đối soát với ngân hàng |
| authorizedAmount | Number | Số tiền đã được authorize |
| capturedAmount | Number | Số tiền đã được capture khi charge. Có thể nhỏ hơn hoặc bằng authorized_amount |
| currency | String | Đơn vị tiền sử dụng thanh toán |
| status | String | Trạng thái của giao dịch PENDING: Đang xử lý giao dịch CAPTURED: Capture thành công AUTHORIZED: Authorize thành công DECLINED: Charge thất bại |
| eci | String | Trạng thái xác thực 3DS |
| id | String | Mã giao dịch id này có thể sử dụng trong các API khác để thực hiện Capture hoặc Reversal hoặc Refund hoặc Get Charge (nếu đủ điều kiện) |
| approvalCode | String | Mã từ phía ngân hàng phát hành trả |
| errorInformation | Object | Lý do thất bại |
| errorInformation.errorCode | Integer | Mã lỗi thất bại, xem chi tiết tại error code |
| errorInformation.message | String | Mô tả lý do thất bại |
| errorInformation.details | Array or Object | Chi tiết thông tin thất bại |
| errorInformation.details.field | String | Trường gây ra lỗi |
| errorInformation.details.reason | String | Lý do |
| chargeType | String | Loại thanh toán - BY_SINGLE_TOKEN - BY_MULTIPLE_TOKEN - BY_CARD_INFO |
| 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