Webhooks

Transacty sends webhook notifications to your server for pay-in and payout state changes.

Configure your webhook URL

Request fields

{ "webhookUrl": "https://merchant.example.com/webhooks/transacty" }

{
  "webhookUrl": null
}

curl -X PATCH https://api.transacty.ai/v1/me/webhook \
  -H "X-Transacty-Key: $TRANSACTY_KEY" \
  -H "X-Transacty-Timestamp: $TS" \
  -H "X-Transacty-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
  "webhookUrl": "https://merchant.example.com/webhooks/transacty"
}'

Events sent by Transacty

• payin.completed
• payin.failed
• payout.completed
• payout.failed

The same webhook URL serves all rails (Bangladesh, Brazil, India, Europe, Nigeria, PYUSD).

For PYUSD completed: currency is PYUSD-USDC, not USDC. paidAmount is the net credited to that pocket.

For Nigeria completed: currency is NGN.

Webhook headers

Each webhook request includes:

• X-Transacty-Webhook-Signature — HMAC-SHA256 of the raw body with webhookSecret
• X-Transacty-Event — the event type

Webhook payload example

{
  "event": "payin.completed",
  "transactionId": "uuid",
  "status": "success",
  "amount": "25.00",
  "paidAmount": "24.50",
  "currency": "PYUSD-USDC",
  "platformOrderId": "…",
  "timestamp": "2026-08-31T10:00:00.000Z"
}

For failed events, paidAmount may be absent.

Nigeria VA credits use the same event names with "currency": "NGN":

{
  "event": "payin.completed",
  "transactionId": "uuid",
  "status": "success",
  "amount": "5000.00",
  "paidAmount": "5000.00",
  "currency": "NGN",
  "platformOrderId": "…",
  "timestamp": "2026-08-31T10:00:00.000Z"
}

Signature verification

Use webhookSecret to verify the payload before processing:

Best practices

• Process webhooks idempotently using transactionId.
• Treat the webhook as the source of asynchronous state updates.
• If a webhook is delayed, poll the rail’s status endpoint (GET /v1/payins/:id, GET /v1/payouts/:id, GET /v1/ngn/payouts/:transactionId, or the region-specific status path).