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
- Open API Keys → Webhooks and click Configurar Webhook.
- Enter your public HTTPS endpoint and select
KYC_APPROVED,KYC_REJECTED,KYC_EXPIRED, orKYC_FAILED. - Submit. If registration fails, the webhook is not saved; try again in a few minutes.
Events
| Event | Description |
|---|---|
DEPOSIT_PIX_CONFIRMED | The PIX paying a deposit settled; the asset delivery has not finished yet. |
DEPOSIT_ASSET_SUCCESS | A deposit was completed successfully. |
DEPOSIT_ASSET_FAILED | A paid deposit could not deliver the requested asset. |
DEPOSIT_ASSET_REFUNDED | A partial or full PIX refund to the deposit's payer was confirmed. |
DEPOSIT_ONCHAIN_RECEIVED | Crypto arrived on-chain in a wallet of your account or a sub-account. |
DEPOSIT_ON_HOLD | A paid deposit is retained for compliance review instead of delivered. |
PAYOUT_SUCCESSFUL | A PIX payout was sent successfully. |
PAYOUT_FAILED | A PIX payout failed. |
PAYOUT_REFUNDED | A settled payout was reversed and refunded. |
PAYOUT_ON_HOLD | A payout was retained by a compliance review and not sent. |
WALLET_TRANSFER_COMPLETED | A POST /api/wallet/transfer send was confirmed on-chain. |
WALLET_TRANSFER_FAILED | A POST /api/wallet/transfer send accepted as pending never landed. |
KYC_APPROVED | KYC for an end-user was approved. |
KYC_REJECTED | KYC for an end-user was rejected. |
KYC_EXPIRED | KYC attempt expired without submission. |
KYC_FAILED | KYC attempt failed during processing. |
DISPUTE_CREATED | A PIX you received was contested (MED opened). |
DISPUTE_ACCEPTED | The contestation was accepted — the amount is returned to the payer. |
DISPUTE_REJECTED | The contestation was rejected — the amount stays with you. |
DISPUTE_CANCELED | The contestation was withdrawn before a decision. |
CARD_KYC_APPROVED | A card holder's identity check was approved (once per holder). |
CARD_KYC_REJECTED | A card holder's identity check was rejected; terminal (once per holder). |
CARD_ISSUED | A 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:
| Header | Description |
|---|---|
X-Hodle-Signature | HMAC-SHA256 signature of the payload, hex-encoded. |
X-Hodle-Timestamp | Unix timestamp (seconds) when the request was sent. |
X-Hodle-Delivery-Attempt | 1 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.
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)
}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
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:
| Attempt | X-Hodle-Delivery-Attempt | When |
|---|---|---|
| First delivery | 1 | As soon as the event happens. |
| Retry 1 | 2 | 10 seconds after attempt 1 failed. |
| Retry 2 | 3 | 60 seconds after attempt 2 failed. |
| Retry 3 | 4 | 5 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.
{
"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"
}
}{
"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
| Field | Type | Description |
|---|---|---|
success | boolean | Always true on this event. |
transactionId | string | Our id for the payout — the same one POST /api/wallet/payout returned. |
externalId | string | null | The idempotency key you created the payout with. null when the payout was not created through the API. |
trackId | string | null | Internal tracking id of the payout. |
status | string | Always COMPLETED on this event. |
asset | string | null | Asset debited to fund the payout (USDT, USDC, BRLA, BRS, LIGHTNING). |
network | string | null | Network the asset was debited on. |
valueInBrl | string | Value paid out, in BRL. Source of truth for the amount. |
fee | string | Fee charged, in BRL. |
pixKey | string | null | The PIX key where BRL was sent. |
endToEndId | string | null | Bacen end-to-end id of the settled PIX. null if none was reported. |
txHash | string | null | On-chain transaction id of the debit, or the bolt11 invoice on a Lightning-funded payout. |
receipt | object | null | Receipt detail of the settled PIX — see Receipt detail. null when none was reported. |
receiptUrl | string | null | PDF comprovante, when one was rendered. |
quote.brlAmount | string | BRL amount quoted. |
quote.assetAmount | string | null | Amount in asset the BRL value converts to at fxRateAtTx. |
quote.fxRateAtTx | number | null | BRL per unit of asset at the time of the payout. |
quote.btcAmount | number | Bitcoin-priced payouts only. BTC amount. |
quote.satoshis | number | Bitcoin-priced payouts only. Amount in satoshis. |
quote.btcToBrlRate | number | Bitcoin-priced payouts only. BTC to BRL rate at the time. |
valueInSatoshis | number | Bitcoin-priced payouts only. Amount in satoshis. Absent on stablecoin payouts — use valueInBrl. |
invoice | string | null | Legacy 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.
| Field | Type | Description |
|---|---|---|
endToEndId | string | Bacen end-to-end id, the identifier the payee's bank shows for this PIX. |
paidAt | string | ISO-8601 settlement time reported by the settling institution. |
amountInBrl | string | Amount that left, in BRL. |
payerIspb | string | ISPB of the institution that debited the funds, read from the end-to-end id. |
brCode | string | Optional. Original PIX BR Code (copia e cola) for a QR payout, when available. |
receiver.name | string | Payee name as resolved by the receiving bank. |
receiver.taxId | string | Payee tax id. A CPF is masked (***.241.413-**); a CNPJ is public registry data and comes whole. |
receiver.pixKey | string | PIX key the transfer was addressed to. |
receiver.pixKeyType | string | Optional. PIX key type, such as EMAIL or CPF, when available. |
receiver.bankName | string | Payee bank name when reported; otherwise null. |
receiver.bankCode | string | Optional. Bank code when reported, such as 001; distinct from the ISPB. |
receiver.ispb | string | ISPB of the payee's institution — resolve the name with Bacen's participant list. |
receiver.branch | string | Payee branch (agência). |
receiver.account | string | Payee account, masked to the last four digits. |
receiver.accountType | string | Account 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.
{
"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.
{
"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
| Field | Type | Description |
|---|---|---|
success | boolean | Always false: the payout was not sent. |
status | string | Always ON_HOLD. |
reason | string | Always COMPLIANCE_REVIEW. The review criteria are not disclosed. |
eventId | string | Stable id of this notification, one per payout. Use it to deduplicate retries. |
transactionId | string | null | Our id for the payout. null when the payout was retained before it was created. |
externalId | string | null | The idempotency key you sent with the payout, if any. |
subAccountId | string | null | The sub-account the payout was attributed to, if any. |
valueInBrl | string | Value of the payout, in BRL. |
pixKey | string | null | The PIX key the payout targeted. null for a BR Code payout. |
occurredAt | string | ISO-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).
{
"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"
}
}| Field | Type | Description |
|---|---|---|
success | boolean | Always true — the event reports a completed reversal, not a failure. |
transactionId | string | Id of the original payout transaction. |
endToEndId | string | null | PIX end-to-end id of the original payout, when we have it. |
pixKey | string | PIX key the original payout was sent to. |
valueInBrl | string | Value of the original payout in BRL. |
returnedAmount | string | Amount actually returned by the reversal (BRLA). May be empty if the provider omits it, and may be less than valueInBrl on a partial return. |
originalTicketId | string | Provider ticket id of the original payout. |
reversalTicketId | string | Provider ticket id of the reversal itself. Use it to deduplicate. |
reason | string | Free-text reason from the provider describing the reversal. |
refundTxId | string | null | On-chain tx hash of the refund we sent the user. null when no refund was sent. |
refundAddress | string | null | Address 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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
transactionId | string | Id of the original payout transaction. |
refundTxId | string | On-chain tx hash of the refund. |
refundAddress | string | Address that received the refund. |
asset | string | Refunded asset (USDT, USDC, USDCE, BRLA). |
network | string | Network of the refund (polygon or base). |
stableAmount | string | Amount refunded in the stablecoin's own unit. |
pixKey | string | PIX key of the original payout. |
valueInBrl | string | Value of the original payout in BRL. |
refundedAt | string | ISO-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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
invoice | string | The original bolt11 invoice that funded the payout. |
refundAddress | string | null | Lightning address the refund was sent to, when one was registered. |
refundInvoice | string | The bolt11 invoice we paid to refund the user. |
refundTxId | string | Lightning payment id of the refund. |
valueInSatoshis | number | Amount refunded, in satoshis. |
pixKey | string | PIX key of the original payout. |
valueInBrl | string | Value of the original payout in BRL. |
refundedAt | string | ISO-8601 timestamp of the refund. |
Handling the event
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
reversalTicketIdand manual refunds byrefundTxId. - Match
transactionId(ororiginalTicketIdon 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:
| Field | Type | Description |
|---|---|---|
subAccountId | string | null | The sub-account the KYC belongs to. |
userId | string | null | The 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:
| Event | When |
|---|---|
WALLET_TRANSFER_COMPLETED | The 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_FAILED | A 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.
{
"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
| Field | Type | Description |
|---|---|---|
eventId | string | Stable id of this notification, one per transfer and the same on every retry. Use it to deduplicate. |
transactionId | string | The data.transactionId the transfer request returned. |
reference | string | null | The reference you sent with the transfer, if any. |
externalId | string | null | Same value as reference, under the name the other webhooks use. |
status | string | COMPLETED or FAILED, matching the event. |
accountId | string | Your account (the owner of the API key). |
subAccountId | string | null | The fromSubAccountId of the request. null for a transfer from your own account's wallet. |
network | string | polygon, base, bnb or solana. |
asset | string | The asset sent, as the transfer response reports it. |
amount | string | The amount you requested, as a decimal string in units of asset. |
fromAddress | string | null | The sending wallet address. |
toAddress | string | The destination address, as the transfer response reports it in recipientAddress. |
txHash | string | null | Transaction hash (on Solana, the signature). Can be null on WALLET_TRANSFER_FAILED when nothing was mined. |
createdAt | string | ISO-8601 time the transfer was accepted. |
completedAt | string | ISO-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.
{
"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:
{
"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":
{
"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.
{
"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:
{
"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.
{
"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.
{
"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.
{
"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"
}
}error | retryable | What to do |
|---|---|---|
LIVENESS_BELOW_THRESHOLD | true | The 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.
{
"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
| Field | Type | Description |
|---|---|---|
eventId | string | Stable id of this notification, one per deposit. The same on every retry; use it to deduplicate. |
occurredAt | string | ISO-8601 time the deposit was completed, not the HTTP delivery time. |
success | boolean | Always true on this event. |
externalId | string | The external ID sent in the deposit request, or an auto-generated UUID. |
walletCharge | string | Hodle id of the deposit, the same one the POST returned. |
trackId | string | Hodle tracking id of the deposit. |
asset, network | string | Asset and network delivered. |
value | number | Amount in BRL cents. |
valueInBrl | string | Same amount, formatted BRL. |
valueInCurrency | number | Stablecoin deposits: amount delivered, in units of asset. |
fee | string | Stablecoin deposits: fee charged, formatted BRL. |
fxRateAtTx | number | Stablecoin 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:
{
"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"
}
}| Field | Type | Description |
|---|---|---|
payer.name | string | null | Name of whoever paid the PIX, as the bank reports it. |
payer.taxId | string | null | CPF/CNPJ of the payer, digits only. |
endToEndId | string | null | End-to-end id of the PIX that funded the deposit. |
paidAt | string | null | ISO-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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
status | string | Always FIAT_PAID: the PIX settled, the asset is not delivered yet. |
endToEndId | string | null | End-to-end id of the PIX that paid the deposit. |
paidAt | string | ISO-8601 settlement time, or the time Hodle received confirmation if no settlement time was reported. |
eventId | string | Stable id of this notification, one per deposit. Use it to deduplicate retries. |
occurredAt | string | Same instant as paidAt, not the HTTP delivery time. |
externalId, walletCharge, trackId | string | Ids of the deposit, as in the other deposit events. |
asset, network | string | Asset and network requested in the deposit. |
value, valueInBrl | number, string | Deposit 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.
| Network | Assets |
|---|---|
polygon | USDC, USDT, BRLA |
base | USDC, BRLA |
solana | USDC, 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.
{
"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"
}
}{
"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
| Field | Type | Description |
|---|---|---|
eventId | string | Stable id of this notification, one per transfer and the same on every retry. Treat it as opaque and use it to deduplicate. |
network | string | polygon, base or solana. |
asset | string | The token received: see the table above. |
amount | string | Amount received, as a decimal string in units of asset ("125.5" is 125.5 USDC). |
amountRaw | string | The same amount in the token's smallest unit, as an integer string. |
toAddress | string | The wallet address that received it, as POST /api/wallet/get returns it in addresses. |
fromAddress | string | null | EVM: the sending address (0x0000000000000000000000000000000000000000 for a token mint). Solana: the owner of the sending account, null if none. |
txHash | string | Transaction hash. On Solana, the transaction signature. |
logIndex | number | EVM only. Position of the transfer in its block; one transaction can carry several transfers. |
blockNumber | number | EVM only. Block that included the transfer. |
signature | string | Solana only. The transaction signature, same as txHash. |
slot | number | Solana only. Slot that included the transaction. |
walletId | string | Hodle id of the wallet that received it, the data.id of POST /api/wallet/create. |
subAccountId | string | null | The sub-account the wallet belongs to. null for a wallet of your own account. |
receivedAt | string | ISO-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:
| Network | Announced after | Usual time from transfer to delivery |
|---|---|---|
polygon | 64 blocks | About 2 to 3 minutes |
base | 12 blocks | Under a minute |
solana | Finalized commitment | Under 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.
{
"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"
}
}| Field | Type | Description |
|---|---|---|
status | string | Always ON_HOLD: the PIX settled and the asset is retained. |
reason | string | Always COMPLIANCE_REVIEW. The review criteria are not disclosed. |
subAccountId | string | null | The sub-account of the deposit, if you sent one. |
heldAt | string | ISO-8601 time the deposit was retained. |
eventId | string | Stable id of this notification, one per deposit. Use it to deduplicate retries. |
occurredAt | string | Same instant as heldAt, not the HTTP delivery time. |
externalId, walletCharge, trackId | string | Ids of the deposit, as in the other deposit events. |
asset, network | string | Asset and network requested in the deposit. |
value, valueInBrl | number, string | Deposit 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:
| Field | Type | Description |
|---|---|---|
eventId | string | Stable notification id. Treat it as opaque and use it to deduplicate retries. |
occurredAt | string | ISO-8601 time of the failure or confirmed refund, not the HTTP delivery time. |
externalId | string | External id of the original deposit, used to match your order. |
walletCharge | string | Hodle id of the original deposit charge. |
trackId | string | Tracking id of the deposit; may be absent if none was recorded. |
asset | string | Asset requested in the deposit, such as LIGHTNING or USDT. A PIX refund returns BRL to the payer. |
network | string | Network requested in the deposit, such as lightning or polygon. |
value | number | Original deposit amount in BRL cents: 2000 means R$20.00. |
valueInBrl | string | Original 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.
{
"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
| Field | Type | Description |
|---|---|---|
success | boolean | Always false: delivery failed. |
status | string | Always FAILED. |
errorCode | string | DEPOSIT_DELIVERY_FAILED. |
errorDescription | string | Customer-safe explanation. Raw provider errors are not included. |
retryable | boolean | Always 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:
{
"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:
{
"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
| Field | Type | Description |
|---|---|---|
success | boolean | Always true: this refund was confirmed. It does not mean the requested asset was delivered or the entire deposit was refunded. |
status | string | REFUNDED when cumulative confirmed refunds equal the original deposit amount. Otherwise, the charge's previous status. |
refundStatus | string | Always CONFIRMED for the individual refund reported by this event, including a partial refund. |
refundValue | number | Amount of this individual refund in BRL cents. |
refundedValue | number | Cumulative confirmed refunds for the deposit in BRL cents at verification time. |
refundEndToEndId | string | PIX end-to-end id of this refund. It identifies the return, not the original payment. |
partial | boolean | true while cumulative confirmed refunds are less than value; false once the entire deposit has been returned. |
retryable | boolean | true 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.
| Event | What happened |
|---|---|
DISPUTE_CREATED | The MED was opened. The disputed amount is frozen on the receiving account. |
DISPUTE_ACCEPTED | The contestation was accepted — the amount goes back to the payer. |
DISPUTE_REJECTED | The contestation was rejected — the amount stays with you. |
DISPUTE_CANCELED | The 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.
{
"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
| Field | Type | Description |
|---|---|---|
status | string | Normalized status: CREATED, ACCEPTED, REJECTED or CANCELED. Always matches the event. |
providerStatus | string | null | The provider's own status string (e.g. OPENED). Free-form — report it, never route on it. |
disputeId | string | null | Provider id of the dispute, when the provider sends one. |
endToEndId | string | End-to-end id identifying the contested PIX and its dispute. |
value | number | Contested amount in BRL cents. |
valueInBrl | string | Contested amount in BRL, decimal string. |
reason | string | null | Free-text reason given by the payer to their bank. |
payerName | string | null | Name of the payer who opened the contestation. Only on your own virtual account; null otherwise. |
payer | object | Only on your own virtual account: name and taxId (CPF/CNPJ, digits only) of the payer. Absent otherwise. |
account | object | Only on your own virtual account: name, taxId and accountId of your account that received the Pix. Absent otherwise. |
transactionDate | string | null | ISO-8601 timestamp of when the contested transaction was made — not when the MED was opened. |
occurredAt | string | ISO-8601 timestamp of this event. |
walletCharge | object | null | The operation the contested Pix funded. null when the Pix funded no charge — see below. |
walletCharge
walletCharge identifies the operation funded by the contested PIX:
| Field | Type | Description |
|---|---|---|
id | string | Hodle id of the charge. |
externalId | string | null | The external id you sent when creating the deposit — your order key. |
trackId | string | null | Hodle tracking id of the operation. |
correlationID | string | null | Provider correlation id of the Pix charge. |
asset | string | null | Asset delivered (USDT, USDC, BRLA, …). |
network | string | null | Network the asset was delivered on. |
status | string | null | Charge status at the time of the event (COMPLETED, FAILED, …). |
valueInBrl | string | Value of the charge in BRL. May differ from the contested amount on a partial MED. |
fee | string | Fee charged, in BRL. |
transactionHash | string | null | On-chain tx hash of the delivery, when there is one. |
createdAt | string | null | ISO-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
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
endToEndIdto 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_ACCEPTEDreturns the amount to the payer;REJECTEDandCANCELEDleave it with you.