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
, 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&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_url
khi 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/Platform 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ố | Đặc tả dữ liệu | Mô tả |
---|---|---|
request_at | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Required | Thời điểm gửi request |
mid | Kiểu dữ liệu: String • Max length: 255 Bắt buộc: Required | ID của merchant |
payment | Kiểu dữ liệu: Json Bao gồm các tham số bên dưới Bắt buộc: Required | 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 |
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 |
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 |
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 |
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ả |
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ả |
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 |
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 |
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 có nếu payment .status là CLOSED | Kết quả thanh toán |
payment .due_time | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Required | Thời điểm hết hạn thanh toán |
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 |
payment .completed_at | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Conditional Bắt buộc nếu payment .result là APPROVED | Thời điểm hoàn thành thanh toán |
refund | Kiểu dữ liệu: Json Bao gồm các tham số bên dưới Bắt buộc: Conditional 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 | 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 giao dịch hoàn tiền |
refund .payment_id | Kiểu dữ liệu: String • Min length: 1 • Max length: 50 Bắt buộc: Required | ID của giao dịch thanh toán được hoàn tiền |
refund .amount | Kiểu dữ liệu: Decimal • Min value: 0.000001 • Max digits: 30 • Decimal places: 6 Bắt buộc: Required | Số tiền hoàn trả |
refund .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ệ |
refund .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 của giao dịch hoàn tiền |
refund .result | Kiểu dữ liệu: String Một trong các giá trị: • APPROVED • DENIED Bắt buộc: Conditional Bắt buộc có nếu refund .status là CLOSED | Kết quả hoàn tiền |
refund .start_at | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Required | hời điểm khởi tạo giao dịch hoàn tiền |
refund .completed_at | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Conditional Bắt buộc nếu refund .result là APPROVED | 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ố | Đặc tả dữ liệu | Mô tả |
---|---|---|
request_at | Kiểu dữ liệu: Datetime • Format ISO 8601 Bắt buộc: Required | Thời điểm gửi request |
mid | Kiểu dữ liệu: String • Max length: 255 Bắt buộc: Required | ID của merchant |
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 |
refund_id | Kiểu dữ liệu: String • Min length: 1 • Max length: 50 Bắt buộc: Conditional 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 |