Pay2S

Appearance

Xử lý kết quả thanh toán (Payment Notification) ​

Giao diện (Redirect) ​

Sau khi luồng thanh toán hoàn tất, khách hàng được điều hướng đến redirectUrl mà bên đối tác đã cung cấp trong create request. Một vài thông số sẽ được thêm vào URL theo dạng sau:

Method: POST
json
redirectUrl ?{parameters}

IPN - Instant Payment Notification ​

Hệ thống của Pay2S sử dụng API được khai báo trong ipnUrl để gửi HTTP request với cấu hình bên dưới đến hệ thống đối tác.

Method: POST
AttributeValueDescription
URLipnUrlURL
MethodPOSTPhương thức của HTTP request
HeadersContent-type: application/jsonHTTP Headers
PayloadResult Transaction Nội dung của HTTP body

Mẫu Request IPN

json
curl -X 'POST' 'https://example.com/pay2s_ipn' -H 'content-type: application/json' -d $'{
  "partnerCode":"PAY2S",
  "orderId":"01234567890123451633504872421",
  "requestId":"01234567890123451633504872421",
  "amount":1000,
  "orderInfo":"Test Thue 1234556",
  "orderType":"Pay2S_wallet",
  "transId":2588659987,
  "resultCode":0,
  "message":"Giao dịch thành công.",
  "payType":"qr",
  "signature":"90482b3881bdf863d5f61ace078921bbc6dbb58b2fded35261c71c9af3b1ce4f"
}'

Response của đối tác sẽ đến Pay2S sau khi Pay2S gửi HTTP request đến địa chỉ ipnUrl.

INFO

Bên đối tác cần phản hồi với HTTP code 204 (không cần gửi thêm nội dung)!

Lưu ý: Đối tác cần phản hồi lại trong vòng 30 giây.

INFO

Đối tác cần kiểm tra tính hợp lệ của chữ ký trong IPN để đảm bảo kết quả của giao dịch. Amount và Currency trong notification phải khớp với Amount và Currency đối tác lưu trong database bên đó!

Field resultCode và message do đối tác xử lý. Tham chiếu đến result code mà Pay2S trả về. Pay2S sẽ dùng những thông tin này để phản hồi lại khách hàng nếu có bất cứ lỗi nào xảy ra trong quá trình xử lý thanh toán bên nhà đối tác.

Trạng Thái Giao Dịch Sử dụng field resultCode để xác định trạng thái của giao dịch:

  • resultCode = 0: giao dịch thành công.
  • resultCode = 9000: giao dịch được cấp quyền (authorization) thành công .
  • resultCode <> 0: giao dịch thất bại. Tham khảo Result code để xác định chi tiết lỗi của giao dịch.

INSTANT PAYMENT NOTIFICATION ​

Instant Payment Notification (IPN) là thông điệp được gửi từ Nhà Cung Cấp Dịch Vụ Thanh Toán - Payment Service Provider (PSP) đến Bên Sử Dụng Dịch Vụ Thanh Toán - Payment Service Consumer (PSC). Việc này sử dụng giao thức HTTP và quy trình này là bất đồng bộ.

Tại sao sử dụng IPN ​

Instant Payment Notification (IPN) được sử dụng để thông báo (notify) kết quả giao dịch ngay lâp tức dến PSC:

  • Thanh Toán: Web, SmartTv.

  • Thanh Toán Trực Tuyến

  • Thanh Toán Định Kỳ Đối tác có thể sử dụng hệ thống của mình để xử lý thông tin nhận được từ PSP:

  • Cập nhật trạng thái giao dịch (khuyên dùng)

  • Cập nhật số dư tài khoản (nạo tiền), xuất sản phẩm, thông báo kết quả giao dịch đến ứng dụng di động,...

  • Gửi hóa đơn điện tử Sử dụng IPN để khắc phục trường hợp thanh toán thành công nhưng người dùng không nhận được sản phẩm. Lý do:

  • Người dùng đóng trình duyệt

  • Không thể điều hướng đến trang ban đầu của đối tác: do đường truyền, hệ thông quá tải,...

Cách thực thi IPN ​

Đối tác cần tạo API phía backend để 'lắng nghe' kết quả từ Pay2S và cung cấp URL của API đó trong field ipnUrl.

Sau khi người dùng sử dụng thanh toán trên Pay2S (web hoặc app), Pay2S sẽ thông báo kết quả giao dịch ngay lập tức đến URL này. API của đối tác nhận kết quả thanh toán và tiếp tực xử lý trong hệ thông bên họ.

Xây dựng API ​

  • HTTP Produces Header: Sử dụng để Pay2S gửi HTTP Request Content-Type: application/json

  • HTTP Consumers Header: Đối tác phản hồi lại Pay2S: HTTP code 204 (không cần gửi thêm nội dung)

  • Endpoint: URL chỉ nên bao gồm đường dẫn, tham số và không chứa ký tự đặc biệt, unicode hoặc khoảng cách.