Nhảy tới nội dung
Phiên bản: Lastest

API Tạo payment method

Endpoint: /api/v1/subs/payment-methods

Method: POST

Header Params

Tham sốYêu cầuKiểu dữ liệuMô tảLưu ý
X-APPOTAPAY-AUTHrequiredString Cách tạo JWT_TOKEN
Content-TyperequiredStringGiá trị: application/json
X-Request-IDoptionalStringĐịnh dạng UUIDv4. Request ID để kiểm tra yêu cầu khi xảy ra sự cốmax:42
LanguageoptionalStringGiá 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-IDoptionalString

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

Tham số

Tham sốYêu cầuKiểu dữ liệuMô tảValidate
paymentMethodRefIdRequiredString

Mã định danh cho payment method được cung cấp bởi partner.

Các request có paymenMethodRefId trùng nhau sẽ trả lỗi.

min:1, max: 50, format: alphanumeric
customerIdConditional, bắt buộc nếu object customer không có thông tinStringCustomer ID được khởi tạo trong API Create customer
customerConditional, bắt buộc nếu trường customerId không có thông tinObjectThông tin khách hàng
customer.firstNameConditionalStringTên khách hàngmin:1, max: 50
customer.lastNameOptionalStringHọ khách hàngmin:1, max: 50
customer.mobileNumberOptionalString

Số điện thoại

Format: +[Mã vùng][Số điện thoại]

Ví dụ: +84919333777

min:1, max: 16, format: E.164
customer.emailOptionalStringEmailmin:1, max: 50
customer.genderOptionalString

Giới tính

- MALE: nam

- FEMALE: nữ

- OTHER: khác

in: MALE, FEMALE, OTHER
customer.dateOfBirthOptionalStringNgày sinhformat YYYY-MM-DD string
customer.placeOfBirthOptionalStringNơi sinhmax: 50
customer.nationalityOptionalStringMã quốc giaformat ISO 3166-2 Country Code
countryRequiredString

Mã quốc gia của GD

Giá trị được chấp nhận

- ID: Indonesia

- PH: Philippines

- VN: Vietnam

- TH: Thailand

- MY: Malaysia

Format ISO 3166-2 Country Code
currencyRequiredStringĐơn vị tiền tệin: VND
paymentMethodRequiredString

Phương thức thanh toán

- CC_SUBS: thanh toán với thẻ quốc tế

- EWALLET_SUBS: thanh toán với ví điện tử

in: CC_SUBS, EWALLET_SUBS
reusabilityRequiredString

Khả năng sử dụng lại của payment method

- MULTIPLE_USE: sử dụng nhiều lần

in: MULTIPLE_USE
cardConditional, bắt buộc nếu paymentMethod = 'CC_SUBS'ObjectThông tin, thuộc tính thẻ
card.propertiesConditional, bắt buộc nếu paymentmethod = 'CC_SUBS'ObjectThuộc tính
card.properties.skipThreeDSecureConditional, bắt buộc nếu paymentMethod = 'CC_SUBS'String

Bỏ qua xác thực 3D secure khi khởi tạo Payment method

- YES: Bỏ qua xác thực 3DS

- NO: Thực hiện xác thực 3DS

in: YES, NO
card.properties.successReturnUrlConditional, bắt buộc nếu skipThreeDSecure = NOString

Đường dẫn điều hướng về sau khi xác thực thành công

AppotaPay sẽ gửi kết quả chi tiết qua URL này với một số thông tin như sau: LINK

max:100
card.properties.failureReturnUrlConditional, bắt buộc nếu skipThreeDSecure = NOString

Đường dẫn điều hướng về sau khi xác thực thất bại

AppotaPay sẽ gửi kết quả chi tiết qua URL này với một số thông tin như sau: LINK

max:100
card.cardInfoConditional, bắt buộc nếu paymentmethod = 'CC_SUBS'ObjectThông tin thẻ
card.cardInfo.cardNumberConditional, bắt buộc nếu paymentMethod = 'CC_SUBS'StringSố thẻmax: 20
card.cardInfo.cardMonthConditional, bắt buộc nếu paymentMethod = 'CC_SUBS'StringTháng hết hạn của thẻ, bao gồm cả số 0 ở đầu (VD: 03)format: MM
card.cardInfo.cardYearConditional, bắt buộc nếu paymentMethod = 'CC_SUBS'StringNăm hết hạn của thẻ (VD: 2024)format: YYYY
card.cardInfo.cardHolderNameOptionalStringTên chủ thẻmax: 50
ewalletConditional, bắt buộc nếu paymentmethod = 'EWALLET_SUBS'ObjectThông tin, thuộc tính ví điện tử
ewallet.serviceCodeConditional, bắt buộc nếu paymentMethod = 'EWALLET_SUBS'StringMã Ví
ewallet.propertiesConditional, bắt buộc nếu paymentMethod = 'EWALLET_SUBS'ObjectThuộc tính
ewallet.properties.successReturnUrlConditional, bắt buộc nếu paymentMethod = 'EWALLET_SUBS'StringĐường dẫn điều hướng về sau khi xác thực thành công
ewallet.properties.pendingReturnUrlConditional, bắt buộc nếu paymentMethod = 'EWALLET_SUBS'StringĐường dẫn điều hướng về sau khi xác thực đang xử lý
ewallet.properties.failureReturnUrlConditional, bắt buộc nếu paymentMethod = 'EWALLET_SUBS'StringĐường dẫn điều hướng về sau khi xác thực thất bại
billingOptionalObjectThông tin thanh toán
billing.countryRequired nếu 1 trường trong object có dữ liệuStringMã quốc giaFormat ISO 3166-2 Country Code
billing.cityRequired nếu 1 trường trong object có dữ liệuStringThành phốmin:1, max: 50
billing.provinceStateRequired nếu 1 trường trong object có dữ liệuStringKhu vực, quận huyệnmin:1, max: 50
billing.addressRequired nếu 1 trường trong object có dữ liệuStringĐịa chỉmin:1, max: 100
billing.zipcodeRequired nếu 1 trường trong object có dữ liệuStringMã zipmin:1, max: 10, format: numeric

Example Request

{
"paymentMethodRefId": "ASKJLKALK16640",
"customer": {
"firstName": "Ha",
"lastName": "Phan",
"mobileNumber": "+84123456789",
"email": "ha@gmail.com",
"gender": "MALE",
"dateOfBirth": "1996-04-23",
"placeOfBirth": "HN",
"nationality": "EC"
},
"country": "VN",
"currency": "VND",
"paymentMethod": "CC_SUBS",
"reusability": "MULTIPLE_USE",
"card": {
"properties" : {
"skipThreeDSecure": "NO",
"successReturnUrl": "https://devtool.vn/success",
"failureReturnUrl": "https://devtool.vn/failure"
},
"cardInfo" : {
"cardNumber": "5200000000001096",
"cardMonth": "07",
"cardYear": "2034",
"cardHolderName": "Mai Minh"
}
},
"billing": {
"country": "EC",
"city": "HN",
"provinceState": "CG",
"address": "CG",
"zipcode": "530000"
}
}

Dữ liệu trả về

Thành công

Http Status Code 200 - OK

Dữ liệu trả về thành công sẽ chứa một Payment method object

Thất bại

HTTP Status Code != 200

Error response params

Tham sốYêu cầuKiểu dữ liệuMô tả
errorCoderequiredIntegerMã lỗi
messagerequiredStringMô tả lỗi
errorsoptionalArrayMô tả lỗi chi tiết các trường nếu có
errors.*.fieldoptionalStringTrường dữ liệu bị lỗi
errors.*.reasonoptionalStringMô tả trường dữ liệu bị lỗi
{
"errorCode": 1,
"message": "Thông tin yêu cầu thiếu hoặc không hợp lệ",
"errors": [
{
"field": "paymentMethodRefId",
"reason": "Trường payment method ref id không được bỏ trống."
}
]
}

Bảng mã lỗi thường gặp

Mã lỗi đầy đủ vui lòng xem tại đây

Mã lỗiMô tả
0Thành công
1Thông tin yêu cầu thiếu hoặc không hợp lệ
11Partner không tồn tại
13Partner đã bị khoá
14API Key không tồn tại
15API Key chưa được kích hoạt hoặc đã bị khoá
92IP không được phép truy cập
99Lỗi không xác định, vui lòng liên hệ AppotaPay để biết thêm thông tin chi tiết
401Lỗi xác thực
500Hệ thống gặp lỗi, vui lòng thử lại sau
3002Mã tham chiếu Partner đã bị trùng, vui lòng thực hiện lại
3003Customer không tồn tại
30133D Secure là bắt buộc
3027Thông tin khách hàng không hợp lệ