Pay2S

Appearance

🔔 Webhook / Thông báo giao dịch tự động ​

🧭 Giới thiệu ​

Webhook Partner API cho phép đối tác nhận thông báo tự động (IN/OUT) mỗi khi có giao dịch mới phát sinh từ các tài khoản ngân hàng đã liên kết.
Đây là cơ chế push notification theo thời gian thực — giúp hệ thống đối tác xử lý thanh toán, đối soát, hoặc cập nhật hóa đơn tức thì.

🔐 Header chung ​

Authorization: Bearer <token>
Content-Type: application/json

1️⃣ Tạo webhook mới ​

POST https://api-partner.pay2s.vn/v1/webhooks

Body mẫu ​

json
{
  "user_bank_id": 25,
  "webhook_url": "https://merchant-domain.com/pay2s/handler",
  "type": "IN"
}

Giải thích ​

TrườngMô tả
user_bank_idID của tài khoản ngân hàng cần gắn webhook (lấy từ /v1/banks)
webhook_urlURL nhận dữ liệu giao dịch
typeLoại giao dịch cần nhận (IN, OUT, ALL)

Phản hồi mẫu ​

json
{
  "status": true,
  "message": "Webhook đã được thêm thành công.",
  "token": "e3a19a5a65a48ff3b3ef198fcb2a5a6c"
}

2️⃣ Danh sách webhook ​

GET https://api-partner.pay2s.vn/v1/webhooks

Phản hồi mẫu ​

json
{
  "status": true,
  "data": [
    {
      "id": 101,
      "user_bank_id": 25,
      "webhook_url": "https://merchant-domain.com/pay2s/handler",
      "type": "IN",
      "status": 1,
      "token": "e3a19a5a65a48ff3b3ef198fcb2a5a6c",
      "created_at": "2025-10-14 10:00:12",
      "updated_at": "2025-10-14 10:00:12",
      "bankName": "ACB",
      "accountNumber": "19354957"
    }
  ]
}

3️⃣ Cập nhật webhook ​

PATCH https://api-partner.pay2s.vn/v1/webhooks/{id}

Body mẫu ​

json
{
  "webhook_url": "https://merchant-domain.com/pay2s/new-handler",
  "type": "ALL"
}

Phản hồi:

json
{
  "status": true,
  "message": "Webhook đã được cập nhật thành công."
}

4️⃣ Bật / Tắt trạng thái webhook ​

PATCH https://api-partner.pay2s.vn/v1/webhooks/{id}/toggle

Cho phép nhanh chóng vô hiệu hóa / kích hoạt webhook mà không cần xóa.

Phản hồi mẫu ​

json
{
  "status": true,
  "message": "Trạng thái webhook đã được cập nhật thành công."
}

5️⃣ Xoá webhook ​

DELETE https://api-partner.pay2s.vn/v1/webhooks/{id}

Phản hồi mẫu ​

json
{
  "status": true,
  "message": "Webhook đã được xóa thành công."
}

Khi xoá, hệ thống cũng sẽ xoá các bản ghi liên quan trong transaction_webhook_history để tránh trùng lặp.

6️⃣ Lịch sử gọi webhook ​

GET https://api-partner.pay2s.vn/v1/webhooks/history

Hiển thị toàn bộ các lần hệ thống Pay2S đã gửi thông báo giao dịch đến endpoint webhook của bạn.

Phản hồi mẫu ​

json
{
  "status": true,
  "data": [
    {
      "id": 991,
      "webhook_id": 101,
      "endpoint": "https://merchant-domain.com/pay2s/handler",
      "status_code": 200,
      "status": 1,
      "call_time": "2025-10-14 11:00:00",
      "response": "Transactions sent successfully",
      "payload": {
        "transactions": [
          {
            "id": 3521,
            "gateway": "ACB",
            "transactionDate": "2025-10-14 10:59:30",
            "transactionNumber": "FT253146879VN",
            "vaNumber": "963869789",
            "accountNumber": "19354957",
            "content": "NAPTIEN MOMO 963869789",
            "transferType": "IN",
            "transferAmount": 200000,
            "checksum": "a8e97b098f45f6e2dfdbf33d10d1dc4b"
          }
        ]
      }
    }
  ]
}

7️⃣ Gửi lại webhook (Resend) ​

POST https://api-partner.pay2s.vn/v1/webhooks/{history_id}/resend

Cho phép đối tác yêu cầu Pay2S gửi lại payload của giao dịch bị lỗi (ví dụ status_code ≠ 200).

Phản hồi mẫu ​

json
{
  "status": true,
  "message": "Gửi lại giao dịch thành công và cập nhật trạng thái webhook."
}

🔁 Cấu trúc Payload gửi đến Webhook của bạn ​

Khi có giao dịch mới, Pay2S sẽ gửi POST tới webhook_url mà bạn đã đăng ký.

Payload mẫu ​

json
{
  "transactions": [
    {
      "id": 3521,
      "gateway": "ACB",
      "transactionDate": "2025-10-14 10:59:30",
      "transactionNumber": "FT253146879VN",
      "vaNumber": "963869789",
      "accountNumber": "19354957",
      "content": "NAPTIEN MOMO 963869789",
      "transferType": "IN",
      "transferAmount": 200000,
      "checksum": "a8e97b098f45f6e2dfdbf33d10d1dc4b"
    }
  ]
}

Header gửi đi ​

Content-Type: application/json
Authorization: Bearer <webhook_token>

Phản hồi yêu cầu ​

Để đánh dấu nhận thành công, endpoint webhook của bạn cần trả về:

json
{ "success": true }

Nếu trả về khác (success=false, hoặc HTTP 4xx/5xx), hệ thống sẽ ghi log lỗi và có thể cho phép gửi lại thủ công qua API resend.

🧪 cURL mẫu ​

Tạo Webhook ​

bash
curl -X POST https://api-partner.pay2s.vn/v1/webhooks \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
  "user_bank_id": 25,
  "webhook_url": "https://merchant-domain.com/pay2s/handler",
  "type": "IN"
 }'

Danh sách Webhook ​

bash
curl -X GET https://api-partner.pay2s.vn/v1/webhooks \
 -H "Authorization: Bearer <token>"

Gửi lại giao dịch ​

bash
curl -X POST https://api-partner.pay2s.vn/v1/webhooks/991/resend \
 -H "Authorization: Bearer <token>"

Ghi chú

  • Mỗi webhook được cấp token riêng (trường token trong dữ liệu webhook). Khi Pay2S gọi webhook của bạn, token này nằm trong header Authorization.
  • Hệ thống ghi log mọi lần gửi — có thể truy xuất qua /v1/webhooks/history.