Webhooks

API Documentation · Zypher Global

Generate credentials

We will send a POST to your webhook_url whenever a transaction changes status. Here is EVERYTHING about webhooks, dynamic charge, fixed key/CLABE (open amount), cash-out and disputes (MED), in the enabled currencies.

Common fields

  • type — cashin | cashout.
  • status — confirmed · completed · med · failed.
  • currency — transaction currency (BRL · MXN · USDT).
  • transaction_id, e2e — identifiers; reconcile by e2e (unique per payment).
  • external_id — your identifier, when you sent it at creation.
  • origin — present and equal to "static" when the payment landed on a FIXED KEY/CLABE (open amount). Absent = dynamic charge (by amount).
The provider always comes with the platform name. Always handle the result by status, not by the message.

Cash In (confirmed)

BRL · PIX

Cash In · BRL
{ "type":"cashin", "status":"confirmed", "amount":123.45, "fee":1.23, "currency":"BRL", "request_number":"pr_...", "transaction_id":"pr_...", "e2e":"E...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }

MXN · SPEI

Cash In · MXN
{ "type":"cashin", "status":"confirmed", "amount":500.00, "fee":5.00, "currency":"MXN", "request_number":"pr_...", "transaction_id":"pr_...", "e2e":"E...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }

USDT

Cash In · USDT (BRL→USDT)
{ "type":"cashin", "status":"confirmed", "amount":19.23, "fee":0.58, "currency":"USDT", "transaction_id":"CRYPTO-...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }

In BRL→USDT the webhook fires as soon as the PIX confirms, the amount is the ESTIMATED USDT (the real amount is credited at the end of the conversion).

Fixed key / open amount (static)

Payments on a FIXED KEY (the fixed PIX QR in BRL or the fixed CLABE in MXN) arrive with "origin":"static" and your external_id back. Since the same key receives multiple payments, each event is individual, reconcile by e2e.

Cash In · fixed key/CLABE
{ "type":"cashin", "origin":"static", "status":"confirmed", "amount":100.00, "currency":"MXN", "external_id":"PEDIDO-123", "transaction_id":"PEDIDO-123", "e2e":"E...", "provider":"Zypher Global" }

Same format for BRL (fixed PIX QR) and MXN (fixed CLABE), only the currency changes.

Cash Out (completed)

Cash Out · BRL
{ "type":"cashout", "status":"completed", "amount":250.00, "fee":2.50, "currency":"BRL", "transaction_id":"pr_...", "external_id":"SEU-ID-123", "e2e":"E...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }
Cash Out · MXN
{ "type":"cashout", "status":"completed", "amount":300.00, "fee":3.00, "currency":"MXN", "transaction_id":"pr_...", "e2e":"E...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }
Cash Out · USDT (USDT→BRL)
{ "type":"cashout", "status":"completed", "usdt":20.00, "brl":100.00, "fee":0.50, "currency":"USDT", "transaction_id":"pr_...", "e2e":"E...", "provider":"Zypher Global", "updated_at":"2025-11-24 12:00:00" }

Cash Out (failed / canceled)

If an already-accepted withdrawal (returned as pending) is NOT completed, declined by the recipient bank, invalid key, expired QR, or no liquidity in time, we send a POST with "status":"failed" and the fail_reason. The amount (amount + fee) is automatically refunded to your balance; use the webhook to re-credit or reprocess your end user.

Cash Out · falha
{ "type":"cashout", "status":"failed", "amount":250.00, "fee":2.50, "transaction_id":"pr_...", "external_id":"SEU-ID-123", "e2e":"E...", "fail_reason":"Invalid PIX key.", "updated_at":"2025-11-24 12:00:00" }
The external_id (the same one you sent in the cash-out) comes in ALL withdrawal callbacks, completed and failed, to match the transaction on your side. The synchronous rejection (invalid data at POST time) already returns in the HTTP of the call itself; this failed webhook covers the asynchronous failure (after pending).

MED / Dispute (BRL)

MED (PIX dispute): when an already-confirmed inflow is contested by the payer, we send a POST with "status":"med" on the SAME transaction_id as the original charge. Use it to lock or reverse the order on your side, the net amount is debited/held again in your balance.

MED · BRL
{
  "type": "cashin",
  "status": "med",
  "amount": 123.45,
  "fee": 1.23,
  "currency": "BRL",
  "request_number": "pr_...",
  "transaction_id": "pr_...",
  "e2e": "E...",
  "provider": "Zypher Global",
  "updated_at": "2025-11-24 12:00:00",
  "med": {
    "payer_name": "João da Silva",
    "payer_document": "***.456.789-**",
    "payer_institution": "ISPB 12345678",
    "infraction_type": "FRAUD",
    "infraction_status": "OPEN",
    "infraction_reason": "Pagador alega não reconhecer a transação",
    "reference_id": "PROTOCOL-123",
    "reported_by": "PAGADOR"
  }
}

The med object carries the infraction details (when the acquirer provides them); fields may come empty/absent, treat them as optional.

Idempotency: always reconcile by e2e (unique per payment), the same fixed key/CLABE resends the same external_id on different payments. If the webhook fails, query the real state in Query Transactions.
PreviousQuery Transactions Next Error handling
Was this page helpful?