Nhận kết quả giao dịch từ Paykit PGW¶
Thông qua Redirect¶
Sau khi có kết quả thanh toán đơn hàng, Paykit redirect người mua về lại trang của đối tác merchant bằng giá trị success_url (trong trường hợp thanh toán thành công) và cancel_url (trong trường hợp thanh toán thất bại, hết hạn hoặc hủy thanh toán).
Các giá trị mid, merchant_id, payment_id, result sẽ được gửi kèm tương ứng như các query params.
Ví dụ: Merchant có id MC_001 tạo thanh toán PAY_001 với success_url là https://mc-001.com/abc. Sau khi người mua thanh toán thành công, người mua sẽ được redirect về: https://mc-001.com/abc?mid=MC_001&merchant_id=MC_001&payment_id=PAY_001&result=APPROVED
Lưu ý:
Khi nhận được redirect hợp lệ, merchant kiểm tra xem có nhận được thông báo qua IPN hay chưa, nếu chưa Merchant sử dụng API Truy vấn thanh toán để lấy kết quả cập nhật vào hệ thống.
Thông qua Instant Payment Notification (IPN)¶
Mỗi khi trạng thái thanh toán được cập nhật hoặc có giao dịch hoàn tiền, Paykit sẽ gửi POST request để thông báo: đến ipn_url do merchant cung cấp để thông báo.
- Đối với Merchant: Nếu merchant có cung cấp
ipn_urlkhi tạo thanh toán, Paykit sẽ thông báo đếnipn_url. Nếu không, Paykit sẽ thông báo đến Webhook url mà merchant cài đặt ở Merchant portal (nếu có). - Đối với Platform: Paykit sẽ thông báo đến Webhook url mà platform cài đặt ở Platform portal (nếu có).
Nếu ipn_url là HTTPS
Khi nhận được thông báo, đối tác merchant xác thực yêu cầu là hợp lệ từ Paykit bằng cách kiểm tra secret-key ở header. Nếu kết quả chưa được cập nhật, đối tác merchant tiến hành cập nhật vào hệ thống.
Header:
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| request-id | String | ID duy nhất của request |
| secret-key | String | Merchant so sánh giá trị này với IPN Secret Key khi đăng ký dịch vụ với Paykit để xác thực request |
Request body:
| Tham số | Kiểu dữ liệu | Ràng buộc | Bắt buộc | Mô tả |
|---|---|---|---|---|
| request_at | Datetime | Format ISO 8601 | ✔ | Thời điểm gửi request |
| mid | String | • Min length: 1 • Max length: 255 | ✔ | ID của merchant |
| payment | Json | Gồm các tham số bên dưới | ✔ | Dữ liệu thanh toán |
| payment.id | String | • Min length: 1 • Max length: 50 | ✔ | ID duy nhất để phân biệt các thanh toán |
| payment.payment_method | String | Một trong các giá trị: DOMESTIC_CARD, INTERNATIONAL_CARD, BANK_TRANSFER | ✔ | Phương thức thanh toán |
| payment.total_amount | Decimal | • Min value: 0.000001 • Max digits: 30 • Decimal places: 6 | ✔ | Tổng giá trị thanh toán |
| payment.captured_amount | Decimal | • Min value: 0 • Max digits: 30 • Decimal places: 6 | ✔ | Số tiền ghi nhận đã thanh toán |
| payment.refunded_amount | Decimal | • Min value: 0 • Max digits: 30 • Decimal places: 6 | ✔ | Số tiền đã hoàn trả |
| payment.refunding_amount | Decimal | • Min value: 0 • Max digits: 30 • Decimal places: 6 | ✔ | Số tiền đang hoàn trả |
| payment.currency | String | Một trong các giá trị: VND | ✔ | Đơn vị tiền tệ thanh toán |
| payment.status | String | Một trong các giá trị: OPEN, PROCESSING, CLOSED | ✔ | Trạng thái thanh toán |
| payment.result | String | Một trong các giá trị: CANCELED, APPROVED, DENIED, EXPIRED | Kết quả thanh toán | |
| payment.due_time | Datetime | Format ISO 8601 | ✔ | Thời điểm hết hạn thanh toán |
| payment.start_at | Datetime | Format ISO 8601 | ✔ | Thời điểm khởi tạo thanh toán |
| payment.completed_at | Datetime | Format ISO 8601 | Thời điểm hoàn thành thanh toán | |
| refund | Json | Gồm các tham số bên dưới Bắt buộc nếu có giao dịch hoàn tiền mới được tạo | Dữ liệu giao dịch hoàn tiền | |
| refund.id | String | • Min length: 1 • Max length: 50 | ✔ | ID duy nhất để phân biệt các giao dịch hoàn tiền |
| refund.payment_id | String | • Min length: 1 • Max length: 50 | ✔ | ID của giao dịch thanh toán được hoàn tiền |
| refund.amount | Decimal | • Min value: 0.000001 • Max digits: 30 • Decimal places: 6 | ✔ | Số tiền hoàn trả |
| refund.currency | String | Một trong các giá trị: VND | ✔ | Đơn vị tiền tệ |
| refund.status | String | Một trong các giá trị: PROCESSING, CLOSED | ✔ | Trạng thái của giao dịch hoàn tiền |
| refund.result | String | Một trong các giá trị: APPROVED, DENIED | Kết quả hoàn tiền | |
| refund.start_at | Datetime | Format ISO 8601 | ✔ | Thời điểm khởi tạo giao dịch hoàn tiền |
| refund.completed_at | Datetime | Format ISO 8601 | Thời điểm hoàn thành giao dịch hoàn tiền |
Nếu ipn_url là HTTP
Khi nhận được thông báo, đối tác merchant cần sử dụng API Truy vấn thanh toán để lấy kết quả. Nếu kết quả chưa được cập nhật, đối tác merchant tiến hành cập nhật vào hệ thống.
Header:
| Tham số | Kiểu dữ liệu | Mô tả |
|---|---|---|
| request-id | String | ID duy nhất của request |
Request body:
| Tham số | Kiểu dữ liệu | Ràng buộc | Bắt buộc | Mô tả |
|---|---|---|---|---|
| request_at | Datetime | Format ISO 8601 | ✔ | Thời điểm gửi request |
| mid | String | • Min length: 1 • Max length: 255 | ✔ | ID của merchant |
| payment_id | String | • Min length: 1 • Max length: 50 | ✔ | ID duy nhất để phân biệt các thanh toán |
| refund_id | String | • Min length: 1 • Max length: 50 | Bắt buộc nếu có giao dịch hoàn tiền mới được tạo | ID duy nhất để phân biệt các giao dịch hoàn tiền |