Webhook Notifications

Receive real-time notifications when funds arrive in or are returned from your virtual account. Pockyt sends HTTP POST requests to your configured callback URL whenever a deposit event occurs, eliminating the need for polling.

The webhook system supports two event types:

1. Deposit Received (deposit.received): Pockyt notifies your system when an inbound wire or ACH transfer is credited to your virtual account.
2. Deposit Returned (deposit.returned): Pockyt notifies your system when a previously received deposit is returned — for example, due to a closed account or compliance issue.

How It Works

sequenceDiagram
    participant EX as External Sender
    participant PA as Pockyt
    participant MB as Merchant Backend

    Note over PA: Deposit arrives
    EX->>PA: Inbound wire / ACH
    PA->>PA: Credit virtual account

    Note over PA: Webhook notification
    PA->>MB: POST callback URL (deposit.received)
    MB->>MB: Verify signature
    MB->>MB: Process event (idempotency check)
    MB-->>PA: HTTP 200 "success"

    Note over PA: If delivery fails
    PA->>MB: Retry (up to 5 attempts)

When a deposit event occurs, Pockyt delivers a signed JSON payload to your callback URL. Your system verifies the signature, processes the event, and responds with HTTP 200 and the body success (lowercase). If Pockyt does not receive this exact response, it retries delivery automatically.

Notification Payloads

deposit.received

Sent when an inbound wire or ACH transfer is credited to your virtual account.

{
  "merchantNo": "M123456",
  "storeNo": "S789",
  "transactionNo": "DEP20260429001",
  "amount": "500.00",
  "currency": "USD",
  "status": "SUCCESS",
  "timestamp": "1717123200",
  "accountNumber": "****1234",
  "depositType": "BANK_TRANSFER",
  "verifySign": "abc123def456..."
}

deposit.returned

Sent when a previously received deposit is returned.

{
  "merchantNo": "M123456",
  "storeNo": "S789",
  "transactionNo": "DEP20260429001",
  "amount": "500.00",
  "currency": "USD",
  "status": "RETURNED",
  "timestamp": "1717123200",
  "returnReason": "ACCOUNT_CLOSED",
  "returnDate": "2026-04-29",
  "verifySign": "xyz789uvw012..."
}

Signature Verification

Every webhook payload includes a verifySign field. Verify this signature before processing any event to confirm the notification originated from Pockyt.

Signature formula:

verifySign = MD5(sorted_params_string + "&" + MD5(yuansferToken))

Verification steps:

1. Parse the JSON request body and extract the verifySign value.
2. Remove the verifySign field from the parameter set.
3. Sort the remaining parameters alphabetically by key (ASCII ascending order).
4. Concatenate them as key1=value1&key2=value2&....
5. Calculate MD5(concatenated_params + "&" + MD5(yuansferToken)).
6. Compare your calculated value against the extracted verifySign. If they match, the notification is authentic.

You can find more details in the following guide: Verifying webhook signatures

⚠️

Important: Always verify the signature before processing the event.

Response Requirements

Your callback URL must respond correctly for Pockyt to mark the notification as delivered:

⚠️

Important: Only an HTTP 200 response with the exact body success (lowercase) stops the retry cycle. Any other response triggers retries.

Retry Strategy

When your callback URL does not return the expected response, Pockyt retries delivery automatically:

After 5 failed attempts, Pockyt stops retrying and marks the notification as failed. You can view failed notifications and trigger manual resends from the merchant portal.

Key Considerations

1. Signature Verification: Always verify verifySign before processing any webhook event. Use your yuansferToken from the merchant portal as the signing key. If verification fails, reject the request; do not process it. See the Signature Verification section above for more details.

2. Idempotency is Required: Because Pockyt retries failed deliveries, your system will receive duplicate notifications. Implement deduplication using transactionNo to ensure each event is processed exactly once.

3. Respond Quickly: Keep your webhook handler lightweight. If your business logic is complex or involves external calls, accept the webhook (return success) and process the event asynchronously. Pockyt recommends a processing timeout under 30 seconds.

4. Testing: Use the merchant portal's "Send Test Notification" feature to verify your callback URL, signature verification, and response handling before going live.