Charge Create
EndPoint
POST /credit-card/charge
Header Params
{
Content-Type: "application/json",
X-APPOTAPAY-AUTH: "your_auth_token",
Language: "vi", // option vi | en, default vi
X-Request-ID: "your_request_id" // optional - easy to debug request
}
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 | optional | 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 | 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 |
| 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