Tạo thanh toán theo mô hình Payment Page¶
Merchant Server gửi thông tin thanh toán đến Paykit PGW để tạo thanh toán theo mô hình Payment Page.
Đặc tả API¶
Tham số | Mô tả |
---|---|
Method | POST |
Endpoint | {base_url}/v2/payment-page-checkout |
Content-Type | application/json |
Request¶
Tham số | Đặc tả dữ liệu | Mô tả |
---|---|---|
payment_method | Kiểu dữ liệu: String Các giá trị hợp lệ: • DOMESTIC_CARD • INTERNATIONAL_CARD • BANK_TRANSFER Bắt buộc: Conditional Bắt buộc có 1 trong 2 tham số payment_method hoặc available_payment_methods .Trong trường hợp đã có payment_method , tham số available_payment_methods sẽ bị bỏ qua. | Xác định phương thức thanh toán cho payment. Khi payment_method được xác định, Paykit sẽ không hiển thị trang chọn phương thức thanh toán cho người mua, mà hiển thị ngay giao diện thanh toán tương ứng với phương thức thanh toán đã xác định.Ví dụ: INTERNATIONAL_CARD |
available_payment_methods | Kiểu dữ liệu: List[String] Các giá trị hợp lệ: • DOMESTIC_CARD • INTERNATIONAL_CARD • BANK_TRANSFER Bắt buộc: Conditional Bắt buộc có 1 trong 2 tham số payment_method hoặc available_payment_methods .Trong trường hợp đã có payment_method , tham số available_payment_methods sẽ bị bỏ qua. | Xác định các phương thức thanh toán mà người mua có thể lựa chọn. Nếu payment_method chưa được xác định, Paykit sẽ hiển thị trang chọn phương thức thanh toán cho người mua.Ví dụ: [“DOMESTIC_CARD”, “INTERNATIONAL_CARD”, ”BANK_TRANSFER”] |
payment | Kiểu dữ liệu: Json Gồm các tham số bên dưới Bắt buộc: Required | Thông tin thanh toán |
payment .id | Kiểu dữ liệu: String • Min length: 1 • Max length: 50 Bắt buộc: Required | ID duy nhất để phân biệt các thanh toán Ví dụ: PAY_0001 |
payment .amount | Kiểu dữ liệu: Decimal • Min value: 0.000001 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Tổng giá trị thanh toán Ví dụ: 100000 |
payment .currency | Kiểu dữ liệu: String Giá trị hợp lệ: VND Bắt buộc: Required | Đơn vị tiền tệ thanh toán Ví dụ: VND |
payment .currency | Kiểu dữ liệu: String • Max length: 1023 Bắt buộc: Optional | Dòng mô tả cho thanh toán Ví dụ: Thanh toán cho đơn hàng ABC |
payment .due_time | Kiểu dữ liệu: Datetime Format ISO 8601 Nếu giá trị này không được cung cấp, mặc định thanh toán hết hạn sau 30 phút. Bắt buộc: Optional | Thời điểm thanh toán hết hạn. Ví dụ: 2023-09-10T00:00:00.000000Z |
payment .success_url | Kiểu dữ liệu: String • Url với format hợp lệ • Max length: 255 Bắt buộc: Required đối với MerchantTham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform. Platform sẽ đăng ký success_url cố định khi tích hợp với Paykit | Khi thanh toán thành công, Paykit sẽ redirect người mua đến success_url Ví dụ: https://www.abc.com/success-payment |
payment .cancel_url | Kiểu dữ liệu: String • Url với format hợp lệ • Max length: 255 Bắt buộc: Required đối với MerchantTham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform. Platform sẽ đăng ký cancel_url cố định khi tích hợp với Paykit | Khi thanh toán thất bại (hoặc hủy thanh toán, thanh toán hết hạn), Paykit sẽ redirect người mua đến cancel_url Ví dụ: https://www.abc.com/cancel-payment |
payment .ipn_url | Kiểu dữ liệu: String • Url với format hợp lệ • Max length: 255 Bắt buộc: Optional Nếu giá trị này không được cung cấp, url được merchant cấu hình khi đăng ký dịch vụ sẽ được sử dụng. Tham số này chỉ có hiệu lực đối với Merchant, không có hiệu lực với Platform. Platform sẽ đăng ký ipn_url cố định khi tích hợp với Paykit | Khi có đơn hàng thay đổi trạng thái, Paykit sẽ thực hiện POST đến url này để thông báo. Ví dụ: https://www.abc-ipn.com |
Ví dụ Request:
Response¶
Tham số | Đặc tả dữ liệu | Mô tả |
---|---|---|
response_at | Kiểu dữ liệu: Datetime Format ISO 8601 Bắt buộc: Required | Thời điểm respose được trả về Ví dụ: 2024-01-16T00:00:00.000001Z |
result | Kiểu dữ liệu: String Một trong các giá trị sau • SUCCESS : Xử lý yêu cầu thành công • FAILURE : Xử lý yêu cầu thất bại, dựa vào gateway_code để biết rõ nguyên nhân thất bại • PENDING : Giao dịch đang được xử lý. Khi có kết quả thành công hoặc thất bại, merchant sẽ được thông báo qua IPN • ERROR : Có lỗi từ yêu cầu, lỗi trong quá trình xử lý, hoặc không rõ nguyên nhân thất bại của yêu cầu • UNKNOWN : Không xác định kết quả của yêu cầuBắt buộc: Required | Kết quả tổng thể sau khi xử lý yêu cầu Ví dụ: SUCCESS |
gateway_code | Kiểu dữ liệu: String Một trong các giá trị sau: • APPROVED : Thành công • DUPLICATE_PAYMENT_ID : ID thanh toán đã tồn tại • PAYMENT_METHOD_NOT_SUPPORTED : Phương thức thanh toán không được hỗ trợ • INVALID_AMOUNT : Số tiền thanh toán không hợp lệ • INVALID_DUE_TIME : Thời gian hết hạn không hợp lệ • PAYMENT_TOTAL_AMOUNT_LIMIT_EXCEED : Vượt quá tổng hạn mức thanh toán • MERCHANT_ACCOUNT_HAS_BEEN_LOCKED : Merchant account đã bị khóa • MERCHANT_ACCOUNT_HAS_BEEN_CLOSED : Merchant account đã bị đóng • PLATFORM_HAS_BEEN_LOCKED : Platform đã bị khóa • PLATFORM_HAS_BEEN_CLOSED : Platform đã bị đóngBắt buộc: Conditional Bắt buộc khi result là SUCCESS ,FAILURE | Tóm tắt thành công hoặc nguyên nhân thất bại Ví dụ: APPROVED |
checkout_url | Kiểu dữ liệu: String URL với format hợp lệ Bắt buộc: Conditional Bắt buộc khi result là SUCCESS | Đường dẫn trang thanh toán của Paykit. Merchant redirect người mua hàng đến trang này để thực hiện thanh toán. Ví dụ: https://payment-page.paykit.vn/merchant/MC_001/payment/PAY_0001 |
payment | Kiểu dữ liệu: Json Gồm các tham số bên dưới Bắt buộc: Conditional Bắt buộc khi result là SUCCESS | Dữ liệu thanh toán |
payment .id | Kiểu dữ liệu: String • Min length: 1 • Max length: 50 Bắt buộc: Required | ID duy nhất để phân biệt các thanh toán Ví dụ: PAY_0001 |
payment .payment_method | Kiểu dữ liệu: String Một trong các giá trị: • DOMESTIC_CARD • INTERNATIONAL_CARD • BANK_TRANSFER Bắt buộc: Required | Phương thức thanh toán Ví dụ: INTERNATIONAL_CARD |
payment .total_amount | Kiểu dữ liệu: Decimal • Min value: 0.000001 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Tổng giá trị thanh toán Ví dụ: 100000 |
payment .captured_amount | Kiểu dữ liệu: Decimal • Min value: 0 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Số tiền ghi nhận đã thanh toán Ví dụ: 0 |
payment .refunded_amount | Kiểu dữ liệu: Decimal • Min value: 0 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Số tiền đã hoàn trả Ví dụ: 0 |
payment .refunding_amount | Kiểu dữ liệu: Decimal • Min value: 0 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Số tiền đang hoàn trả Ví dụ: 0 |
payment .currency | Kiểu dữ liệu: String Một trong các giá trị: • VND Bắt buộc: Required | Đơn vị tiền tệ thanh toán Ví dụ: VND |
payment .status | Kiểu dữ liệu: String Một trong các giá trị: • OPEN • PROCESSING • CLOSED Bắt buộc: Required | Trạng thái thanh toán Ví dụ: CLOSED |
payment .result | Kiểu dữ liệu: String Một trong các giá trị: • APPROVED • DENIED • CANCELED • EXPIRED Bắt buộc: Conditional Bắt buộc khi payment .status là CLOSED | Kết quả thanh toán Ví dụ: APPROVED |
payment .due_time | Kiểu dữ liệu: Datetime Format ISO 8601 Bắt buộc: Required | Thời điểm thanh toán hết hạn. Ví dụ: 2024-01-20T00:00:00.000000Z |
payment .start_at | Kiểu dữ liệu: Datetime Format ISO 8601 Bắt buộc: Required | Thời điểm khởi tạo thanh toán. Ví dụ: 2024-01-16T00:00:00.000000Z |
payment .completed_at | Kiểu dữ liệu: Datetime Format ISO 8601 Bắt buộc: Conditional Bắt buộc khi payment .result laf APPROVED | Thời điểm hoàn thành thanh toán Ví dụ: 2024-01-17T00:00:00.000000Z |
bank_transfer_payment | Kiểu dữ liệu: Json Gồm các tham số bên dưới Bắt buộc: Conditional Bắt buộc khi result là SUCCESS và payment_method là BANK_TRANSFER | Thông tin bổ sung cho PTTT chuyển khoản ngân hàng |
bank_transfer_payment .vietqr_data | Kiểu dữ liệu: String URL với format hợp lệ Bắt buộc: Required | Dữ liệu dùng để tạo mã VietQR. Merchant có thể lựa chọn redirect người mua theo checkout_url, hoặc có thể lựa chọn tự chủ động hiển thị mã QR theo dữ liệu VietQR này cho người mua. Ví dụ: 00020101021238620010A000000727013200069704480118PKTTEST1234567890A0208QRIBFTTA53037045405100005802VN62370833Thanh toan cho PKTTEST1234567890A6304DC58 |
bank_transfer_payment .status | Kiểu dữ liệu: String Một trong các giá trị: • ACTIVE : Tài khoản ngân hàng (VA) còn hiệu lực• INACTIVE : Tài khoản ngân hàng (VA) không còn hiệu lựcBắt buộc: Required | Ví dụ: ACTIVE |
error | Kiểu dữ liệu: Json Gồm các tham số bên dưới Bắt buộc: Conditional Bắt buộc khi result là ERROR | Các thông tin cụ thể hơn về lỗi |
error .cause | Kiểu dữ liệu: String Một trong các giá trị sau: • INVALID_REQUEST : Các tham số của yêu cầu được gửi không hợp lệ • REQUEST_REJECTED : Yêu cầu bị từ chối • SERVER_BUSY : Server hiện đang bận, không thể xử lý yêu cầu • SERVER_FAILED : Lỗi serverBắt buộc: Required | Loại nguyên nhân gây ra lỗi Ví dụ: INVALID_REQUEST |
error .explanation | Kiểu dữ liệu: String Bắt buộc: Conditional Bắt buộc khi error .cause là SERVER_BUSY hoặc REQUEST_REJECTED | Nội dung mô tả lỗi Ví dụ: The request was rejected because we detected unusual behavior |
error .field | Kiểu dữ liệu: Json Bắt buộc: Conditional Bắt buộc khi error .cause là INVALID_REQUEST Keys là tên các tham số không hợp lệ. Values là danh sách các nội dung xác thực không hợp lệ, có kiểu là Json (khi các keys lồng nhau) hoặc List[String] . | Ví dụ: {"order": {"currency": ["\"USD\" is not a valid choice."] }} |
error .support_code | Kiểu dữ liệu: String Bắt buộc: Conditional Bắt buộc khi error .cause là SERVER_FAILED | Mã lỗi nội bộ giúp Paykit dễ dàng hơn trong việc hỗ trợ đối tác khi gặp lỗi Server Ví dụ: 6f4c81832a6d45b1be2ab19edd267414 |
Ví dụ Response: