3.3.1 Khởi tạo yêu cầu thanh toán tự động
Lưu ý
API này chỉ sử dụng cho đối tác đăng ký sử dụng tính năng thanh toán tự động.
Thông tin chung
- API khởi tạo giao dịch được gọi từ server của Đối tác để thiết lập một giao dịch đăng ký/hủy/chỉnh sửa thanh toán tự động mới để người dùng có thể thực hiện thanh toán trên MB App.
Đặc tả
Endpoint
POST /api/merchant/v2/auto-debit
Header
Content-Type: application/json
MERCHANT_CODE: Mã đối tác
MERCHANT_SECRET: Khóa bí mật của Đối tác
Dữ liệu truyền lên
| Tham số | Mô tả |
|---|---|
sessionId | BẮT BUỘC. Mã phiên đăng nhập (Được trả về từ API xác minh token) Trường này được thêm vào bản update ngày 23/03/2022 và sẽ được hỗ trợ KHÔNG bắt buộc đến hết ngày 01/04/2022 |
cif | BẮT BUỘC. Kiểu String, tối đa 45 ký tự. Mã khách hàng tại MB |
requestType | BẮT BUỘC. Loại yêu cầu, truyền một trong bốn loại REGISTER: đăng ký REGISTER_AND_FIRST_PAYMENT: đăng ký kèm thanh toán lần đầu UPDATE: chỉnh sửa thông tin thanh toán tự động CANCEL: hủy thanh toán tự động |
autoDebitId | KHÔNG bắt buộc. Kiểu Long. Mã đăng ký thanh toán tự động. Bắt buộc khi truyền requestType = UPDATE hoặc requestType = CANCEL |
amount | KHÔNG bắt buộc. Kiểu Long. Số tiền thực hiện giao dịch Yêu cầu: 0 ≤ amount < 10 tỉ VND |
description | KHÔNG bắt buộc. Kiểu String, tối đa 48 ký tự. Nội dung giao dịch. Bắt buộc truyền khi requestType = REGISTER, REGISTER_AND_FIRST_PAYMENT |
firstPaymentAmount | KHÔNG bắt buộc. Kiểu Long. Số tiền thanh toán lần đầu.Bắt buộc truyền khi requestType = REGISTER_AND_FIRST_PAYMENT. Yêu cầu: 0 ≤ amount < 10 tỉ VND |
firstPaymentDescription | KHÔNG bắt buộc. Kiểu String, tối đa 48 ký tự. Nội dung giao dịch lần đầu. Bắt buộc khi requestType = REGISTER_AND_FIRST_PAYMENT |
frequencyUnit | KHÔNG bắt buộc. Kiểu String, tần suất thanh toán. Không bắt buộc với Merchant có cấu hình autodebitType = BILLING_RECEIVE_BILLS. Truyền một trong các giá trị DAY, WEEK, MONTH, YEAR |
dayOfAutoDebit | KHÔNG bắt buộc. Kiểu String, thời gian thực hiện autodebit. Trong trường hợp frequencyUnit = DAY, để null. Trong trường hợp frequencyUnit = WEEK nhận các giá trị nhận giá trị MON, TUE, WED, THU, FRI, SAT, SUN Trong trường hợp frequencyUnit = MONTH nhận một giá trị từ 1->28 Trong trường hợp frequencyUnit = YEAR nhận giá trị theo format: DD/MM .Ví dụ 28/12 |
contractCode | KHÔNG bắt buộc. Kiểu String, tối đa 50 ký tự. Mã hợp đồng đăng kí autodebit. Bắt buộc truyền khi requestType = REGISTER, REGISTER_AND_FIRST_PAYMENT |
paymentTransactionType | KHÔNG bắt buộc. Kiểu String. Mã loại giao dịch. Bắt buộc truyền khi requestType = REGISTER, REGISTER_AND_FIRST_PAYMENT |
successMessage | KHÔNG bắt buộc. Kiểu String, tối đa 500 ký tự. Thông báo khi khách hàng thanh toán thành công Nếu không truyền tham số này, hệ thống sẽ sử dụng thông báo mặc định của hệ thống. |
metadata | KHÔNG bắt buộc. Kiểu String, tối đa 500 ký tự. Chuỗi dữ liệu bất kỳ chưa dữ liệu bổ sung cho giao dịch và sẽ được trả về cho Đối tác khi truy vấn thông tin giao dịch hoặc khi thông báo giao dịch thành công |
Dữ liệu trả về
| Tham số | Mô tả |
|---|---|
autoDebitId | Kiểu String, tối đa 30 ký tự. ID bản ghi đăng kí |
merchant.code | Kiểu String, tối đa 100 ký tự. Mã đối tác |
merchant.name | Kiểu String, tối đa 256 ký tự. Tên đối tác |
cif | Kiểu String, tối đa 45 ký tự. Mã khách hàng MB |
amount | Kiểu Long. Số tiền thực hiện giao dịch |
description | Kiểu String, tối đa 48 ký tự. Nội dung giao dịch |
scheduledPattern | Kiểu String, tối đa 50 ký tự. Chuỗi cron exprestion được ghép từ Thời gian và Tần suất autodebit |
requestType | Kiểu String, tối đa 50 ký tự. Loại yêu cầu REGISTER, REGISTER_AND_FIRST_PAYMENT, UPDATE, CANCEL |
paymentTransactionType.code | Kiểu String, tối đa 100 ký tự. Mã loại giao dịch |
paymentTransactionType.name | Kiểu String, tối đa 256 ký tự. Tên loại giao dịch |
paymentTransactionType.allowCard | Kiểu Boolean. Cho phép thanh toán bằng thẻ hay không true: Có cho phép false: Không cho phép |
successMessage | Kiểu String, tối đa 2000 ký tự. Thông báo khi thanh toán thành công |
contractCode | Kiểu String, tối đa 2000 ký tự. Mã hợp đồng |
autodebitStatus | Kiểu String, tối đa 50 ký tự. Trạng thái của autodebit; bao gồm: REGISTER_PENDING: Đang chờ xác nhận đăng ký UPDATE_PENDING: Đang chờ xác nhận Update CANCEL_PENDING: Đang chờ xác nhận Hủy |
billerCustomerId | Kiểu String, tối đa 100 ký tự. Trả về chuỗi merchantCode + contractCode |
billerCustomerCode | Kiểu String, tối đa 100 ký tự. Trả về chuỗi merchantCode + contractCode |
requestId | Kiểu String, tối đa 100 ký tự. Trả về id của request |
autoDebitType | Kiểu String, tối đa 100 ký tự. Loại giao dịch autodebit TOPUP: Thanh toán cố định BILLING_RECEIVE_BILLS: Thanh toán với số tiền ko cố định (hàng kỳ nhận list bill từ đối tác để hạch toán) BILLING_GET_BILLS: Thanh toán với số tiền ko cố định (hàng kỳ quét list bill của đối tác để hạch toán) |
retryDay | Kiểu int. Số ngày retry |
recordId | Kiểu String, tối đa 50 ký tự. ID bản ghi autodebit trong hệ thống của Thu chi hộ( Chỉ tra ra nếu type là Chỉnh sửa hoặc Hủy) |
metadata | Kiểu String, tối đa 500 ký tự. Chuỗi dữ liệu bổ sung thông tin cho giao dịch được Đối tác truyền vào khi khởi tạo giao dịch |
createdTime | Kiểu Date. Thời điểm tạo giao dịch Theo định dạng yyyy-MM-dd'T'HH:mm:ss (ISO 8601) |
payment.firstPaymentAmount | Kiểu Long. Số tiền thanh toán lần đầu |
payment.firstPaymentDescription | Kiểu String, tối đa 48 ký tự. Mô tả cho giao dịch thanh toán lần đầu |
payment.paymentTransactionStatus | Kiểu String, tối đa 45 ký tự. Trạng thái của thanh toán lần đầu nếu kèm: PENDING: chờ xác nhận thanh toán |