Webhook Events
Here, we present the current events that you may receive through your registered Webhook, as described in the previous section. These events include the following:
| Events | Description |
|---|---|
| TICKET | A ticket event refers to any updates related to a created ticket (money) within your Account. Naturally, it may also involve a subAccount. This event can have multiple statuses, such as TICKET-CREATED, DEPOSIT-PROCESSING, among others. |
| KYC | A KYC event refers to any updates related to a KYC attempt. This event can have multiple statuses, such as KYC-STARTED, KYC-PROCESSING, KYC-EXPIRED, and KYC-COMPLETED. |
| LIMIT-UPDATE | An event that notifies you when there are changes to your account's operational limits. This is typically triggered after a successful KYC verification or when an administrator modifies your account limits. |
| WALLET-QUALIFICATION | An event that asks you to qualify the wallet that sent a deposit: WALLET-QUALIFICATION-REQUIRED. |
| DEPOSIT-HOLD | An event that asks you for the purpose code of a held deposit: DEPOSIT-PURPOSE-CODE-REQUIRED. |
| KYT-STATE | An event that notifies you when one of your users (or a user/counterparty pair) is held, placed under review, rejected or released by our compliance team. Its single status is KYT-STATE-CHANGED. |
| DISPUTE | An event that notifies you of disputes on your account's transactions. Its types so far are BRAZILIAN-PIX-DISPUTE-<STATUS>, sent as a PIX dispute (MED) on a PIX deposit to your account is opened and decided, and CARD-DISPUTE-<STATUS>, sent as a card dispute on one of your card payments reaches each status. |
| DOCUMENT | An event about a file sent to the Document Inbox (SFTP or API) or a document cited in a KYB: DOCUMENT-RECEIVED, DOCUMENT-QUARANTINED and DOCUMENT-UPLOAD-REJECTED when a file is checked, then DOCUMENT-SUBMITTED, DOCUMENT-APPROVED and DOCUMENT-REJECTED along its KYB review. Sent only when the Document Inbox is enabled for your account. |
Ticket
The Ticket Event always reflects an update related to any updates related to a created ticket within your account. In other words, for each type of transaction (as defined inside the quote field of a ticket), a ticket is generated.
Each ticket has a specific type, which determines the nature of the transaction, and during the lifecycle of that ticket, you’ll receive multiple status updates reflecting its current state.
These updates will be sent to your registered Webhook as the ticket progresses through its execution steps.
About the TICKET-ON-HOLD state (dotted path): This is an optional state entered when our risk engine flags a ticket for compliance review during deposit processing, before the deposit is settled. The ticket pauses while our compliance team reviews it. Approved tickets move to DEPOSIT-SUCCESS and proceed to DELIVERY-PROCESSING normally. Rejected tickets move to DEPOSIT-FAILED when the deposit can be refunded to the sender or the input is an Avenia balance (INTERNAL); otherwise the ticket ends in PARTIAL-FAILED with DELIVERY-PROCESSING and DELIVERY-PARTIAL-FAILED events, and the amount is credited to your Avenia balance — for most operations as Avenia's token for the output currency (BRLA for a BRL payout, USDC for USD, EURC for EUR, the same token for a crypto output); for COP, ARS, MXN and SWIFT payouts, the full input amount as the token of the input currency (for example BRLA for a PIX input). If the review window elapses without action, the ticket is auto-approved and proceeds to DEPOSIT-SUCCESS. When a ticket enters this state a TICKET-ON-HOLD webhook is dispatched.
Deposit check failures: Before crediting a BRL/PIX deposit, Avenia runs compliance and limit checks. A failed check follows the same failure path as any other rejected deposit: the ticket becomes FAILED, a DEPOSIT-FAILED webhook is sent, and the full input amount is returned asynchronously to the originating account.
The ticket's failureCode says which check failed: SENDER_BLOCKED_TAX_ID or SENDER_BLOCKED_BANK_INSTITUTION (the sender is blocked), THIRD_PARTY_DEPOSIT, LIMIT_EXCEEDED, USER_BLOCKED, a COMPLIANCE_* code for a compliance rejection, or INTERNAL_ERROR when the deposit could not be verified. Branch on failureCode; failureReason is a human-readable explanation (for example user does not have enough limit) and its wording can change. The reason field may first report Refund in progress. and later include the refund E2E ID. Treat the refund as pending until the ticket reaches its final state or the TICKET-COMPLETE webhook is received. Every code is listed in Ticket Failure Codes.
Ticket Event's Status
| Status Name | Description |
|---|---|
| TICKET-CREATED | The ticket has been successfully created—this occurs when the transaction hits the endpoint. |
| DEPOSIT-PROCESSING | The deposit phase has started and is currently being processed. |
| TICKET-ON-HOLD | The ticket has been paused for compliance review during deposit processing, before the deposit is settled. |
| DEPOSIT-SUCCESS | The deposit was completed successfully. |
| DEPOSIT-FAILED | The deposit attempt has failed. For a failed deposit gate, no output asset is credited and the full input amount is returned asynchronously. |
| DELIVERY-PROCESSING | The delivery phase (e.g., transfer of tokens or funds) is now in progress. |
| DELIVERY-SUCCESS | The delivery was completed successfully. |
| DELIVERY-FAILED | The delivery attempt has failed. |
| DELIVERY-PARTIAL-FAILED | The delivery failed after the input was already debited or converted. The ticket ends in PARTIAL-FAILED and the amount is credited to your Avenia balance. |
| TICKET-PURPOSE-CODE-REQUIRED | Sent after an international deposit (on-chain or in a currency other than BRL) is credited, when it still has no BCB purpose code. It does not pause the ticket. See Deposits. |
| TICKET-COMPLETE | The entire ticket lifecycle has been completed, regardless of the outcome. Not sent when you cancel an UNPAID ticket yourself. |
If a deposit is made to the Main Account without a previously created Ticket, a Ticket Event will still be triggered, starting with the status TICKET-CREATED. From November 15, 2026, an on-chain deposit without a ticket, from a sender wallet that is not known to be in Brazil and is not one of your own wallets, is first held: you receive DEPOSIT-PURPOSE-CODE-REQUIRED on the DEPOSIT-HOLD subscription, and its ticket, with TICKET-CREATED, only exists once the hold is released.
Any type of error will also return a REASON field, providing details about why the specific step could not be completed.
An additional note for when the Ticket represents a Pay Out—either via PIX or BrCode
When the Ticket represents a Pay Out via PIX or BrCode, the delivery status may fail. In such cases a DELIVERY-PARTIAL-FAILED event is sent, the ticket ends in PARTIAL-FAILED, and the amount is credited back to your Avenia balance in the currency the operation had reached — for example USDC if a BRL → USD payout failed after the conversion to USDC (it is not sent back on-chain). The same event is used when any other payout — bank transfer or blockchain — fails after the input was debited. The ticket's failureCode says why — for example RECEIVER_PIX_KEY_INVALID or RECEIVER_BANK_REJECTED; see Ticket Failure Codes for every code. The human-readable failureReason reads ticket failed partially: … - tokens returned to user's wallet, where "wallet" means your Avenia balance.
Ticket Event's Status Pay Out Failure
| Status Name | Description |
|---|---|
| DELIVERY-PROCESSING | The delivery phase (e.g., transfer of tokens or funds) is now in progress. |
| DELIVERY-PARTIAL-FAILED | Failure to complete Pay Out delivery |
Understanding the Data Returned in a Webhook
Ticket Events follow a standardized structure, where:
{
"event": {
"id": "6df2ae75-670f-4619-a6b1-8a5018af56b0",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {},
"type": "TICKET-CREATED"
}
"createdAt": "2025-09-16T12:32:12.338058Z"
}
Detailed ticket events
TICKET-CREATED
{
"event": {
"id": "6df2ae75-670f-4619-a6b1-8a5018af56b0",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "UNPAID",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.208933037Z",
"updatedAt": "2025-09-16T12:32:12.208933037Z",
"expiresAt": "2025-09-17T12:32:12.208933037Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "",
"taxId": "",
"bankCode": "",
"branchCode": "",
"accountNumber": "",
"accountType": "",
"endToEndId": ""
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": ""
}
},
"type": "TICKET-CREATED"
},
"createdAt": "2025-09-16T12:32:12.338058Z",
"EventType": ""
}
}
DEPOSIT-PROCESSING
{
"event": {
"id": "7b1cc0ab-5e35-4cb0-a5be-720aba6f9146",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "PROCESSING",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:12.219815Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "",
"taxId": "",
"bankCode": "",
"branchCode": "",
"accountNumber": "",
"accountType": "",
"endToEndId": ""
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": ""
}
},
"type": "DEPOSIT-PROCESSING"
},
"createdAt": "2025-09-16T12:32:26.669037Z",
"EventType": ""
}
}
DELIVERY-PROCESSING
{
"event": {
"id": "98db8c1b-b2f6-4ee1-92d9-cd7821ce29f8",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "PROCESSING",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:12.219815Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "Example Company Ltda",
"taxId": "00000000000100",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "0000000000000000",
"accountType": "payment",
"endToEndId": "e00000000202509161232XXXXXXXXXXX"
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": ""
}
},
"type": "DELIVERY-PROCESSING"
},
"createdAt": "2025-09-16T12:32:26.829798Z",
"EventType": ""
}
}
DEPOSIT-SUCCESS
{
"event": {
"id": "b4d05f88-09a0-488c-8360-5c42c11d3a52",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "PROCESSING",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:12.219815Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "Example Company Ltda",
"taxId": "00000000000100",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "0000000000000000",
"accountType": "payment",
"endToEndId": "e00000000202509161232XXXXXXXXXXX"
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": ""
}
},
"type": "DEPOSIT-SUCCESS"
},
"createdAt": "2025-09-16T12:32:26.857476Z",
"EventType": ""
}
}
TICKET-ON-HOLD
{
"event": {
"id": "a3f1c2d4-7e8b-49a0-bd12-3c4e5f6a7b8c",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "ON-HOLD",
"reason": "Asset delivery temporarily held for compliance review.",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:27.012345Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "Example Company Ltda",
"taxId": "00000000000100",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "0000000000000000",
"accountType": "payment",
"endToEndId": "e00000000202509161232XXXXXXXXXXX"
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": ""
}
},
"type": "TICKET-ON-HOLD"
},
"createdAt": "2025-09-16T12:32:27.012345Z",
"EventType": ""
}
}
DELIVERY-SUCCESS
{
"event": {
"id": "546dce9b-98ea-447b-9136-d1265cb36d81",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "PAID",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:12.219815Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "Example Company Ltda",
"taxId": "00000000000100",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "0000000000000000",
"accountType": "payment",
"endToEndId": "e00000000202509161232XXXXXXXXXXX"
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": "0x0000000000000000000000000000000000000000000000000000000000000007"
}
},
"type": "DELIVERY-SUCCESS"
},
"createdAt": "2025-09-16T12:32:35.762643Z",
"EventType": ""
}
}
TICKET-PURPOSE-CODE-REQUIRED
Sent once, after a credited international deposit with no purpose code for its deposit leg (quote.inputPurposeCode): always for a deposit in a currency other than BRL, and for an on-chain deposit unless its sender wallet is known to be in Brazil or is one of your own wallets. An on-chain deposit whose sender wallet has a standing purpose code for its band takes that code instead, with no webhook. List the deposits still waiting with GET /v2/account/tickets/?missingPurposeCode=true. The ticket is not paused. The ticket's quote carries purposeCodeBand (the table to take the code from) and usdAmount. State the code as inputPurposeCode with PATCH /v2/account/tickets/{ticket-id}/purpose-code (add ?subAccountId= when accountId is a sub-account). See Deposits.
{
"event": {
"id": "7c2e9a41-3b5d-4f8e-a6c1-9d0b2e4f6a8c",
"accountId": "94fdb114-189f-46d2-bce8-6ee6ba461d18",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "fbe2f6a3-6604-4b12-aae5-9f2994aaa3c1",
"userId": "94fdb114-189f-46d2-bce8-6ee6ba461d18",
"status": "PAID",
"reason": "",
"failureReason": "",
"createdAt": "2026-10-30T12:32:12.219815Z",
"updatedAt": "2026-10-30T12:32:40.012345Z",
"expiresAt": "2026-10-31T12:32:12.208933Z",
"quote": {
"inputCurrency": "USDC",
"inputPaymentMethod": "POLYGON",
"inputAmount": "1500",
"outputCurrency": "USDC",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "1500",
"purposeCodeBand": "UP_TO_50K",
"usdAmount": "1500",
"createdAt": "2026-10-30T12:32:11Z"
},
"blockchainSenderInfo": {
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"txHash": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0",
"disposableDepositAddress": ""
}
},
"type": "TICKET-PURPOSE-CODE-REQUIRED"
},
"createdAt": "2026-10-30T12:32:40.012345Z"
}
}
TICKET-COMPLETE
{
"event": {
"id": "ee9a907f-3fdc-4521-9d61-28f6c6a859b5",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "TICKET",
"data": {
"ticket": {
"id": "c4bd34dd-cbb2-4cda-b158-f104dd67d0c8",
"externalId": "",
"workspaceId": "33333333-3333-3333-3333-333333333333",
"userId": "44444444-4444-4444-4444-444444444444",
"status": "PAID",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-09-16T12:32:12.219815Z",
"updatedAt": "2025-09-16T12:32:12.219815Z",
"expiresAt": "2025-09-17T12:32:12.208933Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "10.2",
"outputCurrency": "BRLA",
"outputPaymentMethod": "INTERNAL",
"outputAmount": "10",
"markupCurrency": "",
"markupAmount": "0",
"sendMethod": "PERMIT",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "1",
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL",
"rebatable": false
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL",
"rebatable": true
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0",
"currency": "BRL",
"rebatable": true
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0",
"currency": "BRL",
"rebatable": false
}
],
"pairName": "BRLBRLA",
"outputBrCode": "",
"createdAt": "2025-09-16T12:32:11Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "uOUAP45Mg7PrhVg50DURHjX6f",
"additionalData": "BRLA Ticket Payment",
"name": "Example Company Ltda",
"taxId": "00000000000100",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "0000000000000000",
"accountType": "payment",
"endToEndId": "e00000000202509161232XXXXXXXXXXX"
},
"blockchainReceiverInfo": {
"walletAddress": "0x0000000000000000000000000000000000000003",
"walletChain": "INTERNAL",
"walletMemo": "",
"txHash": "0x0000000000000000000000000000000000000000000000000000000000000007"
}
},
"type": "TICKET-COMPLETE"
},
"createdAt": "2025-09-16T12:32:35.776372Z",
"EventType": ""
}
}
Check the detailed breakdown of the fields that make up a ticket
KYC
The KYC Event reflects updates related to a Know Your Customer verification attempt within your account. These events track the entire lifecycle of a KYC verification process, from submission to completion.
During the KYC verification process, you'll receive multiple status updates reflecting the current state of the verification attempt.
KYC Event Types
| Type Name | Description |
|---|---|
| KYC-STARTED | Indicates that the KYC process has been initiated. |
| KYC-PROCESSING | Indicates that the KYC information is being processed. |
| KYC-COMPLETED | Indicates that the KYC process has been completed. |
| KYC-EXPIRED | Indicates that the KYC process has been expired. |
KYC Status
| Status Name | Description |
|---|---|
| PENDING | The KYC verification is pending and awaiting processing. |
| PROCESSING | The KYC verification is currently being processed. |
| COMPLETED | The KYC verification has been completed (with either APPROVED or REJECTED result). |
| EXPIRED | The KYC verification has expired without being completed. |
KYC Result
| Result Name | Description |
|---|---|
| APPROVED | The KYC verification was successfully approved. |
| REJECTED | The KYC verification was rejected. A resultMessage field will provide details about the reason for rejection. |
Understanding the Data Returned in a KYC Webhook
KYC Events follow a standardized structure, where:
{
"event": {
"id": "unique-event-id",
"accountId": "account-identifier",
"subscription": "KYC",
"data": {
"attempt": {
"id": "kyc-attempt-id",
"userId": "user-identifier",
"levelName": "level-1",
"submissionData": {
// Personal information submitted for verification
},
"status": "COMPLETED",
"result": "APPROVED",
"resultMessage": "",
"rejectionLabels": [],
"retryable": false,
"createdAt": "timestamp",
"updatedAt": "timestamp"
},
"type": "KYC-COMPLETED"
},
"createdAt": "timestamp",
"EventType": ""
}
}
KYC Webhook Fields
| Field | Description |
|---|---|
id | Unique identifier for the webhook event. |
accountId | The identifier of the account associated with this KYC attempt. |
subscription | Always "KYC" for KYC events. |
data.attempt.id | Unique identifier for the specific KYC attempt. |
data.attempt.userId | The identifier of the user making the KYC attempt. |
data.attempt.levelName | The KYC level being attempted (e.g., "level-1"). |
data.attempt.submissionData | Contains all personal information submitted for verification. |
data.attempt.status | Current status of the KYC attempt (PENDING, PROCESSING, COMPLETED, EXPIRED). |
data.attempt.result | Result of the KYC verification (APPROVED or REJECTED) when completed. |
data.attempt.resultMessage | Provides details about rejection reasons if the result is REJECTED. |
data.attempt.rejectionLabels | Array of machine-readable labels categorizing rejection reasons. See Rejection Labels. |
data.attempt.retryable | Boolean indicating if another KYC attempt can be made. |
data.type | The type of KYC event (KYC-STARTED, KYC-PROCESSING, KYC-COMPLETED). |
When a KYC verification is rejected, the resultMessage field will contain information about why the verification failed, such as "birthdate does not match".
The retryable field indicates whether a new KYC attempt can be made. If true, the user can submit another KYC verification with corrected information.
LIMIT-UPDATE
The LIMIT-UPDATE Event notifies you when there are changes to your account's operational limits. These events are triggered whenever your account limits are updated, either due to KYC level changes, administrative actions, or other account-related events.
Understanding the Data Returned in a LIMIT-UPDATE Webhook
LIMIT-UPDATE Events follow a standardized structure, where:
{
"event": {
"id": "unique-event-id",
"accountId": "account-identifier",
"subscription": "LIMIT-UPDATE",
"data": {
"limitInfo": {
"blocked": false,
"createdAt": "timestamp",
"limits": [
{
"currency": "*",
"maxFiatIn": "100000",
"maxFiatOut": "100000",
"maxChainIn": "100000",
"maxChainOut": "100000",
"usedLimit": {
"year": 0,
"month": 0,
"usedFiatIn": "0",
"usedFiatOut": "0",
"usedChainIn": "0",
"usedChainOut": "0"
}
},
{
"currency": "BRL",
"maxFiatIn": "600000",
"maxFiatOut": "600000",
"maxChainIn": "600000",
"maxChainOut": "600000",
"usedLimit": {
"year": 0,
"month": 0,
"usedFiatIn": "0",
"usedFiatOut": "0",
"usedChainIn": "0",
"usedChainOut": "0"
}
}
// Additional currencies...
]
},
"type": "LIMIT-UPDATE"
},
"createdAt": "timestamp",
"EventType": ""
}
}
LIMIT-UPDATE Webhook Fields
| Field | Description |
|---|---|
id | Unique identifier for the webhook event. |
accountId | The identifier of the account whose limits were updated. |
subscription | Always "LIMIT-UPDATE" for limit update events. |
data.limitInfo.blocked | Boolean indicating if the account is blocked from operations. |
data.limitInfo.createdAt | Timestamp when the limit information was generated. |
data.limitInfo.limits | Array of objects containing limit details for different currencies. |
data.type | Always "LIMIT-UPDATE" for this event type. |
Each object in the limits array contains:
| Field | Description |
|---|---|
currency | The currency code. A value of "*" represents the global limit in USD. |
maxFiatIn | The maximum monthly limit for fiat deposits. |
maxFiatOut | The maximum monthly limit for fiat withdrawals. |
maxChainIn | The maximum monthly limit for on-chain deposits. |
maxChainOut | The maximum monthly limit for on-chain withdrawals. |
usedLimit | Object containing details about consumed limits for the current month. |
The LIMIT-UPDATE event is typically triggered after a successful KYC verification or when an administrator modifies your account limits.
WALLET-QUALIFICATION
The WALLET-QUALIFICATION-REQUIRED event notifies you that you received a crypto deposit from a deposit sender wallet that is still PENDING. It's sent for every deposit from that wallet until you qualify it with Qualify Deposit Sender Wallet. Wallets that are already QUALIFIED never trigger it.
Understanding the Data Returned in a WALLET-QUALIFICATION Webhook
{
"event": {
"id": "unique-event-id",
"accountId": "account-identifier",
"subscription": "WALLET-QUALIFICATION",
"data": {
"type": "WALLET-QUALIFICATION-REQUIRED",
"depositSenderWallet": {
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chainFamily": "EVM",
"isSelfCustody": null,
"custodianName": "",
"counterpartyName": "",
"counterpartyCountry": "",
"isSameEconomicGroup": null,
"qualificationStatus": "PENDING",
"standingPurposeCodes": {
"UP_TO_50K": "",
"ABOVE_50K": ""
},
"acamGroup": null,
"lastDepositAt": "timestamp",
"createdAt": "timestamp"
},
"deposit": {
"ticketId": "00000000-0000-0000-0000-000000000000",
"txHash": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"chain": "POLYGON",
"asset": "BRLA",
"amount": "10"
}
},
"createdAt": "timestamp"
}
}
WALLET-QUALIFICATION Webhook Fields
| Field | Description |
|---|---|
id | Unique identifier for the webhook event. A retry of the same deposit keeps the same id, so you can use it to deduplicate. |
accountId | The account that received the deposit. |
subscription | Always "WALLET-QUALIFICATION" for these events. |
data.type | Always "WALLET-QUALIFICATION-REQUIRED". |
data.depositSenderWallet | The sending wallet, in the same format as Get all Deposit Sender Wallets. Use its id to qualify it. |
data.deposit.ticketId | The deposit's ticket. null when the deposit is an internal transfer from another Avenia account, or a held deposit that has no ticket yet. |
data.deposit.txHash | Transaction hash of the deposit. |
data.deposit.chain | The chain the deposit arrived on, such as POLYGON, TRON or INTERNAL. |
data.deposit.asset | Token received. |
data.deposit.amount | Amount received, as a decimal string. |
chainFamily is EVM, TRON or INTERNAL. An internal transfer from another Avenia account comes as chainFamily: "INTERNAL" with deposit.chain: "INTERNAL", and deposit.ticketId is null because the ticket belongs to the payer. For a held deposit, deposit.ticketId is also null, and the event is sent once, when the deposit is held, not again when it is credited.
DEPOSIT-HOLD
No deposit is held through November 14, 2026. Deposits are held starting November 15, 2026. See Crypto Deposit Holds.
The DEPOSIT-HOLD Event asks you for the purpose code of an on-chain deposit held before it is credited: DEPOSIT-PURPOSE-CODE-REQUIRED. It is sent when the deposit is held and again every 24 hours until its code is stated. It is not sent for a deposit released right away by its sender wallet's standing purpose code for the deposit's band. The event carries no band, since the band follows the crypto's price: list the holds with GET /v2/account/deposit-holds to get it. To release the deposit:
- sender in Brazil: qualify the sender wallet with
counterpartyCountryBR. No code is needed; - sender abroad: state the code with
PATCH /v2/account/deposit-holds/{hold-id}/purpose-codeand qualify the sender wallet with its country, in either order. Or, for a wallet that sends you many deposits, give it standing purpose codes once, one for each band.
{
"event": {
"id": "unique-event-id",
"accountId": "account-identifier",
"subscription": "DEPOSIT-HOLD",
"data": {
"depositHold": {
"id": "5b0e3c1a-8f2d-4e6b-9a7c-1d2e3f4a5b6c",
"token": "USDT",
"chain": "TRON",
"amount": "62000",
"txHash": "9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0",
"senderWalletAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "AWAITING_PURPOSE_CODE",
"createdAt": "timestamp"
},
"type": "DEPOSIT-PURPOSE-CODE-REQUIRED"
},
"createdAt": "timestamp"
}
}
KYT-STATE
The KYT-STATE Event notifies you when our compliance team changes the transaction status of one of your users. It is sent when a user is temporarily held, placed under review, permanently rejected, or released again. While a user is held, under review or rejected, that user's transactions are paused for compliance review or refunded to the sender; the webhook lets you inform your end user before they try.
To receive these events, register your webhook with the KYT-STATE subscription, or with *.
For companies, a restriction may apply only to transactions between your user and one specific counterparty. In that case the event carries the counterpartyKey and the restriction does not affect the user's other transactions.
KYT-STATE Status
| Status | Description |
|---|---|
| TEMPORARY_HOLD | Transactions are held until expiresAt. The hold lifts by itself at that time; no release event is sent. |
| UNDER_REVIEW | Transactions are held until our compliance team decides. A release event follows the decision. |
| REJECTED | Transactions are refused permanently. A release event is only sent if compliance reverses the decision. |
| ACTIVE | The restriction was lifted by our compliance team. Transactions are allowed again. |
A state is announced when the user enters it. A TEMPORARY_HOLD is also announced again each time it is extended: you receive a new event with state and previousState both TEMPORARY_HOLD and a later expiresAt. Always keep the latest expiresAt you received.
Understanding the Data Returned in a KYT-STATE Webhook
{
"event": {
"id": "6d1f0b1e-3c2a-4a7e-9f0b-2a1c3d4e5f60",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "KYT-STATE",
"data": {
"type": "KYT-STATE-CHANGED",
"kytState": {
"userId": "44444444-4444-4444-4444-444444444444",
"state": "TEMPORARY_HOLD",
"previousState": "ACTIVE",
"expiresAt": "2026-10-04T12:00:00Z",
"message": "User temporarily held for compliance review until 2026-10-04T12:00:00Z. Transactions will be refused until then. Send an email to compliance@avenia.io and respond to the RFI (request for information).",
"updatedAt": "2026-10-02T12:00:00Z"
}
}
}
}
A release of a counterparty-scoped restriction looks like this:
{
"event": {
"id": "0b7c9e2a-5d41-4f8e-8a3b-9c1d2e3f4a5b",
"accountId": "44444444-4444-4444-4444-444444444444",
"subscription": "KYT-STATE",
"data": {
"type": "KYT-STATE-CHANGED",
"kytState": {
"userId": "44444444-4444-4444-4444-444444444444",
"counterpartyKey": "52998224725",
"state": "ACTIVE",
"previousState": "UNDER_REVIEW",
"message": "Transactions between this user and counterparty 52998224725 were released by compliance and are allowed again.",
"updatedAt": "2026-10-03T09:30:00Z"
}
}
}
}