Bỏ qua

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_urlhttps://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 đến ipn_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.statusCLOSED
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.resultAPPROVED
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.statusCLOSED
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.resultAPPROVED
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