Skip to main content

Verification Webhooks

The following are verification requests, not final business success notifications:

  • payout.verify.request
  • batch.verify.request

These events use the same request headers and signature verification rule as all other webhook events.

payout.verify.request​

Purpose​

This event is sent before payout auto-review approval. It allows the receiver to verify the payout and return a verification decision.

Request Validation​

The receiver should validate the request using the same webhook rules as standard events:

  1. verify X-Beyounger-Signature
  2. use the raw HTTP body for signature verification
  3. process the request idempotently if needed
  4. validate business fields such as:
    • payout_id
    • amount
    • currency
    • beneficiary_id
    • beneficiary_account_id
    • beneficiary_name
    • beneficiary_account

Current Payload Notes​

The request may include beneficiary information, including:

  • payout_id
  • type
  • account_id
  • reference
  • currency
  • amount
  • status
  • review_status
  • execution_status
  • beneficiary_id
  • beneficiary_account_id
  • beneficiary_name
  • network_code
  • account_type
  • beneficiary_account
  • submitted_at
  • created_at

beneficiary_account object​

This object may include:

  • beneficiary_account_id
  • beneficiary_id
  • display_name
  • network_code
  • account_type
  • key_identifier
  • rail
  • status
  • fields
  • fields_masked

Compatibility Note​

In the current version:

  • beneficiary_account.fields
  • beneficiary_account.fields_masked

return the same raw beneficiary account values.

fields_masked is currently kept for compatibility and is not masked in this flow.

Response Contract​

A verification response is treated as verified only when:

  1. HTTP status is 2xx
  2. and the response body contains:
  • "verified": true

If this signal is not present, the verification result is treated as not verified.

Accepted Response Examples​

{
  "verified": true
}

Rejected / Not Verified Examples​

{
  "verified": false
}
{
  "ok": true
}

Any non-2xx response is also treated as verification failure.

This event does not mean the payout is successful. It only means the system is requesting a verification decision before auto-review approval.

batch.verify.request​

Purpose​

This event is sent before batch payout auto-review approval. It allows the receiver to verify the batch and return a verification decision.

Request Validation​

The receiver should validate the request using the same webhook rules as standard events:

  1. verify X-Beyounger-Signature
  2. use the raw HTTP body for signature verification
  3. process the request idempotently if needed
  4. validate business fields such as:
    • batch_id
    • total_amount
    • currency
    • total_count

Response Contract​

A batch verification response is treated as verified only when:

  1. HTTP status is 2xx
  2. and the response body contains:
  • "verified": true

If this signal is not present, the verification result is treated as not verified.

Accepted Response Examples​

{
  "verified": true
}

Rejected / Not Verified Examples​

{
  "verified": false
}
{
  "ok": true
}

Any non-2xx response is also treated as verification failure.

This event does not mean the batch payout is successful. It only means the system is requesting a verification decision before auto-review approval.