Webhooks

Webhooks do Stablecoin

Os webhooks notificam sua aplicação sobre o resultado do depósito e do payout de stablecoin. Caso ainda não saiba como cadastrar webhooks na plataforma, veja o nosso tutorial.

Depósito (on-ramp)

Evento	Quando ocorre
`STABLECOIN_DEPOSIT_COMPLETED`	A stablecoin foi entregue na blockchain
`STABLECOIN_DEPOSIT_FAILED`	O depósito falhou em alguma etapa

O objeto enviado contém stableDeposit (os dados do depósito) e company (sua empresa). O campo correlationID corresponde ao identificador único que você enviou ao criar o depósito.

STABLECOIN_DEPOSIT_COMPLETED

Disparado quando a stablecoin é entregue com sucesso na carteira de destino. O campo txHash traz o hash da transação on-chain.

{
  "event": "STABLECOIN_DEPOSIT_COMPLETED",
  "stableDeposit": {
    "id": "6650abc1234def567890aaaa",
    "status": "COMPLETED",
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "txHash": "0x587a660fe5349113801ec77fa6f79ae096e53a67bfa7f9098f096d1b9575fa53",
    "correlationID": "my-unique-id",
    "completedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  }
}

STABLECOIN_DEPOSIT_FAILED

Disparado quando o depósito falha. Os campos reason e errorCode indicam o motivo.

{
  "event": "STABLECOIN_DEPOSIT_FAILED",
  "stableDeposit": {
    "id": "6650abc1234def567890aaaa",
    "status": "FAILED",
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputCurrency": "USDT",
    "correlationID": "my-unique-id",
    "failedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  },
  "reason": "Deposit failed",
  "errorCode": "DEPOSIT-FAILED"
}

Webhooks do Payout (off-ramp)

Quando você cria um payout via POST /api/v1/stablecoin/payout, o resultado final chega por webhook:

Evento	Quando ocorre
`STABLECOIN_PAYOUT_COMPLETED`	O Pix foi pago / ticket do provedor em estado terminal de sucesso
`STABLECOIN_PAYOUT_FAILED`	O payout falhou — o Pix não saiu
`STABLECOIN_PAYOUT_REFUND_CONFIRMED`	O Pix saiu, voltou, e o valor está disponível de novo no seu saldo de stablecoin
`STABLECOIN_PAYOUT_REFUND_FAILED`	O Pix saiu, voltou, mas o valor não está disponível para você

O objeto enviado contém stablePayout e company. O campo correlationID corresponde ao correlationId enviado na criação.

STABLECOIN_PAYOUT_COMPLETED

{
  "event": "STABLECOIN_PAYOUT_COMPLETED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 100,
    "inputCurrency": "USDT",
    "outputAmount": 5.08,
    "outputCurrency": "BRL",
    "pixKey": "[email protected]",
    "endToEndId": "E123...",
    "correlationID": "payout-001",
    "completedAt": "2026-08-04T17:10:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  }
}

STABLECOIN_PAYOUT_FAILED

{
  "event": "STABLECOIN_PAYOUT_FAILED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "FAILED",
    "inputAmount": 100,
    "inputCurrency": "USDT",
    "outputCurrency": "BRL",
    "pixKey": "[email protected]",
    "correlationID": "payout-001",
    "failedAt": "2026-08-04T17:10:00.000Z"
  },
  "company": {
    "name": "Acme Corp"
  },
  "reason": "Payout failed",
  "errorCode": "PAYOUT-FAILED"
}

Devolução de um payout já liquidado

Um payout liquidado pode voltar — o recebedor devolve o Pix, ou o banco dele rejeita o crédito. Nesse caso o status do payout continua COMPLETED: o Pix realmente saiu, e reverter o status quebraria a máquina de estados que você já construiu em cima do STABLECOIN_PAYOUT_COMPLETED. A devolução chega como um evento novo, com um bloco refund.

FAILED e REFUND_* são mutuamente exclusivos no mesmo payout: FAILED significa que o Pix nunca saiu; REFUND_* significa que saiu e voltou.

Campos do bloco refund:

Campo	Descrição
`status`	`CONFIRMED` ou `FAILED` — se o valor devolvido está disponível para você
`amount`	Em centavos de `currency`, a mesma unidade do `stablePayout.inputAmount` — nunca o `outputAmount` em BRL
`currency`	O ativo de entrada do payout, ex.: `BRLA`, `USDT`
`destination`	`SUBACCOUNT_BALANCE` (sacável por você), `MAIN_BALANCE` (creditado fora da sua subconta, precisa de intervenção manual) ou `NONE` (nada foi creditado)
`providerTicketId`	O ticket da devolução, não o do payout original. Use como chave de idempotência: uma reentrega repete o mesmo valor
`originalProviderTicketId`	O ticket do payout original, quando o provedor informa
`reason`	Motivo informado pelo provedor
`refundEndToEndId`	O `endToEndId` da devolução Pix, quando existe
`failureReason`	Só em `REFUND_FAILED`: por que o valor não está disponível
`refundedAt`	Quando a devolução foi registrada

STABLECOIN_PAYOUT_REFUND_CONFIRMED

O valor voltou e está disponível de novo no seu saldo de stablecoin — é seguro reembolsar o seu cliente final.

{
  "event": "STABLECOIN_PAYOUT_REFUND_CONFIRMED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 3379,
    "inputCurrency": "BRLA",
    "outputAmount": 33.73,
    "outputCurrency": "BRL",
    "pixKey": "[email protected]",
    "endToEndId": "E123...",
    "correlationID": "payout-001"
  },
  "company": {
    "name": "Acme Corp"
  },
  "refund": {
    "status": "CONFIRMED",
    "amount": 3379,
    "currency": "BRLA",
    "destination": "SUBACCOUNT_BALANCE",
    "providerTicketId": "9a1c4f7e-2b83-4d55-9c0e-1f6a2d3b4c5d",
    "originalProviderTicketId": "018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "reason": "payout reversed - original ticket id: 018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "refundEndToEndId": "E54811417202608251402",
    "refundedAt": "2026-08-25T14:02:41.318Z"
  }
}

STABLECOIN_PAYOUT_REFUND_FAILED

O valor voltou, mas não está disponível para você: ou a própria devolução não se concretizou, ou o crédito caiu fora da sua subconta. Não credite o seu cliente final — o caso precisa de conciliação.

{
  "event": "STABLECOIN_PAYOUT_REFUND_FAILED",
  "stablePayout": {
    "id": "6a721b1e3c785acfaebfa01c",
    "status": "COMPLETED",
    "inputAmount": 3379,
    "inputCurrency": "BRLA",
    "outputAmount": 33.73,
    "outputCurrency": "BRL",
    "pixKey": "[email protected]",
    "endToEndId": "E123...",
    "correlationID": "payout-001"
  },
  "company": {
    "name": "Acme Corp"
  },
  "refund": {
    "status": "FAILED",
    "amount": 3379,
    "currency": "BRLA",
    "destination": "NONE",
    "providerTicketId": "9a1c4f7e-2b83-4d55-9c0e-1f6a2d3b4c5d",
    "originalProviderTicketId": "018f2b2c-9a4d-4a6f-b0d5-7c9f1e2a3b44",
    "failureReason": "returned funds not available in the sub-account balance",
    "refundedAt": "2026-08-25T14:02:41.318Z"
  }
}

Webhooks da Subconta (KYB)

Quando você solicita uma subconta de stablecoin (KYB) via POST /api/v1/stablecoin/subaccount, ela é criada com status IN_REVIEW enquanto a análise é processada. O resultado não é síncrono: assim que o KYB é resolvido pelo provedor, sua aplicação recebe um destes eventos.

Evento	Quando ocorre
`STABLECOIN_SUBACCOUNT_CONFIRMED`	O KYB foi aprovado e a subconta está apta a receber depósitos
`STABLECOIN_SUBACCOUNT_REJECTED`	O KYB foi recusado; a subconta não pode operar

O objeto enviado contém stableSubAccount (os dados da subconta) e company (sua empresa). Use o campo stableSubAccount.id para conciliar com o subAccountId retornado na criação.

STABLECOIN_SUBACCOUNT_CONFIRMED

Disparado quando o KYB é aprovado. A partir deste momento a subconta tem status: "CONFIRMED" e pode ser usada em POST /api/v1/stablecoin/deposit. O campo confirmedAt traz o instante da confirmação.

{
  "event": "STABLECOIN_SUBACCOUNT_CONFIRMED",
  "stableSubAccount": {
    "id": "6650abc1234def567890aaaa",
    "status": "CONFIRMED",
    "subAccountId": "sub_01HZ...",
    "accountRegisterId": "6650def1234abc567890bbbb",
    "confirmedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "id": "6650aaa1234bbb567890cccc",
    "name": "Acme Corp",
    "taxID": "12345678000199"
  }
}

STABLECOIN_SUBACCOUNT_REJECTED

Disparado quando o KYB é recusado. Os campos opcionais reason e rejectionLabels indicam o motivo da recusa, quando disponíveis.

{
  "event": "STABLECOIN_SUBACCOUNT_REJECTED",
  "stableSubAccount": {
    "id": "6650abc1234def567890aaaa",
    "status": "REJECTED",
    "subAccountId": "sub_01HZ...",
    "accountRegisterId": "6650def1234abc567890bbbb",
    "rejectedAt": "2026-06-05T12:00:00.000Z"
  },
  "company": {
    "id": "6650aaa1234bbb567890cccc",
    "name": "Acme Corp",
    "taxID": "12345678000199"
  },
  "reason": "Document verification failed",
  "rejectionLabels": ["INVALID_DOCUMENT"]
}

Webhooks do Stablecoin​

Depósito (on-ramp)​

STABLECOIN_DEPOSIT_COMPLETED​

STABLECOIN_DEPOSIT_FAILED​

Webhooks do Payout (off-ramp)​

STABLECOIN_PAYOUT_COMPLETED​

STABLECOIN_PAYOUT_FAILED​

Devolução de um payout já liquidado​

STABLECOIN_PAYOUT_REFUND_CONFIRMED​

STABLECOIN_PAYOUT_REFUND_FAILED​

Webhooks da Subconta (KYB)​

STABLECOIN_SUBACCOUNT_CONFIRMED​

STABLECOIN_SUBACCOUNT_REJECTED​