Webhooks

Transcaty Webhooks

Transcaty sends webhook notifications to the merchant server for PAYIN/PAYOUT state changes.

1) Configure Webhook URL

  • Method: PATCH
  • Endpoint: /v1/me/webhook

Request Body

FieldTypeRequiredDescription
webhookUrlstring | nullYesMerchant callback URL, or null to remove
{
  "webhookUrl": "https://merchant.com/webhooks/transcaty"
}

Use null to disable:

{
  "webhookUrl": null
}

Response Notes

  • Response includes webhookSecret
  • Merchant must store this securely
  • This secret is used to verify webhook signatures

2) Events Sent by Transcaty

Current event types:

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

3) Webhook Headers

Each webhook request includes:

  • X-Transcaty-Webhook-Signature
  • X-Transcaty-Event

X-Transcaty-Webhook-Signature is an HMAC-SHA256 signature.

4) Webhook Payload Example

{
  "event": "payin.completed",
  "transactionId": "uuid",
  "status": "success",
  "amount": "500",
  "paidAmount": "500",
  "platformOrderId": "2026031807000000129",
  "timestamp": "2026-03-19T10:00:00.000Z"
}

For failed events, paidAmount may be absent.

5) Signature Verification (Merchant Side)

Use webhookSecret to verify the payload before processing:

  1. Read raw request body exactly as received
  2. Compute HMAC-SHA256(rawBody, webhookSecret)
  3. Compare with X-Transcaty-Webhook-Signature
  4. Reject if signature mismatches

6) Best Practices

  • Process webhooks idempotently using transactionId
  • Treat webhook as source of async state updates
  • If webhook is delayed, poll:
    • GET /v1/payins/:id
    • GET /v1/payouts/:id
Supported MethodsOverview