Webhooks

Receive real-time notifications when events occur.

Overview

Configure webhook endpoints to receive real-time POST notifications when events occur in your account.

Registering KYC webhooks

  1. Open API Keys → Webhooks and click Configurar Webhook.
  2. Enter your public HTTPS endpoint and select KYC_APPROVED, KYC_REJECTED, KYC_EXPIRED, or KYC_FAILED.
  3. Submit. If registration fails, the webhook is not saved; try again in a few minutes.

Events

EventDescription
DEPOSIT_PIX_CONFIRMEDThe PIX paying a deposit settled; the asset delivery has not finished yet.
DEPOSIT_ASSET_SUCCESSA deposit was completed successfully.
DEPOSIT_ASSET_FAILEDA paid deposit could not deliver the requested asset.
DEPOSIT_ASSET_REFUNDEDA partial or full PIX refund to the deposit's payer was confirmed.
DEPOSIT_ONCHAIN_RECEIVEDCrypto arrived on-chain in a wallet of your account or a sub-account.
DEPOSIT_ON_HOLDA paid deposit is retained for compliance review instead of delivered.
PAYOUT_SUCCESSFULA PIX payout was sent successfully.
PAYOUT_FAILEDA PIX payout failed.
PAYOUT_REFUNDEDA settled payout was reversed and refunded.
PAYOUT_ON_HOLDA payout was retained by a compliance review and not sent.
WALLET_TRANSFER_COMPLETEDA POST /api/wallet/transfer send was confirmed on-chain.
WALLET_TRANSFER_FAILEDA POST /api/wallet/transfer send accepted as pending never landed.
KYC_APPROVEDKYC for an end-user was approved.
KYC_REJECTEDKYC for an end-user was rejected.
KYC_EXPIREDKYC attempt expired without submission.
KYC_FAILEDKYC attempt failed during processing.
DISPUTE_CREATEDA PIX you received was contested (MED opened).
DISPUTE_ACCEPTEDThe contestation was accepted — the amount is returned to the payer.
DISPUTE_REJECTEDThe contestation was rejected — the amount stays with you.
DISPUTE_CANCELEDThe contestation was withdrawn before a decision.
CARD_KYC_APPROVEDA card holder's identity check was approved (once per holder).
CARD_KYC_REJECTEDA card holder's identity check was rejected; terminal (once per holder).
CARD_ISSUEDA card holder's first card was issued (once per holder).

Payload

Every webhook delivery sends a JSON body with the following structure:

{
  "event": "PAYOUT_SUCCESSFUL",
  "data": { ... }
}

Headers

Each request includes these headers for verification:

HeaderDescription
X-Hodle-SignatureHMAC-SHA256 signature of the payload, hex-encoded.
X-Hodle-TimestampUnix timestamp (seconds) when the request was sent.
X-Hodle-Delivery-Attempt1 on the first delivery, then the number of the attempt on each retry.

Plus any custom headers you configured on the webhook.

Webhook Secret

Each webhook listens to one event and has its own 64-character hex signing secret. To receive multiple events at the same URL, create a webhook for each and verify deliveries with the matching secret.

Copy the secret after creation in API Keys → Webhooks, or reveal it later using the eye icon in the Secret column. Store it in your backend secret manager.

Custom headers are sent on every delivery; blank values are omitted.

Verifying Signatures

Verify X-Hodle-Signature before processing a delivery:

signature = hex( HMAC_SHA256( secret, "<X-Hodle-Timestamp>.<raw request body>" ) )

Use the raw request bytes before JSON parsing, compare signatures with a constant-time function, and reject timestamps more than 5 minutes from the current time.

Node.js / TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_IN_SECONDS = 300

type VerifyHodleWebhookArgs = {
  rawBody: string
  signature: string
  timestamp: string
  secret: string
}

const verifyHodleWebhook = (args: VerifyHodleWebhookArgs): boolean => {
  const { rawBody, signature, timestamp, secret } = args

  const timestampAge = Math.abs(
    Math.floor(Date.now() / 1000) - Number(timestamp),
  )

  if (!Number.isFinite(timestampAge) || timestampAge > TOLERANCE_IN_SECONDS) {
    return false
  }

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest()

  const received = Buffer.from(signature, 'hex')

  if (received.length !== expected.length) {
    return false
  }

  return timingSafeEqual(expected, received)
}
Express endpoint (raw body)
import express from 'express'

const app = express()

app.post(
  '/hodle/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const isValid = verifyHodleWebhook({
      rawBody: req.body.toString('utf8'),
      signature: req.header('X-Hodle-Signature') ?? '',
      timestamp: req.header('X-Hodle-Timestamp') ?? '',
      secret: process.env.HODLE_WEBHOOK_SECRET ?? '',
    })

    if (!isValid) {
      return res.status(401).send('invalid signature')
    }

    const payload = JSON.parse(req.body.toString('utf8'))

    // handle payload.event / payload.data

    return res.status(200).send('ok')
  },
)
PHP
<?php

function verifyHodleWebhook(
    string $rawBody,
    string $signature,
    string $timestamp,
    string $secret,
): bool {
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HODLE_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_HODLE_TIMESTAMP'] ?? '';

if (!verifyHodleWebhook($rawBody, $signature, $timestamp, getenv('HODLE_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}

The registration test delivery

Registration sends a signed WEBHOOK_TEST before you can copy the secret. Respond 2xx without changing any order state. The webhook is saved only if the test succeeds. Configure its secret afterward and verify every real event before accepting it.

Retry Policy

Respond 2xx within 10 seconds to acknowledge delivery. Other statuses, network errors and timeouts trigger up to three retries:

AttemptX-Hodle-Delivery-AttemptWhen
First delivery1As soon as the event happens.
Retry 1210 seconds after attempt 1 failed.
Retry 2360 seconds after attempt 2 failed.
Retry 345 minutes after attempt 3 failed. Last attempt.

Each retry has the same payload and a fresh signature timestamp. Payout, KYC, dispute and on-chain deposit webhooks retry independently; deleting a webhook cancels its pending retries.

After retries are exhausted, read the current state from GET /api/deposit/{id} or GET /api/wallet/payout/{transactionId}.

Deposit status events

The five deposit events follow the retry schedule above. Deduplicate by data.eventId and acknowledge duplicates with 2xx. Endpoints that already accepted an event are skipped on its retries.

Events are attempted in order: DEPOSIT_PIX_CONFIRMED, then DEPOSIT_ON_HOLD when the deposit is retained, then DEPOSIT_ASSET_SUCCESS or DEPOSIT_ASSET_FAILED, then refunds. A failed event delays later events for that deposit until it succeeds or exhausts its retries. Other deposits continue independently. Handle missing or older events without moving an order backwards.

PAYOUT_SUCCESSFUL

Sent when a PIX payout completes, whether funded by Lightning or Wallet Payout. Match externalId to your order; the payload fields are listed below.

PAYOUT_SUCCESSFUL — stablecoin (wallet/payout)
{
  "event": "PAYOUT_SUCCESSFUL",
  "data": {
    "success": true,
    "transactionId": "65f1a8b2c3d4e5f6a7b8c9d0",
    "externalId": "offramp:823e6356",
    "trackId": "e38afb8e-7472-4100-9c69-dd619dda9b96",
    "status": "COMPLETED",
    "asset": "USDC",
    "network": "solana",
    "valueInBrl": "50.00",
    "fee": "2.75",
    "pixKey": "recipient@example.com",
    "endToEndId": "E12345678202604281432abcdef123456",
    "txHash": "2mZcnSeMEbYA8Rz6YNse6zkB7gsUcZsnvo5AhtgcF9DqHbGho3k9S16Y4Szd",
    "receipt": {
      "endToEndId": "E12345678202604281432abcdef123456",
      "paidAt": "2026-04-28T14:32:11.708Z",
      "amountInBrl": "50.00",
      "payerIspb": "12345678",
      "receiver": {
        "name": "MARIA SOUZA",
        "taxId": "***.241.413-**",
        "pixKey": "recipient@example.com",
        "bankName": "Example Bank",
        "ispb": "54811417",
        "branch": "0001",
        "account": "****5716",
        "accountType": "TRAN"
      }
    },
    "receiptUrl": "https://receipts.hodle.com.br/receipts/65f1a8b2c3d4e5f6a7b8c9d0.pdf",
    "quote": {
      "brlAmount": "50.00",
      "assetAmount": "9.65281000",
      "fxRateAtTx": 5.17981
    },
    "invoice": "2mZcnSeMEbYA8Rz6YNse6zkB7gsUcZsnvo5AhtgcF9DqHbGho3k9S16Y4Szd"
  }
}
PAYOUT_SUCCESSFUL — Lightning-funded
{
  "event": "PAYOUT_SUCCESSFUL",
  "data": {
    "success": true,
    "transactionId": "65f1a8b2c3d4e5f6a7b8c9d1",
    "externalId": null,
    "trackId": "3dbbb785-8a1d-41c4-9d15-171e0ddc7c3d",
    "status": "COMPLETED",
    "asset": "LIGHTNING",
    "network": "lightning",
    "valueInBrl": "1000.00",
    "fee": "170.00",
    "pixKey": "13d3109f-3a1e-4c56-b76d-d2db7213b9f2",
    "endToEndId": "E12345678202604281432abcdef123457",
    "txHash": "lnbc32310n1p5u2g2qsp5xq6j2rhspx7es5c0dymwrn2wcam6ay2vpgft65njm9pe6te93fgqpp5...",
    "receipt": null,
    "receiptUrl": null,
    "valueInSatoshis": 276190,
    "quote": {
      "brlAmount": "1000.00",
      "assetAmount": "0.00276190",
      "fxRateAtTx": 362069.04418686405,
      "btcAmount": 0.0027619041618037344,
      "satoshis": 276190,
      "btcToBrlRate": 362069.04418686405
    },
    "invoice": "lnbc32310n1p5u2g2qsp5xq6j2rhspx7es5c0dymwrn2wcam6ay2vpgft65njm9pe6te93fgqpp5..."
  }
}

Fields

FieldTypeDescription
successbooleanAlways true on this event.
transactionIdstringOur id for the payout — the same one POST /api/wallet/payout returned.
externalIdstring | nullThe idempotency key you created the payout with. null when the payout was not created through the API.
trackIdstring | nullInternal tracking id of the payout.
statusstringAlways COMPLETED on this event.
assetstring | nullAsset debited to fund the payout (USDT, USDC, BRLA, BRS, LIGHTNING).
networkstring | nullNetwork the asset was debited on.
valueInBrlstringValue paid out, in BRL. Source of truth for the amount.
feestringFee charged, in BRL.
pixKeystring | nullThe PIX key where BRL was sent.
endToEndIdstring | nullBacen end-to-end id of the settled PIX. null if none was reported.
txHashstring | nullOn-chain transaction id of the debit, or the bolt11 invoice on a Lightning-funded payout.
receiptobject | nullReceipt detail of the settled PIX — see Receipt detail. null when none was reported.
receiptUrlstring | nullPDF comprovante, when one was rendered.
quote.brlAmountstringBRL amount quoted.
quote.assetAmountstring | nullAmount in asset the BRL value converts to at fxRateAtTx.
quote.fxRateAtTxnumber | nullBRL per unit of asset at the time of the payout.
quote.btcAmountnumberBitcoin-priced payouts only. BTC amount.
quote.satoshisnumberBitcoin-priced payouts only. Amount in satoshis.
quote.btcToBrlRatenumberBitcoin-priced payouts only. BTC to BRL rate at the time.
valueInSatoshisnumberBitcoin-priced payouts only. Amount in satoshis. Absent on stablecoin payouts — use valueInBrl.
invoicestring | nullLegacy alias of txHash.

Receipt detail

Use receipt to render a PIX receipt. Missing details are null; optional fields may be absent. Bank identifiers are strings and preserve leading zeros.

FieldTypeDescription
endToEndIdstringBacen end-to-end id, the identifier the payee's bank shows for this PIX.
paidAtstringISO-8601 settlement time reported by the settling institution.
amountInBrlstringAmount that left, in BRL.
payerIspbstringISPB of the institution that debited the funds, read from the end-to-end id.
brCodestringOptional. Original PIX BR Code (copia e cola) for a QR payout, when available.
receiver.namestringPayee name as resolved by the receiving bank.
receiver.taxIdstringPayee tax id. A CPF is masked (***.241.413-**); a CNPJ is public registry data and comes whole.
receiver.pixKeystringPIX key the transfer was addressed to.
receiver.pixKeyTypestringOptional. PIX key type, such as EMAIL or CPF, when available.
receiver.bankNamestringPayee bank name when reported; otherwise null.
receiver.bankCodestringOptional. Bank code when reported, such as 001; distinct from the ISPB.
receiver.ispbstringISPB of the payee's institution — resolve the name with Bacen's participant list.
receiver.branchstringPayee branch (agência).
receiver.accountstringPayee account, masked to the last four digits.
receiver.accountTypestringAccount type as reported (e.g. TRAN).

GET /api/wallet/payout/:transactionId returns the latest receipt, plus creditParty, receiptUrl and receiptComplete. Later receipt updates do not emit another success event.

Compare end-to-end ids case-insensitively.

PAYOUT_FAILED

Sent when a PIX payout fails. For a stablecoin-funded /api/wallet/payout, the debited on-chain funds are auto-refunded to the user's wallet when automatic refund is enabled on the account (ask support). As with the success event, invoice carries the on-chain transaction id for stablecoin payouts.

PAYOUT_FAILED — stablecoin (wallet/payout)
{
  "event": "PAYOUT_FAILED",
  "data": {
    "success": false,
    "invoice": "0xeafe9c...",
    "pixKey": "user@email.com",
    "valueInBrl": "10.00",
    "errorCode": "PAYOUT_FAILED",
    "errorDescription": "Não foi possível processar o pagamento no momento. Tente novamente mais tarde."
  }
}

errorCode and errorDescription are stable values suitable for customer-facing messages.

PAYOUT_ON_HOLD

Sent when a compliance review retains a payout instead of sending it. It is sent at most once per payout: a retry of the same payout, or a later review of it, sends nothing new.

A payout can be retained before it is created, when the request itself is refused (transactionId is null and the request answered 403), or after it was created, while it was being settled. In the second case the payout continues with the usual events: PAYOUT_FAILED (with its refund, when automatic refund is enabled) or PAYOUT_SUCCESSFUL. Payout events are not ordered, so read GET /api/wallet/payout/{transactionId} for the current state.

PAYOUT_ON_HOLD
{
  "event": "PAYOUT_ON_HOLD",
  "data": {
    "success": false,
    "status": "ON_HOLD",
    "reason": "COMPLIANCE_REVIEW",
    "eventId": "payout-on-hold-66f0c1e2a4b5c6d7e8f90123",
    "transactionId": "66f0c1e2a4b5c6d7e8f90123",
    "externalId": "offramp:my-order-123",
    "subAccountId": null,
    "valueInBrl": "500.00",
    "pixKey": "user@email.com",
    "occurredAt": "2026-11-10T18:00:00.000Z"
  }
}

Fields

FieldTypeDescription
successbooleanAlways false: the payout was not sent.
statusstringAlways ON_HOLD.
reasonstringAlways COMPLIANCE_REVIEW. The review criteria are not disclosed.
eventIdstringStable id of this notification, one per payout. Use it to deduplicate retries.
transactionIdstring | nullOur id for the payout. null when the payout was retained before it was created.
externalIdstring | nullThe idempotency key you sent with the payout, if any.
subAccountIdstring | nullThe sub-account the payout was attributed to, if any.
valueInBrlstringValue of the payout, in BRL.
pixKeystring | nullThe PIX key the payout targeted. null for a BR Code payout.
occurredAtstringISO-8601 time of the hold, not the HTTP delivery time.

Do not resend a retained payout under a new externalId: it is reviewed the same way. To ask about a hold, contact support with the eventId.

Subscribe in API Keys → Webhooks (Payout retido para análise).

PAYOUT_REFUNDED

Sent after a PIX reversal or a refund issued by Hodle's team. The payload varies by refund type; only success, pixKey and valueInBrl are always present.

Reversed PIX (MED)

The recipient's bank returned the PIX. An on-chain refund requires automatic refund to be enabled on your account (ask support).

PAYOUT_REFUNDED — reversed PIX
{
  "event": "PAYOUT_REFUNDED",
  "data": {
    "success": true,
    "transactionId": "6650b21c9f4d3a0012ab34cd",
    "endToEndId": "E1234567820260731113000abcdef123",
    "pixKey": "recipient@example.com",
    "valueInBrl": "50.00",
    "returnedAmount": "50.00",
    "originalTicketId": "7f3c1b2a-9d84-4c1e-8f20-1a2b3c4d5e6f",
    "reversalTicketId": "b1e4d9c7-2a55-4f83-91cd-77e0a1b2c3d4",
    "reason": "Payout reversed. Original ticket id: 7f3c1b2a-9d84-4c1e-8f20-1a2b3c4d5e6f",
    "refundTxId": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
    "refundAddress": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  }
}
FieldTypeDescription
successbooleanAlways true — the event reports a completed reversal, not a failure.
transactionIdstringId of the original payout transaction.
endToEndIdstring | nullPIX end-to-end id of the original payout, when we have it.
pixKeystringPIX key the original payout was sent to.
valueInBrlstringValue of the original payout in BRL.
returnedAmountstringAmount actually returned by the reversal (BRLA). May be empty if the provider omits it, and may be less than valueInBrl on a partial return.
originalTicketIdstringProvider ticket id of the original payout.
reversalTicketIdstringProvider ticket id of the reversal itself. Use it to deduplicate.
reasonstringFree-text reason from the provider describing the reversal.
refundTxIdstring | nullOn-chain tx hash of the refund we sent the user. null when no refund was sent.
refundAddressstring | nullAddress that received the refund. null when no refund was sent.

If refundTxId is null, the reversal is confirmed but the on-chain refund needs manual review. Wait for Hodle's follow-up before crediting the user.

Manual stablecoin refund

Hodle's team refunded the payout on-chain.

PAYOUT_REFUNDED — manual stablecoin refund
{
  "event": "PAYOUT_REFUNDED",
  "data": {
    "success": true,
    "transactionId": "6650b21c9f4d3a0012ab34cd",
    "refundTxId": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
    "refundAddress": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
    "asset": "USDT",
    "network": "polygon",
    "stableAmount": "9.85",
    "pixKey": "user@email.com",
    "valueInBrl": "50.00",
    "refundedAt": "2026-07-31T11:30:00.000Z"
  }
}
FieldTypeDescription
transactionIdstringId of the original payout transaction.
refundTxIdstringOn-chain tx hash of the refund.
refundAddressstringAddress that received the refund.
assetstringRefunded asset (USDT, USDC, USDCE, BRLA).
networkstringNetwork of the refund (polygon or base).
stableAmountstringAmount refunded in the stablecoin's own unit.
pixKeystringPIX key of the original payout.
valueInBrlstringValue of the original payout in BRL.
refundedAtstringISO-8601 timestamp of the refund.

Manual Lightning refund

The original payout was funded by a Lightning invoice, and the refund was paid back over Lightning.

PAYOUT_REFUNDED — manual Lightning refund
{
  "event": "PAYOUT_REFUNDED",
  "data": {
    "success": true,
    "invoice": "lnbc32310n1p5u2g2qsp5xq6j2rhspx7es5c0dymwrn2wcam6ay2vpgft65njm9pe6te93fgqpp5...",
    "refundAddress": "user@walletofsatoshi.com",
    "refundInvoice": "lnbc27619n1p5abcd2qsp5...",
    "refundTxId": "5f8a1c2d3e4b5a6c7d8e9f0a1b2c3d4e",
    "valueInSatoshis": 276190,
    "pixKey": "13d3109f-3a1e-4c56-b76d-d2db7213b9f2",
    "valueInBrl": "1000.00",
    "refundedAt": "2026-07-31T11:30:00.000Z"
  }
}
FieldTypeDescription
invoicestringThe original bolt11 invoice that funded the payout.
refundAddressstring | nullLightning address the refund was sent to, when one was registered.
refundInvoicestringThe bolt11 invoice we paid to refund the user.
refundTxIdstringLightning payment id of the refund.
valueInSatoshisnumberAmount refunded, in satoshis.
pixKeystringPIX key of the original payout.
valueInBrlstringValue of the original payout in BRL.
refundedAtstringISO-8601 timestamp of the refund.

Handling the event

Branching on the refund shape
type PayoutRefundedData = {
  transactionId?: string
  reversalTicketId?: string
  refundTxId?: string | null
  refundInvoice?: string
  valueInBrl: string
  pixKey: string
}

const handlePayoutRefunded = (data: PayoutRefundedData) => {
  if (data.reversalTicketId) {
    return reverseOrder({
      orderRef: data.transactionId,
      dedupeKey: data.reversalTicketId,
      refundPending: !data.refundTxId,
    })
  }

  return reverseOrder({
    orderRef: data.transactionId,
    dedupeKey: data.refundTxId ?? data.refundInvoice,
    refundPending: false,
  })
}
  • Deduplicate reversals by reversalTicketId and manual refunds by refundTxId.
  • Match transactionId (or originalTicketId on reversals) to the original payout.
  • Size a reversal using returnedAmount, which may be a partial return.

Identifying the sub-account

KYC events for a subaccount created through POST /api/kyc or POST /api/kyb include:

FieldTypeDescription
subAccountIdstring | nullThe sub-account the KYC belongs to.
userIdstring | nullThe Hodle user id of the sub-account.

Both are null for KYC on your own account, where the event refers to the platform account itself.

Wallet transfer events

Sent once per transfer made through POST /api/wallet/transfer, from your account's wallet or a sub-account's wallet, to any destination (an external address, another sub-account or a linked user), when the transfer reaches a final on-chain state:

EventWhen
WALLET_TRANSFER_COMPLETEDThe transfer is confirmed on-chain. For a 200 response, right after the request; for a 202 (PENDING), as soon as the confirmation is seen.
WALLET_TRANSFER_FAILEDA transfer answered 202 (PENDING) never landed: it expired, failed or reverted on-chain. No funds left the wallet; send again with a new reference.

A request refused with 4xx or 5xx sends no event: nothing was submitted and the response already says why. Subscribe to each event separately in API Keys → Webhooks (Envio da carteira confirmado, Envio da carteira falhou). The event goes to the webhooks of the account that owns the API key; a transfer from a sub-account carries its subAccountId.

WALLET_TRANSFER_COMPLETED
{
  "event": "WALLET_TRANSFER_COMPLETED",
  "data": {
    "eventId": "wallet-transfer-66f0c1e2a4b5c6d7e8f90123",
    "transactionId": "66f0c1e2a4b5c6d7e8f90123",
    "reference": "transfer-123",
    "externalId": "transfer-123",
    "status": "COMPLETED",
    "accountId": "66a1b2c3d4e5f60718293a4b",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "network": "polygon",
    "asset": "USDT",
    "amount": "125.5",
    "fromAddress": "0x4B1f2E3d4C5b6A7980716253443526170819c9a2",
    "toAddress": "0x8a3D9c1B2e4F5a6B7c8D9e0F1a2B3c4D5e6F71Fe",
    "txHash": "0x5c3b8a1e0d7f4c2b9a6e3d1f0c8b7a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a",
    "createdAt": "2026-11-10T14:03:02.000Z",
    "completedAt": "2026-11-10T14:03:11.000Z"
  }
}

Fields

FieldTypeDescription
eventIdstringStable id of this notification, one per transfer and the same on every retry. Use it to deduplicate.
transactionIdstringThe data.transactionId the transfer request returned.
referencestring | nullThe reference you sent with the transfer, if any.
externalIdstring | nullSame value as reference, under the name the other webhooks use.
statusstringCOMPLETED or FAILED, matching the event.
accountIdstringYour account (the owner of the API key).
subAccountIdstring | nullThe fromSubAccountId of the request. null for a transfer from your own account's wallet.
networkstringpolygon, base, bnb or solana.
assetstringThe asset sent, as the transfer response reports it.
amountstringThe amount you requested, as a decimal string in units of asset.
fromAddressstring | nullThe sending wallet address.
toAddressstringThe destination address, as the transfer response reports it in recipientAddress.
txHashstring | nullTransaction hash (on Solana, the signature). Can be null on WALLET_TRANSFER_FAILED when nothing was mined.
createdAtstringISO-8601 time the transfer was accepted.
completedAtstringISO-8601 time Hodle saw the final state, not the HTTP delivery time.

Deliveries follow the retry policy, each endpoint independently: an endpoint that already answered 2xx is not sent the event again. Deliveries are at least once: deduplicate by eventId and acknowledge duplicates with 2xx. A transfer still pending 7 days after it was accepted is no longer watched; contact support with its transactionId.

KYC_APPROVED

Sent when KYC is approved.

KYC_APPROVED
{
  "event": "KYC_APPROVED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "level": "level-1",
    "approvedAt": "2026-05-08T22:31:11.000Z"
  }
}

When the subaccount was linked to an identity Hodle already verified, KYC_APPROVED is sent right after POST /api/kyc, with the same fields plus linked: true. The attemptId is the one that call returned:

KYC_APPROVED — linked to an existing verification
{
  "event": "KYC_APPROVED",
  "data": {
    "attemptId": "link_3f9c1e2a-...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "level": "level-1",
    "approvedAt": "2026-09-30T12:00:00.000Z",
    "linked": true
  }
}

When the second verification is enabled for your account, subaccount KYC events also carry provider, naming which verification decided: PRIMARY for the primary verification. Accounts without it never receive the field. With second-verification webhooks also enabled, a second KYC_APPROVED (or KYC_REJECTED) arrives later for the same attemptId with provider: "SECONDARY":

KYC_APPROVED — second verification
{
  "event": "KYC_APPROVED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "provider": "SECONDARY",
    "kycUserId": "b8e2d3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "APPROVED",
    "approvedAt": "2026-05-08T22:40:02.000Z"
  }
}

Branch on provider before acting on a KYC event when it is present: the PRIMARY approval is what unlocks transactions, and a SECONDARY rejection does not revoke it.

Primary approval unlocks deposits and payouts, subject to account enablement.

KYC_REJECTED

Sent when KYC is rejected.

KYC_REJECTED
{
  "event": "KYC_REJECTED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "reason": "DOCUMENT_MISMATCH"
  }
}

reason is a human-readable sentence you can show the customer. When it is present, reasonCode is the stable code to branch on. reasonCode: "PROVIDER_REJECTED" is a final rejection by the compliance screening (e.g. reason: "criminal lawsuits detected"): a new attempt for that subaccount is refused, so do not offer a retry.

From the second verification (provider: "SECONDARY"), reason is an object { code, retryable, retryFrom } and status is REJECTED or REJECTED_RETRYABLE:

KYC_REJECTED — second verification
{
  "event": "KYC_REJECTED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "provider": "SECONDARY",
    "kycUserId": "b8e2d3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "REJECTED_RETRYABLE",
    "reason": {
      "code": "DOCUMENT_UNREADABLE",
      "retryable": true,
      "retryFrom": "documents"
    }
  }
}

KYC_EXPIRED

Sent when a hosted KYC attempt times out before submission.

KYC_EXPIRED
{
  "event": "KYC_EXPIRED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "expiredAt": "2026-05-08T22:31:11.000Z"
  }
}

KYC_FAILED

Sent when KYC processing fails.

KYC_FAILED
{
  "event": "KYC_FAILED",
  "data": {
    "attemptId": "att_a1b2c3...",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "error": "Internal provider error"
  }
}

For second verification, error is a stable code. If retryable is true and retryFrom is documents, upload a new identity document and SELFIE-FROM-LIVENESS, then call POST /api/kyc again. Previous document ids cannot be reused.

KYC_FAILED — retryable
{
  "event": "KYC_FAILED",
  "data": {
    "attemptId": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "userId": "6a70b6364c38f215e99b8c8b",
    "error": "LIVENESS_BELOW_THRESHOLD",
    "retryable": true,
    "retryFrom": "documents"
  }
}
errorretryableWhat to do
LIVENESS_BELOW_THRESHOLDtrueThe selfie did not score high enough. Record a new liveness selfie (good light on the face, no glasses or hat) and resubmit.

DEPOSIT_ASSET_SUCCESS

Confirms asset delivery to the requested address. See the deposit event policy.

DEPOSIT_ASSET_SUCCESS
{
  "event": "DEPOSIT_ASSET_SUCCESS",
  "data": {
    "eventId": "deposit-completed-66f0c1e2a4b5c6d7e8f90123",
    "occurredAt": "2026-09-22T23:52:40.000Z",
    "success": true,
    "externalId": "my-order-123",
    "walletCharge": "66f0c1e2a4b5c6d7e8f90123",
    "trackId": "trk_abc123",
    "asset": "USDC",
    "network": "solana",
    "value": 5000,
    "valueInBrl": "50.00",
    "valueInCurrency": 9.21,
    "fee": "1.00",
    "fxRateAtTx": 5.32
  }
}

Fields

FieldTypeDescription
eventIdstringStable id of this notification, one per deposit. The same on every retry; use it to deduplicate.
occurredAtstringISO-8601 time the deposit was completed, not the HTTP delivery time.
successbooleanAlways true on this event.
externalIdstringThe external ID sent in the deposit request, or an auto-generated UUID.
walletChargestringHodle id of the deposit, the same one the POST returned.
trackIdstringHodle tracking id of the deposit.
asset, networkstringAsset and network delivered.
valuenumberAmount in BRL cents.
valueInBrlstringSame amount, formatted BRL.
valueInCurrencynumberStablecoin deposits: amount delivered, in units of asset.
feestringStablecoin deposits: fee charged, formatted BRL.
fxRateAtTxnumberStablecoin deposits: BRL per unit of asset at the time of the deposit.

eventId, occurredAt, success, externalId, walletCharge, trackId, asset, network, value and valueInBrl are present on every deposit. The last three rows are sent on stablecoin deposits; other assets may carry extra fields that are not part of the contract, so do not depend on them.

Treat DEPOSIT_ASSET_SUCCESS as authoritative for delivery. The on-chain transaction hash and the amount delivered in the asset's smallest unit are available from GET /api/deposit/{id}.

Who paid the PIX

Accounts with their own virtual account also receive the payer identity:

DEPOSIT_ASSET_SUCCESS (own virtual account)
{
  "event": "DEPOSIT_ASSET_SUCCESS",
  "data": {
    "success": true,
    "asset": "USDT",
    "network": "polygon",
    "externalId": "my-order-123",
    "valueInBrl": "50.00",
    "valueInCurrency": 8.82,
    "fee": "1.00",
    "fxRateAtTx": 5.55,
    "trackId": "trk_abc123",
    "payer": {
      "name": "FULANO DE TAL",
      "taxId": "12345678901"
    },
    "endToEndId": "E1823612020260830120000000000001",
    "paidAt": "2026-08-30T12:00:00.000Z"
  }
}
FieldTypeDescription
payer.namestring | nullName of whoever paid the PIX, as the bank reports it.
payer.taxIdstring | nullCPF/CNPJ of the payer, digits only.
endToEndIdstring | nullEnd-to-end id of the PIX that funded the deposit.
paidAtstring | nullISO-8601 timestamp of when the PIX settled.

These fields require your own virtual account (ask support). They are also available from GET /api/deposit/{id}.

DEPOSIT_PIX_CONFIRMED

Confirms the PIX payment before asset delivery. Use it to release your customer's order without waiting for the asset to arrive.

DEPOSIT_PIX_CONFIRMED
{
  "event": "DEPOSIT_PIX_CONFIRMED",
  "data": {
    "status": "FIAT_PAID",
    "endToEndId": "E18236120202609222351s0000000001",
    "paidAt": "2026-09-22T23:51:43.000Z",
    "eventId": "deposit-pix-confirmed-66f0c1e2a4b5c6d7e8f90123",
    "occurredAt": "2026-09-22T23:51:43.000Z",
    "externalId": "my-order-123",
    "walletCharge": "66f0c1e2a4b5c6d7e8f90123",
    "trackId": "trk_abc123",
    "asset": "USDC",
    "network": "solana",
    "value": 5000,
    "valueInBrl": "50.00"
  }
}
FieldTypeDescription
statusstringAlways FIAT_PAID: the PIX settled, the asset is not delivered yet.
endToEndIdstring | nullEnd-to-end id of the PIX that paid the deposit.
paidAtstringISO-8601 settlement time, or the time Hodle received confirmation if no settlement time was reported.
eventIdstringStable id of this notification, one per deposit. Use it to deduplicate retries.
occurredAtstringSame instant as paidAt, not the HTTP delivery time.
externalId, walletCharge, trackIdstringIds of the deposit, as in the other deposit events.
asset, networkstringAsset and network requested in the deposit.
value, valueInBrlnumber, stringDeposit amount, in BRL cents and formatted BRL.

PIX confirmation does not guarantee asset delivery. Listen for DEPOSIT_ASSET_SUCCESS, DEPOSIT_ASSET_FAILED and DEPOSIT_ASSET_REFUNDED to track the outcome.

Create a subscription in API Keys → Webhooks (Pix do depósito recebido) before the deposit is paid.

DEPOSIT_ONCHAIN_RECEIVED

Sent when crypto arrives on-chain in a Hodle wallet of your account or of one of your sub-accounts. Use it when your customers send stablecoins from an external wallet straight to the address POST /api/wallet/get returned: no Pix and no deposit order is involved, so no other event fires.

NetworkAssets
polygonUSDC, USDT, BRLA
baseUSDC, BRLA
solanaUSDC, USDT, BRS

Subscribe in API Keys → Webhooks (Cripto recebida na carteira). One subscription covers every wallet of your account and of all your sub-accounts. Transfers that landed before the subscription existed are not replayed.

Every inbound transfer is announced, including deliveries Hodle itself makes to the wallet: a POST /api/deposit/asset delivered to the account's own wallet sends DEPOSIT_ASSET_SUCCESS and also this event. If you credit those through the deposit events, deduplicate by txHash. Transfers out of the wallet and zero-value transfers are never announced.

DEPOSIT_ONCHAIN_RECEIVED — Polygon
{
  "event": "DEPOSIT_ONCHAIN_RECEIVED",
  "data": {
    "eventId": "polygon:0x5c3b8a1e0d7f4c2b9a6e3d1f0c8b7a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a:12",
    "network": "polygon",
    "asset": "USDC",
    "amount": "125.5",
    "amountRaw": "125500000",
    "toAddress": "0x4B1f2E3d4C5b6A7980716253443526170819c9a2",
    "fromAddress": "0x8a3D9c1B2e4F5a6B7c8D9e0F1a2B3c4D5e6F71Fe",
    "txHash": "0x5c3b8a1e0d7f4c2b9a6e3d1f0c8b7a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a",
    "logIndex": 12,
    "blockNumber": 64210345,
    "walletId": "66f0c1e2a4b5c6d7e8f90123",
    "subAccountId": "a928c33c-1ad2-4bf9-b4ce-1f83b403f1e4",
    "receivedAt": "2026-11-10T14:03:11.000Z"
  }
}
DEPOSIT_ONCHAIN_RECEIVED — Solana
{
  "event": "DEPOSIT_ONCHAIN_RECEIVED",
  "data": {
    "eventId": "solana:5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v:7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "network": "solana",
    "asset": "USDC",
    "amount": "40",
    "amountRaw": "40000000",
    "toAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
    "fromAddress": "3Kz9pJqvR8rZ4dB2m1tWcFqyH6sL5nXeAoT7uGiVbN2E",
    "txHash": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
    "signature": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
    "slot": 312345678,
    "walletId": "66f0c1e2a4b5c6d7e8f90124",
    "subAccountId": null,
    "receivedAt": "2026-11-10T14:05:40.000Z"
  }
}

Fields

FieldTypeDescription
eventIdstringStable id of this notification, one per transfer and the same on every retry. Treat it as opaque and use it to deduplicate.
networkstringpolygon, base or solana.
assetstringThe token received: see the table above.
amountstringAmount received, as a decimal string in units of asset ("125.5" is 125.5 USDC).
amountRawstringThe same amount in the token's smallest unit, as an integer string.
toAddressstringThe wallet address that received it, as POST /api/wallet/get returns it in addresses.
fromAddressstring | nullEVM: the sending address (0x0000000000000000000000000000000000000000 for a token mint). Solana: the owner of the sending account, null if none.
txHashstringTransaction hash. On Solana, the transaction signature.
logIndexnumberEVM only. Position of the transfer in its block; one transaction can carry several transfers.
blockNumbernumberEVM only. Block that included the transfer.
signaturestringSolana only. The transaction signature, same as txHash.
slotnumberSolana only. Slot that included the transaction.
walletIdstringHodle id of the wallet that received it, the data.id of POST /api/wallet/create.
subAccountIdstring | nullThe sub-account the wallet belongs to. null for a wallet of your own account.
receivedAtstringISO-8601 block time of the transfer, not the HTTP delivery time.

Confirmations and latency

A transfer is announced only after the network can no longer take it back, so you can credit your customer on the event:

NetworkAnnounced afterUsual time from transfer to delivery
polygon64 blocksAbout 2 to 3 minutes
base12 blocksUnder a minute
solanaFinalized commitmentUnder a minute

Accounts with many Solana wallets may see longer Solana delays, since the wallets are checked in turn. Deliveries follow the retry policy. Deliveries are at least once: deduplicate by eventId, acknowledge duplicates with 2xx, and use POST /api/wallet/get with sync: true to reconcile the balance after retries are exhausted.

DEPOSIT_ON_HOLD

Sent when a paid deposit is retained for compliance review instead of delivered. The PIX settled (DEPOSIT_PIX_CONFIRMED comes first), but the asset is not delivered until the review ends. It is sent at most once per deposit.

When the review releases the deposit, it is delivered and DEPOSIT_ASSET_SUCCESS follows. There is no separate release event. A deposit that is not released ends with DEPOSIT_ASSET_FAILED and DEPOSIT_ASSET_REFUNDED.

DEPOSIT_ON_HOLD
{
  "event": "DEPOSIT_ON_HOLD",
  "data": {
    "status": "ON_HOLD",
    "reason": "COMPLIANCE_REVIEW",
    "subAccountId": "sub_123",
    "heldAt": "2026-11-10T18:00:00.000Z",
    "eventId": "deposit-on-hold-66f0c1e2a4b5c6d7e8f90123",
    "occurredAt": "2026-11-10T18:00:00.000Z",
    "externalId": "my-order-123",
    "walletCharge": "66f0c1e2a4b5c6d7e8f90123",
    "trackId": "trk_abc123",
    "asset": "USDC",
    "network": "base",
    "value": 5000,
    "valueInBrl": "50.00"
  }
}
FieldTypeDescription
statusstringAlways ON_HOLD: the PIX settled and the asset is retained.
reasonstringAlways COMPLIANCE_REVIEW. The review criteria are not disclosed.
subAccountIdstring | nullThe sub-account of the deposit, if you sent one.
heldAtstringISO-8601 time the deposit was retained.
eventIdstringStable id of this notification, one per deposit. Use it to deduplicate retries.
occurredAtstringSame instant as heldAt, not the HTTP delivery time.
externalId, walletCharge, trackIdstringIds of the deposit, as in the other deposit events.
asset, networkstringAsset and network requested in the deposit.
value, valueInBrlnumber, stringDeposit amount, in BRL cents and formatted BRL.

Do not ask the payer to pay again while a deposit is on hold. To ask about a hold, contact support with the eventId.

Subscribe in API Keys → Webhooks (Depósito retido para análise).

Deposit failure and refund

Subscribe separately to DEPOSIT_ASSET_FAILED and DEPOSIT_ASSET_REFUNDED in API Keys → Webhooks.

Hodle returns the PIX to the payer after a definitive delivery failure; you do not need to request it. Some refunds require manual review, so there is no fixed deadline. The refund event confirms a settled return, including partial returns.

Failure events cover stablecoin, Lightning and bitcoin deliveries. Use GET /api/deposit/{id} to check failures without an event. Most deliveries take a few minutes; an unconfirmed delivery stays PROCESSING until its outcome is known. Do not submit another purchase while it is pending.

Both events include these fields in data, alongside their event-specific fields:

FieldTypeDescription
eventIdstringStable notification id. Treat it as opaque and use it to deduplicate retries.
occurredAtstringISO-8601 time of the failure or confirmed refund, not the HTTP delivery time.
externalIdstringExternal id of the original deposit, used to match your order.
walletChargestringHodle id of the original deposit charge.
trackIdstringTracking id of the deposit; may be absent if none was recorded.
assetstringAsset requested in the deposit, such as LIGHTNING or USDT. A PIX refund returns BRL to the payer.
networkstringNetwork requested in the deposit, such as lightning or polygon.
valuenumberOriginal deposit amount in BRL cents: 2000 means R$20.00.
valueInBrlstringOriginal deposit amount in BRL, formatted with two decimal places.

DEPOSIT_ASSET_FAILED

Sent when a paid deposit definitively fails to deliver the requested asset. retryable: false means the customer must wait for a full refund before starting another purchase. This event does not confirm that any money has been returned.

DEPOSIT_ASSET_FAILED
{
  "event": "DEPOSIT_ASSET_FAILED",
  "data": {
    "eventId": "deposit-failed-65f1a8b2c3d4e5f6a7b8c9d0",
    "occurredAt": "2026-09-11T02:00:00.000Z",
    "externalId": "order-example",
    "walletCharge": "65f1a8b2c3d4e5f6a7b8c9d0",
    "trackId": "example-track",
    "asset": "LIGHTNING",
    "network": "lightning",
    "value": 2000,
    "valueInBrl": "20.00",
    "success": false,
    "status": "FAILED",
    "errorCode": "DEPOSIT_DELIVERY_FAILED",
    "errorDescription": "Não foi possível concluir a entrega. Aguarde a confirmação do estorno antes de tentar novamente.",
    "retryable": false
  }
}

Failure fields

FieldTypeDescription
successbooleanAlways false: delivery failed.
statusstringAlways FAILED.
errorCodestringDEPOSIT_DELIVERY_FAILED.
errorDescriptionstringCustomer-safe explanation. Raw provider errors are not included.
retryablebooleanAlways false. A failure alone does not permit another purchase.

DEPOSIT_ASSET_REFUNDED

Confirms a partial or full PIX return to the original payer. It may follow a delivery failure or a refund of a completed deposit, so do not require a prior failure event.

Full refund

In this example the original R$20.00 deposit was fully returned to the payer:

DEPOSIT_ASSET_REFUNDED — full refund
{
  "event": "DEPOSIT_ASSET_REFUNDED",
  "data": {
    "eventId": "deposit-refund-65f1a8b2c3d4e5f6a7b8c9d0-D00000000202609110205example000001",
    "occurredAt": "2026-09-11T02:05:00.000Z",
    "externalId": "order-example",
    "walletCharge": "65f1a8b2c3d4e5f6a7b8c9d0",
    "trackId": "example-track",
    "asset": "LIGHTNING",
    "network": "lightning",
    "value": 2000,
    "valueInBrl": "20.00",
    "success": true,
    "status": "REFUNDED",
    "refundStatus": "CONFIRMED",
    "refundValue": 2000,
    "refundedValue": 2000,
    "refundEndToEndId": "D00000000202609110205example000001",
    "partial": false,
    "retryable": true
  }
}

Partial refund

Here only R$5.00 of a failed R$20.00 deposit has been returned. The charge keeps its previous status (FAILED in this example), and retryable remains false:

DEPOSIT_ASSET_REFUNDED — partial refund
{
  "event": "DEPOSIT_ASSET_REFUNDED",
  "data": {
    "eventId": "deposit-refund-65f1a8b2c3d4e5f6a7b8c9d1-D00000000202609110205example000002",
    "occurredAt": "2026-09-11T02:05:00.000Z",
    "externalId": "order-partial-example",
    "walletCharge": "65f1a8b2c3d4e5f6a7b8c9d1",
    "trackId": "example-partial-track",
    "asset": "LIGHTNING",
    "network": "lightning",
    "value": 2000,
    "valueInBrl": "20.00",
    "success": true,
    "status": "FAILED",
    "refundStatus": "CONFIRMED",
    "refundValue": 500,
    "refundedValue": 500,
    "refundEndToEndId": "D00000000202609110205example000002",
    "partial": true,
    "retryable": false
  }
}

Refund fields

FieldTypeDescription
successbooleanAlways true: this refund was confirmed. It does not mean the requested asset was delivered or the entire deposit was refunded.
statusstringREFUNDED when cumulative confirmed refunds equal the original deposit amount. Otherwise, the charge's previous status.
refundStatusstringAlways CONFIRMED for the individual refund reported by this event, including a partial refund.
refundValuenumberAmount of this individual refund in BRL cents.
refundedValuenumberCumulative confirmed refunds for the deposit in BRL cents at verification time.
refundEndToEndIdstringPIX end-to-end id of this refund. It identifies the return, not the original payment.
partialbooleantrue while cumulative confirmed refunds are less than value; false once the entire deposit has been returned.
retryablebooleantrue only after a full confirmed refund. The customer may start a new purchase; this does not retry the original deposit.

Use refundedValue as the cumulative total; do not add it to the previous total or count the same eventId twice.

Handling failures and refunds

Match externalId to your order. Show failures and partial refunds as awaiting resolution; offer a new purchase only when retryable is true.

Keep polling GET /api/deposit/{id} while awaiting a refund. Its refundStatus describes the whole deposit: PARTIALLY_REFUNDED for a partial return, CONFIRMED for a full return. In the webhook, it describes the individual refund and is always CONFIRMED. The GET also returns refundedValue, refundedAt, refundEndToEndId and retryable.

Dispute events (MED)

A MED (Mecanismo Especial de Devolução) is a PIX fraud contestation opened by the payer's bank.

EventWhat happened
DISPUTE_CREATEDThe MED was opened. The disputed amount is frozen on the receiving account.
DISPUTE_ACCEPTEDThe contestation was accepted — the amount goes back to the payer.
DISPUTE_REJECTEDThe contestation was rejected — the amount stays with you.
DISPUTE_CANCELEDThe contestation was withdrawn before any decision.

All four events use the same payload. Match walletCharge.externalId to your order or endToEndId to the PIX.

A dispute can arrive after asset delivery. Flag the payer for review rather than retrying the order.

DISPUTE_CREATED
{
  "event": "DISPUTE_CREATED",
  "data": {
    "status": "CREATED",
    "providerStatus": "OPENED",
    "disputeId": null,
    "endToEndId": "E00416968202608231253t7wOSElb8rU",
    "value": 10000,
    "valueInBrl": "100.00",
    "reason": "No intuito de recuperar meu primeiro investimento me pediu mais dinheiro",
    "payerName": null,
    "transactionDate": "2026-08-23T12:53:00.000Z",
    "occurredAt": "2026-08-25T09:14:22.104Z",
    "walletCharge": {
      "id": "6650b21c9f4d3a0012ab34cd",
      "externalId": "my-order-123",
      "trackId": "9f4d3a0012ab34cd6650b21c",
      "correlationID": "3f1a9c7e-2b44-4d10-9a51-8c2d6e0f4b73",
      "asset": "USDT",
      "network": "polygon",
      "status": "COMPLETED",
      "valueInBrl": "100.00",
      "fee": "2.00",
      "transactionHash": "0xeafe9c4985963a7a7d6e49f763cca5c6006693031402d46c0da2fced4519fe03",
      "createdAt": "2026-08-23T12:52:41.000Z"
    }
  }
}

Fields

FieldTypeDescription
statusstringNormalized status: CREATED, ACCEPTED, REJECTED or CANCELED. Always matches the event.
providerStatusstring | nullThe provider's own status string (e.g. OPENED). Free-form — report it, never route on it.
disputeIdstring | nullProvider id of the dispute, when the provider sends one.
endToEndIdstringEnd-to-end id identifying the contested PIX and its dispute.
valuenumberContested amount in BRL cents.
valueInBrlstringContested amount in BRL, decimal string.
reasonstring | nullFree-text reason given by the payer to their bank.
payerNamestring | nullName of the payer who opened the contestation. Only on your own virtual account; null otherwise.
payerobjectOnly on your own virtual account: name and taxId (CPF/CNPJ, digits only) of the payer. Absent otherwise.
accountobjectOnly on your own virtual account: name, taxId and accountId of your account that received the Pix. Absent otherwise.
transactionDatestring | nullISO-8601 timestamp of when the contested transaction was made — not when the MED was opened.
occurredAtstringISO-8601 timestamp of this event.
walletChargeobject | nullThe operation the contested Pix funded. null when the Pix funded no charge — see below.

walletCharge

walletCharge identifies the operation funded by the contested PIX:

FieldTypeDescription
idstringHodle id of the charge.
externalIdstring | nullThe external id you sent when creating the deposit — your order key.
trackIdstring | nullHodle tracking id of the operation.
correlationIDstring | nullProvider correlation id of the Pix charge.
assetstring | nullAsset delivered (USDT, USDC, BRLA, …).
networkstring | nullNetwork the asset was delivered on.
statusstring | nullCharge status at the time of the event (COMPLETED, FAILED, …).
valueInBrlstringValue of the charge in BRL. May differ from the contested amount on a partial MED.
feestringFee charged, in BRL.
transactionHashstring | nullOn-chain tx hash of the delivery, when there is one.
createdAtstring | nullISO-8601 creation timestamp of the charge.

walletCharge may be null if no matching charge is available. Match endToEndId against your own records instead.

Handling the event

One handler for the four legs
type DisputeData = {
  status: 'CREATED' | 'ACCEPTED' | 'REJECTED' | 'CANCELED'
  endToEndId: string
  value: number
  reason: string | null
  walletCharge: { externalId: string | null } | null
}

const handleDispute = async (data: DisputeData): Promise<void> => {
  const orderRef = data.walletCharge?.externalId ?? null

  if (data.status === 'CREATED') {
    return flagOrderUnderDispute({
      dedupeKey: data.endToEndId,
      orderRef,
      amountInCents: data.value,
      reason: data.reason,
    })
  }

  return closeDispute({
    dedupeKey: data.endToEndId,
    orderRef,
    lostToPayer: data.status === 'ACCEPTED',
  })
}
  • Use endToEndId to identify the dispute and handle redeliveries idempotently without discarding later status changes.
  • Handle missing or out-of-order events; a dispute may remain open for days.
  • DISPUTE_ACCEPTED returns the amount to the payer; REJECTED and CANCELED leave it with you.