Skip to main content

Quotes and Tickets

Basic Concepts​

What is a Quote​

A quote is the first step for any transaction. It calculates the price, fees, and validity before execution.

Flow:

  1. Request → Send transaction parameters
  2. Calculation → System calculates price, fees, and validity
  3. Response → Receive quoteToken to use in the ticket

What is a Ticket​

A ticket executes the transaction using the quoteToken obtained from the quote.

Flow:

  1. Creation → Use quoteToken + specific parameters
  2. Execution → System processes the transaction
  3. Monitoring → Track status until completion

Ticket Lifecycle​

tickets fluxogram

info

About TICKET-ON-HOLD (dotted path): An optional pause during deposit processing, triggered when our risk engine flags a ticket for compliance review before the deposit is settled. You'll receive a TICKET-ON-HOLD webhook and the reason field will read "Asset delivery temporarily held for compliance review.". The ticket then resolves in one of three ways:

  • Approved → moves to DEPOSIT-SUCCESS and proceeds to DELIVERY-PROCESSING normally.
  • Auto-approved (review window elapses) → same as approved.
  • Rejected → moves to DEPOSIT-FAILED when the deposit can be refunded to the sender (BRL/PIX) or when the input is an Avenia balance (INTERNAL), which is simply returned. Otherwise the ticket ends in PARTIAL-FAILED with DELIVERY-PROCESSING and DELIVERY-PARTIAL-FAILED webhooks, 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). See Ticket Lifecycle and Failures.

Deposit validation before credit​

Before crediting a BRL/PIX deposit, Avenia runs compliance and limit checks. If any check rejects the deposit, no output asset is credited. The ticket moves to FAILED, a DEPOSIT-FAILED webhook is sent, and Avenia starts an asynchronous refund of the full input amount to the originating account. The refund may still be processing after the failure webhook, so integrations should wait for the final ticket state or TICKET-COMPLETE before presenting the operation as fully settled.

Where the funds end up after each kind of failure: Ticket Lifecycle and Failures.

The ticket's failureCode identifies why the deposit was rejected. Branch on it, not on the text of failureReason, which is a human-readable explanation. Common codes at this step:

failureCodeMeaningExample failureReason
LIMIT_EXCEEDEDThe available BRL input limit was insufficient.user does not have enough limit
THIRD_PARTY_DEPOSITThe account's third-party pay-in policy rejected the sender.third party deposit is not allowed for this user
SENDER_BLOCKED_TAX_ID, SENDER_BLOCKED_BANK_INSTITUTIONThe sender can't pay this account.sender tax id is blocked
USER_BLOCKEDThe user is blocked.user is blocked, funds returned. Contact compliance@avenia.io
COMPLIANCE_REJECTED, COMPLIANCE_TEMPORARY_HOLD, COMPLIANCE_UNDER_REVIEWRejected by a compliance check.A compliance message
INTERNAL_ERRORThe checks could not be completed, so the deposit was returned.deposit could not be verified, funds returned

Every code is listed in Ticket Failure Codes. The ticket reason may initially be Refund in progress. and is updated to include the refund E2E ID when the return completes.

info

For operations on behalf of a sub-account, simply add the subAccountId parameter to both the quote and ticket. The values must be identical in both calls.

API Reference - Quotes​

Endpoint​

GET/v2/account/quote/fixed-rate

Parameters​

Required Parameters​

FieldTypeDescription
inputCurrencystringThe currency you are paying with
inputPaymentMethodstringThe payment method you are using
outputCurrencystringThe currency you want to receive
outputPaymentMethodstringThe method you want to receive funds
inputAmountdecimal (string)The amount you want to pay/deposit. Required if outputAmount is not provided.
outputAmountdecimal (string)The amount you want to receive. Required if inputAmount is not provided.
inputThirdPartyboolReserved field. Send false. See Third Party Fields.
outputThirdPartyboolReserved field. Send false. See Third Party Fields.
blockchainSendMethodstringDefines the blockchain transaction type. Can be TRANSFER or PERMIT. Required for blockchain inputs.

Optional Parameters​

FieldTypeDescription
markupFloatingFeedecimal (string)A percentage fee added on top of the transaction. Example: 0.01 for 1%.
markupInputFixedFeedecimal (string)A fixed fee applied to the input amount. Example: 10.00 in all input operations.
markupOutputFixedFeedecimal (string)A fixed fee applied to the output amount. Example: 5.00 in all output operations.
markupCurrencystringThe currency in which the markup fee will be charged. Example: BRLA, USDC or USDT.
subAccountIdstringThe sub-account ID to perform the operation on behalf of.
inputPurposeCodestringThe BCB purpose code of the deposit leg, when it is international: crypto on a public chain (not INTERNAL), whoever sends it, or fiat in a currency other than BRL. Pick it from GET /v2/purpose-codes, in the table for the operation's USD value: UP_TO_50K up to USD 50,000, ABOVE_50K above. To learn the band first, quote without it and read purposeCodeBand. Sent for any other deposit leg, it returns 400 Bad Request, as does an unknown code or one from the other table. Optional through November 14, 2026; from November 15, 2026 a ticket without it is refused when its deposit leg is international. See International Transfers (ACAM).
outputPurposeCodestringThe BCB purpose code of the payout leg, when it is international: fiat in a currency other than BRL, or crypto on a public chain to a wallet not known to be in Brazil (none for a wallet in Brazil: the ticket drops it). From the same table as inputPurposeCode; sent for a payout leg that cannot be international (INTERNAL, BRL), it returns 400 Bad Request. Optional through November 14, 2026; from November 15, 2026 a ticket without it is refused when its payout leg is international.
warning

Either inputAmount or outputAmount must be provided, but not both at the same time.

Example​

cURL
# Regular quote
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "inputCurrency=BRL" \
--data-urlencode "inputPaymentMethod=PIX" \
--data-urlencode "inputAmount=100" \
--data-urlencode "outputCurrency=BRLA" \
--data-urlencode "outputPaymentMethod=POLYGON" \
--data-urlencode "inputThirdParty=false" \
--data-urlencode "outputThirdParty=false"

# Quote for sub-account
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "inputCurrency=BRL" \
--data-urlencode "inputPaymentMethod=PIX" \
--data-urlencode "inputAmount=100" \
--data-urlencode "outputCurrency=BRLA" \
--data-urlencode "outputPaymentMethod=POLYGON" \
--data-urlencode "inputThirdParty=false" \
--data-urlencode "outputThirdParty=false" \
--data-urlencode "subAccountId=YOUR_SUB_ACCOUNT_ID"

Response​

JSON
{
"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "100",
"outputCurrency": "BRLA",
"outputPaymentMethod": "POLYGON",
"outputAmount": "99.749583",
"markupAmount": "0",
"markupCurrency": "",
"inputThirdParty": false,
"outputThirdParty": false,
"appliedFees": [
{
"type": "Markup Fee",
"description": "Total markup fees represented in the input currency.",
"amount": "0",
"currency": "BRL"
},
{
"type": "In Fee",
"description": "Fees due to input currency and input payment method.",
"amount": "0.2",
"currency": "BRL"
},
{
"type": "Conversion Fee",
"description": "Fees due to conversion from input currency to output currency.",
"amount": "0",
"currency": "BRL"
},
{
"type": "Out Fee",
"description": "Fees due to output currency and output payment method.",
"amount": "0.05",
"currency": "BRL"
},
{
"type": "Gas Fee",
"description": "Fees due to blockchain transaction costs.",
"amount": "0.000417",
"currency": "BRL"
}
],
"basePrice": "1",
"pairName": "BRLBRLA",
"purposeCodeBand": "UP_TO_50K",
"usdAmount": "18.05"
}

A quote with a public chain (not INTERNAL) or fiat in a currency other than BRL on either side also returns purposeCodeBand (UP_TO_50K or ABOVE_50K) and usdAmount, the operation's value in USD that sets the band. The inputPurposeCode and outputPurposeCode you sent are returned as well. See International Transfers (ACAM).

Card sale quotes​

A quote with inputPaymentMethod=CARD prices a card sale: what you receive for an amount in BRL that a cardholder pays by card. It is priced like a PIX deposit into the same output, with your card MDR in place of the PIX fee:

PairinputCurrencyinputPaymentMethodoutputCurrencyoutputPaymentMethod
Card saleBRLCARDBRLA, USDC or USDTINTERNAL, or a blockchain that token is delivered on (see Available Combinations)
  • Fees. The MDR is the In Fee in appliedFees, with the minimum of your card price applied as on any quote's In Fee. Into USDC or USDT, the Conversion Fee is the one of a PIX deposit into the same currency, after-hours included. On a blockchain output, the Out Fee and Gas Fee are those of your account's pricing for that token and chain, as on a ticket. A markup is accepted as on any quote (markupFloatingFee, markupInputFixedFee, markupOutputFixedFee): it is the only markup on the sale, and it is paid to your workspace's main account.
  • Fees are paid on the sale. feeSettlement is always IMMEDIATE, whatever your account's default. Asking for EOM or FEE_ACCOUNT returns 400.
  • No rebate. A card sale pays none.
  • The quoteToken is valid for 5 minutes, not 15 seconds as for other quotes, since a cardholder pays it on a checkout page.
  • It opens one card sale. Send it as quoteToken on a checkout session, a server-to-server payment or a saved-card charge: the sale's amount is the quote's inputAmount, it is paid in the quote's output currency, and the sale lasts as long as the quote. A payment that starts after the quote expired is refused with QUOTE_EXPIRED.
  • It opens no ticket. Creating a ticket with a card quote's token is refused with 400 InvalidFieldError: quoteToken is invalid ("extraInfo": "a card quote opens no ticket").
  • A blockchain output needs a wallet on the sale. The sale then names one of your beneficiary wallets on that chain with beneficiaryWalletId; an INTERNAL output is paid to your account's balance and names none. See settling a sale to a wallet.
StatuserrorCause
400InvalidFieldError: outputCurrency-outputPaymentMethod is invalidThe output token is not delivered on that outputPaymentMethod.
400InvalidFieldError: outputCurrency is invalidAny output other than BRLA, USDC or USDT with CARD. extraInfo: a card sale buys BRLA, USDC or USDT.
400InvalidFieldError: feeSettlement is invalidfeeSettlement is EOM or FEE_ACCOUNT. extraInfo: a card sale pays its fees on the sale.
409card sales are not priced for this accountYour account has no card MDR. Contact your account manager.
409a card sale pays no rebate, and this account has one configuredYour account has a rebate, which card sales do not pay. Contact your account manager.

API Reference - Tickets​

Endpoint​

POST/v2/account/tickets/

Base Body​

FieldTypeRequiredDescription
quoteTokenstring✅The quote token received from the quote response. Each token creates at most one ticket — see Idempotency and safe retries.
externalIdstring❌A free-form reference (max 68 characters) for reconciliation in your system. It is not unique and not an idempotency key.

Additional Fields by Operation Type​

For PIX Input​

JSON
{
"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBrlPixInput": {
"additionalData": "optional PIX message"
}
}
FieldTypeRequiredDescription
additionalDatastring❌Additional information in the PIX transaction.

For Blockchain Input (PERMIT)​

JSON
{
"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBlockchainInput": {
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"permit": {
"r": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"s": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"v": 1,
"nonce": 1,
"deadline": 1234567890
}
}
}
FieldTypeRequiredDescription
walletAddressstring✅The wallet address that will be sending the tokens.
permit.rstring✅The r component of the permit signature.
permit.sstring✅The s component of the permit signature.
permit.vnumber✅The v component of the permit signature.
permit.noncenumber✅The nonce value for the permit signature.
permit.deadlinenumber✅The deadline timestamp for the permit signature.

For Blockchain Input (Personal Signature)​

JSON
{
"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBlockchainInput": {
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"personal": {
"signature": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"deadline": 1234567890
}
}
}
FieldTypeRequiredDescription
walletAddressstring✅The wallet address that will be sending the tokens.
personal.signaturestring✅The personal signature for the transaction.
personal.deadlinenumber✅The deadline timestamp for the signature.
info

If the wallet you specify is an Avenia Wallet, you do not need to include the PERMIT or TRANSFER fields.

For Blockchain Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBlockchainOutput": {
"beneficiaryWalletId": "00000000-0000-0000-0000-000000000000"
}
}
FieldTypeRequiredDescription
beneficiaryWalletIdstring✅Where the output goes. For a blockchain output, the id of a registered beneficiary wallet. For an INTERNAL output, 00000000-0000-0000-0000-000000000000 (your own balance) or the ID of another of your accounts. See beneficiaryWalletId by operation.

For Blockchain Output (Direct)​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBlockchainOutput": {
"walletChain": "POLYGON",
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletMemo": "",
"isSelfCustody": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "John Doe",
"counterpartyCountry": "US",
"isSameEconomicGroup": false
}
}
FieldTypeRequiredDescription
walletChainstring✅The blockchain network of the destination wallet (e.g., CELO, POLYGON, ETHEREUM).
walletAddressstring✅The public address of the destination wallet.
walletMemostring❌A memo or tag required by certain wallets or exchanges.
isSelfCustodybool❌Whether the counterparty holds the wallet's private keys.
custodianNamestring❌The institution that holds the keys, when not self-custody.
counterpartyNamestring❌The person or company that owns the destination wallet and receives the payout.
counterpartyCountrystring❌The custodian's country when not self-custody; for a self-custody wallet, the counterparty's country of residence (individual) or incorporation (company) (ISO 3166-1 alpha-2).
isSameEconomicGroupbool❌Outside Brazil: whether the counterparty is a company of your economic group.

The last five fields qualify the destination address with the same rules as a beneficiary wallet. Through November 14, 2026, a missing field leaves the destination PENDING; from November 15, 2026, it returns 400 Bad Request naming it. An invalid value always returns 400 Bad Request naming the field (e.g. ticketBlockchainOutput.counterpartyCountry). Send them only with a raw walletAddress on a public chain: with beneficiaryWalletId (qualify that wallet instead) or on an INTERNAL payout they return 400. See Payouts.

info

From November 15, 2026, an on-chain payout only goes to a QUALIFIED destination, in Brazil too: a payout to a PENDING beneficiary wallet returns 400 Bad Request (ticketBlockchainOutput).

An on-chain payout whose destination has counterpartyCountry BR (from the beneficiary wallet, or sent with a raw address) is domestic, and the ticket drops the quote's outputPurposeCode. Any other on-chain payout, including one whose country was not declared, is an international transfer and takes a quote with outputPurposeCode. This is optional through November 14, 2026; from November 15, 2026 such a payout without a code is refused with 400 Bad Request when the ticket is created. See Payouts.

A deposit on a public chain (TRANSFER or PERMIT) takes a quote with inputPurposeCode, whoever sends it: its sender is unknown until the crypto arrives. From November 15, 2026 such a ticket without it is refused with 400 Bad Request too. A ticket with both legs international, such as a USD deposit paid out on-chain abroad, takes both codes. See Deposits.

For PIX Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketBrlPixOutput": {
"beneficiaryBrlBankAccountId": "00000000-0000-0000-0000-000000000000",
"pixMessage": "optional PIX message"
}
}
FieldTypeRequiredDescription
beneficiaryBrlBankAccountIdstring✅The ID of the beneficiary account that this PIX belongs to.
pixMessagestring❌A message you want to be sent in the PIX.

For USD WIRE Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketUsdOutput": {
"beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
FieldTypeRequiredDescription
beneficiaryUsdBankAccountIdstring✅The ID of the beneficiary account that this WIRE transfer belongs to.

For USD ACH Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketUsdOutput": {
"beneficiaryUsdBankAccountId": "00000000-0000-0000-0000-000000000000",
"achReference": "optional ACH reference"
}
}
FieldTypeRequiredDescription
beneficiaryUsdBankAccountIdstring✅The ID of the beneficiary account that this ACH transfer belongs to.
achReferencestring❌A reference code you want to be sent with the ACH transfer.

For EUR SEPA Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketEurSepaOutput": {
"beneficiaryEurBankAccountId": "00000000-0000-0000-0000-000000000000",
"sepaReference": "optional SEPA reference"
}
}
FieldTypeRequiredDescription
beneficiaryEurBankAccountIdstring✅The ID of the beneficiary account that this SEPA transfer belongs to.
sepaReferencestring❌A reference you want to be sent with the SEPA transfer.

For COP Input (Bre-B)​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketCopInput": {
"additionalData": "optional reference shown on the transfer"
}
}
FieldTypeRequiredDescription
additionalDatastring❌Free-text reference carried with the Bre-B transfer. Max 256 characters. Bre-B only — it has no effect on PSE (BANK-TRANSFER) payins.

For COP Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketCopOutput": {
"beneficiaryCopBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
FieldTypeRequiredDescription
beneficiaryCopBankAccountIdstring⚠️The ID of the registered COP beneficiary that will receive the funds.
breBKeystring⚠️A Bre-B key to pay out to directly, without registering a beneficiary.
warning

Send exactly one of beneficiaryCopBankAccountId or breBKey. Sending both returns ticketCopOutput is invalid; sending neither leaves the payout with no destination.

For ARS Input​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketArsInput": {
"senderAccountNumber": "0000003100010000000001"
}
}
FieldTypeRequiredDescription
senderAccountNumberstring✅The end-user's own CVU or CBU — the account the ARS transfer will be sent from. Exactly 22 digits. The deposit only settles if it arrives from this account.

For ARS Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketArsOutput": {
"beneficiaryArsBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
FieldTypeRequiredDescription
beneficiaryArsBankAccountIdstring✅The ID of the registered ARS beneficiary (CVU or CBU) that will receive the funds.

For MXN Output​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketMxnOutput": {
"beneficiaryMxnBankAccountId": "00000000-0000-0000-0000-000000000000"
}
}
FieldTypeRequiredDescription
beneficiaryMxnBankAccountIdstring✅The ID of the registered MXN beneficiary (CLABE) that will receive the funds.
info

MXN payins take no input block. Unlike ARS, there is no sender account to declare — send only quoteToken (and optionally externalId) plus your blockchain output block.

For Markup​

JSON
{
"quoteToken": "eyJadXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id",
"ticketMarkupInput": {
"markupWalletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}
FieldTypeRequiredDescription
markupWalletAddressstring✅ (optional when the markup is locked to the main account)Your Avenia Wallet address to receive the markup.
warning

The markup must be sent to your Avenia Wallet, which belongs to your Business Account (BA) or sub-account if applicable. Avenia will automatically route the markup amount to this wallet.

Markup locked to the main account​

Accounts where operators create tickets on behalf of the business can ask Avenia to lock the markup to the main account. The lock covers the whole account: tickets of the main account and of every sub-account. Only Avenia turns it on or off; it cannot be changed through the API.

With the lock on, for every ticket whose quote carries a markup:

markupWalletAddressResult
omitted or emptyThe markup goes to the main account's Avenia Wallet.
an Avenia Wallet of the main accountAccepted.
any other wallet, including a sub-account'sRefused with HTTP 400.

The markup amount is unaffected: markupFloatingFee, markupInputFixedFee, markupOutputFixedFee and markupCurrency are still chosen on each quote.

A ticket that names another wallet is refused:

JSON
{
"error": "InvalidFieldError: ticketMarkupInput.markupWalletAddress is invalid",
"extraInfo": "markup is locked to the main account's wallet for this account"
}

On a locked account, simply omit ticketMarkupInput. The ticket's markupInfo.markupWalletAddress shows the wallet that received the markup.

API Reference - Tickets Management​

Get All Tickets​

This endpoint allows you to retrieve the entire history of created tickets.

Endpoint​

GET/v2/account/tickets/

Parameters​

ParameterTypeDescription
subAccountIdstringFilter by sub-account ID
createdAfterint64Unix epoch timestamp in milliseconds (UTC). Returns tickets whose creation time is on or after this instant (createdAt >= createdAfter). See the timestamp note below.
createdBeforeint64Unix epoch timestamp in milliseconds (UTC). Returns tickets whose creation time is strictly before this instant (createdAt < createdBefore). See the timestamp note below.
cursorstringUsed for pagination
statusstringFilter tickets by their current status (PENDING, PAID, etc.)
inputCurrencystringFilter by the input currency used in the ticket
outputCurrencystringFilter by the output currency received in the ticket
outputPaymentMethodstringFilter by the payment method used for the output
endToEndIdstringFilter by identifier assigned to each PIX transaction
externalIdstringFilter by the externalId you set on ticket creation (exact match). Because externalId is not unique, this can return zero, one or several tickets.
missingPurposeCodebooleantrue returns only the credited international deposits still waiting for their BCB purpose code: the tickets that PATCH /v2/account/tickets/{ticket-id}/purpose-code accepts. Works with subAccountId=*.
Time zones & timestamp formats

The createdAfter / createdBefore filters and the createdAt field returned in the response use different formats, and both are always expressed in UTC. This is the most common source of "why is this ticket outside my range?" confusion, so read this carefully.

  • Filter inputs (createdAfter, createdBefore) are Unix epoch timestamps in milliseconds, UTC — 13 digits for current dates (e.g. 1769990400000). They are not seconds (10 digits) and not date strings. If you have a value in seconds, multiply it by 1000.
  • The filter is applied to each ticket's own creation instant, with an inclusive lower bound (createdAt >= createdAfter) and an exclusive upper bound (createdAt < createdBefore).
  • The returned createdAt is an RFC3339 UTC timestamp string ending in Z (e.g. 2026-05-01T03:59:56.109Z).
  • Results are ordered newest first (by createdAt descending), so the tickets closest to your createdBefore boundary appear at the top of the first page.

Because everything is in UTC, a boundary you build from a local calendar date lands a few hours into the next UTC day when your zone is behind UTC. For example, for a client in Brazil (UTC−3), createdBefore=1777607999999 is 2026-05-01T03:59:59.999Z in UTC — which is the end of April 30 in Brazil local time. A ticket returned with createdAt=2026-05-01T03:59:56.109Z (epoch 1777607996109) is correctly in range, because its epoch is less than createdBefore, even though its UTC date string reads "May 1". Ordered newest-first, such tickets sit at the top of the page and can look out of range at a glance — but they are not.

Recommendations

  • Convert your local date/time boundaries to UTC before computing the millisecond epoch for createdAfter / createdBefore.
  • When checking whether a returned ticket falls in your range, compare its createdAt as epoch milliseconds (or convert it to your own time zone) rather than eyeballing the date portion of the UTC string.
  • Watch for the seconds-vs-milliseconds pitfall: a 10-digit epoch is seconds — multiply by 1000 to get the milliseconds this endpoint expects.

Example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-G \
--data-urlencode "subAccountId=YOUR_SUB_ACCOUNT_ID" \
--data-urlencode "status=PAID"

Response​

The response is an object with a tickets array and a pagination cursor. Each ticket carries the identifiers you can use to match Avenia records against your own: the top-level id (Avenia ticket ID), externalId (your reference, if you set one on ticket creation), and — for PIX operations — the endToEndId inside the relevant fiat sender/receiver block.

Each ticket only includes the sender/receiver blocks relevant to its operation type (e.g. a PIX-in → crypto-out ticket has brazilianFiatSenderInfo + blockchainReceiverInfo); irrelevant blocks are omitted.

JSON
{
"tickets": [
{
"id": "8f2c1e4a-9b3d-4c7e-a1f6-2d5b8c0e4a91",
"externalId": "your-reference-id",
"workspaceId": "b2d1f0c4-7a3e-4d2b-9c1f-0e8a6b4d2c10",
"userId": "a1c3e5f7-2b4d-6e8a-0c2e-4f6a8b0d2e40",
"status": "PAID",
"reason": "",
"failureReason": "",
"failureCode": "",
"createdAt": "2025-04-01T23:00:01.123456Z",
"updatedAt": "2025-04-01T23:01:34.335504Z",
"expiresAt": "2025-04-01T23:10:01.123456Z",
"quote": {
"inputCurrency": "BRL",
"inputPaymentMethod": "PIX",
"inputAmount": "1000",
"outputCurrency": "USDC",
"outputPaymentMethod": "POLYGON",
"outputAmount": "180.500000",
"markupCurrency": "USDC",
"markupAmount": "0",
"sendMethod": "PIX",
"inputThirdParty": false,
"outputThirdParty": false,
"basePrice": "5.540000",
"appliedFees": [
{
"type": "MARKUP",
"description": "Markup fee",
"amount": "0",
"currency": "USDC",
"rebatable": false
}
],
"pairName": "BRLUSDC",
"purposeCodeBand": "UP_TO_50K",
"usdAmount": "180.5",
"outputBrCode": "",
"ticketRefundId": "",
"createdAt": "2025-04-01T22:59:50.000000Z"
},
"brazilianFiatSenderInfo": {
"referenceLabel": "",
"additionalData": "",
"name": "John Doe",
"taxId": "12345678901",
"bankCode": "00000000",
"branchCode": "0001",
"accountNumber": "1234567",
"accountType": "CHECKING",
"pixMessage": "",
"endToEndId": "E000000002025040123010000000000001",
"brCode": ""
},
"blockchainReceiverInfo": {
"walletAddress": "0xAbC1234567890dEf1234567890AbCdEf12345678",
"walletChain": "POLYGON",
"walletMemo": "",
"txHash": "0x9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a39281706f5e4d3c2b1a0",
"isSelfCustody": true,
"custodianName": "",
"counterpartyName": "John Doe",
"counterpartyCountry": "US",
"isSameEconomicGroup": false,
"qualificationStatus": "QUALIFIED"
}
}
],
"cursor": "MjgzLTE3NDM1MTU4MjA4MDY="
}

On an on-chain ticket, or one with fiat in a currency other than BRL on either side, quote also carries inputPurposeCode, outputPurposeCode, purposeCodeBand and usdAmount. On an on-chain ticket, blockchainReceiverInfo carries the destination's qualification as it stood when the ticket was created, with qualificationStatus (QUALIFIED or PENDING; empty on INTERNAL payouts).

When the response cursor is non-empty, pass it back as the cursor query param to fetch the next page; keep paging until tickets comes back empty.

Get Ticket by ID​

Retrieve a specific ticket by its unique identifier.

Endpoint​

GET/v2/account/tickets/{ticket-id}

Parameters​

ParameterTypeDescription
ticket-idstringThe unique identifier of the ticket

Example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/tickets/TICKET-UUID-HERE" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

Returns the ticket wrapped in a ticket object — {"ticket": {...}} — with the same fields as each element of the tickets array in Get All Tickets. Read the status as ticket.status.

Create Ticket​

Create a new ticket using a quote token.

Endpoint​

POST/v2/account/tickets/

Body Parameters​

FieldTypeRequiredDescription
quoteTokenstring✅The quote token received from the quote response. Each token creates at most one ticket — see Idempotency and safe retries.
externalIdstring❌A free-form reference (max 68 characters) for reconciliation in your system. It is not unique and not an idempotency key.

Example​

cURL
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/tickets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"quoteToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"externalId": "your-reference-id"
}'

Idempotency and safe retries​

One quoteToken creates at most one ticket, and externalId is not an idempotency key. Within the token's 15 seconds a re-sent token returns cannot reuse quote token; after that it returns InvalidFieldError: quoteToken is invalid whether or not a ticket was created. To retry after a lost response, look the ticket up by externalId first — the full pattern is in Idempotency and Retries.

Cancel Ticket​

Cancel a ticket that is still awaiting payment — useful when a ticket was created by mistake or you changed your mind before sending the funds.

warning

Only tickets in the UNPAID state can be canceled. Once a ticket has moved to PROCESSING (or any later state), it can no longer be canceled.

Endpoint​

PATCH/v2/account/tickets/{ticket-id}/cancel

Parameters​

ParameterTypeDescription
ticket-idstringThe unique identifier of the ticket to cancel
subAccountIdstringOptional. Cancel a ticket that belongs to a sub-account

Example​

cURL
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/tickets/TICKET-UUID-HERE/cancel" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

On success the endpoint returns 200 OK with an empty body, and the ticket's state becomes CANCELED.

If the ticket does not exist, is already canceled, or is no longer UNPAID, the endpoint returns 400 Bad Request:

JSON
{
"error": "ticket not found, already canceled, or not eligible for cancellation"
}

Verifying Blocked Institutions​

Before creating a BRL ticket, you can check whether the counterparty bank is blocked for your account. Our risk engine maintains a deny-list of banks (by ISPB) that are blocked for pay-in and/or pay-out.

What happens when a blocked institution is involved depends on the direction:

DirectionOutcome
Pay-out to a blocked institutionThe delivery fails. The ticket ends in PARTIAL-FAILED with failureCode RECEIVER_BLOCKED_BANK_INSTITUTION, you get a DELIVERY-PARTIAL-FAILED webhook, and the amount is credited back to your Avenia balance (not sent back on-chain).
Pay-in from a blocked institutionThe deposit is refunded to the sender. The ticket ends FAILED with failureCode SENDER_BLOCKED_BANK_INSTITUTION, and you get a DEPOSIT-FAILED webhook.

Checking up front lets you fail fast and pick a different institution instead. You can rehearse the pay-out case in sandbox — see Magic Values.

Banks explicitly allowed for your account are left out of the list.

Endpoint​

GET/v2/account/bank-accounts/brl/blacklisted-ispbs

By default the scope is the authenticated account.

Parameters​

ParameterTypeDescription
subAccountIdstringOptional. Return the blocked ISPBs resolved for a sub-account instead of the main account

Example​

cURL
# Main account
curl "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/blacklisted-ispbs" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

# For a sub-account
curl "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/blacklisted-ispbs?subAccountId=SUB-ACCOUNT-UUID-HERE" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

200 OK with the blocked ISPBs, grouped by ispb with the operations each is blocked for:

JSON
{
"ispbs": [
{
"ispb": "12345678",
"bankName": "EXAMPLE BANK S.A.",
"blockedOperations": ["PAY-IN-COUNTERPARTY", "PAY-OUT-COUNTERPARTY"]
},
{
"ispb": "87654321",
"bankName": "ANOTHER BANK S.A.",
"blockedOperations": ["PAY-OUT-COUNTERPARTY"]
}
]
}
FieldTypeDescription
ispbstringThe 8-digit ISPB code identifying the bank
bankNamestringHuman-readable name of the bank (may be empty if the ISPB is unknown)
blockedOperationsstring[]The operations this bank is blocked for

blockedOperations values:

ValueMeaning
PAY-IN-COUNTERPARTYDeposits (pay-in) from this bank are blocked
PAY-OUT-COUNTERPARTYPayouts (pay-out) to this bank are blocked
ACCOUNT-BLOCKThe bank is fully blocked for the account, across operations

If no banks are blocked for your account, ispbs is an empty array.

Monitoring​

Webhook Events​

Tickets emit real-time events throughout their lifecycle:

  • TICKET-CREATED - The ticket has been successfully created
  • 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. The ticket will either move to DEPOSIT-SUCCESS (approved or auto-approved) or, if rejected, to DEPOSIT-FAILED (refundable or INTERNAL input) or PARTIAL-FAILED (amount credited to your Avenia balance, followed by DELIVERY-PARTIAL-FAILED)
  • DEPOSIT-SUCCESS - The deposit was completed successfully
  • DEPOSIT-FAILED - The deposit attempt has failed
  • 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, in the currency the operation had reached (see PARTIAL-FAILED in Ticket States)
  • TICKET-PURPOSE-CODE-REQUIRED - A notification, not a status: sent after an international deposit (on-chain or in a currency other than BRL) is credited, when it still needs its BCB purpose code. The ticket's status does not change and the event is sent one time. State the code with PATCH /v2/account/tickets/{ticket-id}/purpose-code
  • TICKET-COMPLETE - The entire ticket lifecycle has been completed, regardless of the outcome. Not sent when you cancel an UNPAID ticket yourself

Ticket States​

When you consult a ticket, the possible states are below. Where the funds end up after each kind of failure is in Ticket Lifecycle and Failures; why a ticket failed is in its failureCode, listed in Ticket Failure Codes.

  • UNPAID - The ticket has been created and is awaiting payment.
    Next step: Customer action required.

  • PROCESSING - Payment has been identified and is currently being processed.
    Next step: Avenia action required.

  • ON-HOLD - The ticket has been paused for compliance review during deposit processing, before the deposit is settled. The reason field will contain "Asset delivery temporarily held for compliance review.".
    Next step: Avenia compliance action required.

  • PAID - Funds have been successfully paid out.

    • BRL PIX payouts: the PIX was confirmed as settled at the beneficiary's institution — no further action is pending. See PIX payout outcomes.
    • Other payout methods: funds were delivered to the partner institution, which completes the transfer to the beneficiary.
  • FAILED - An error occurred and the transaction was not completed. The ticket's failureCode says why (see Ticket Failure Codes); failureReason has a human-readable explanation.

  • PARTIAL-FAILED - An error occurred during one stage of the transaction, resulting in partial completion. For example, in a PIX to USD transaction that results in the steps: PIX → USDC → USD. If the second step (USDC → USD) fails, the currency conversion will not be reversed, and the customer will retain the balance in USDC. A deposit rejected by compliance that cannot be refunded to the sender also ends here, with the amount credited to your Avenia balance (see Ticket Lifecycle and Failures); a rejected INTERNAL input is returned and ends in FAILED instead. The ticket's failureCode says why (see Ticket Failure Codes).

  • CANCELED - The ticket was canceled while still UNPAID (see Cancel Ticket). This is a final state; no payment is expected and no funds are moved.

PIX payout outcomes​

For BRL PIX payouts (outputPaymentMethod PIX or PIX-BRCODE), a ticket ends in one of these final states:

Final statusWhat happenedFunds
PAIDThe PIX was confirmed as settled at the beneficiary's institution.The beneficiary was paid.
PARTIAL-FAILEDThe PIX was refused or rejected after your balance was debited — for example, the destination account is invalid or closed, the receiving institution rejected it, the output limit was exceeded, or the beneficiary can't be paid. failureCode says why — for example RECEIVER_ACCOUNT_CLOSED, RECEIVER_BANK_REJECTED or LIMIT_EXCEEDED.The beneficiary was not paid; the amount is returned to your balance.
FAILEDThe ticket failed before the payout — for example, insufficient balance (INSUFFICIENT_BALANCE). With failureCode INTERNAL_ERROR, the input may already have been debited: contact support with the ticket id.No PIX was sent.
tip

TICKET-COMPLETE is sent for every final outcome, not only for successful payouts. Always read the ticket's status (and failureCode) in that webhook, or fetch the ticket, before marking the payout as done.

Reversals after a PIX was paid​

A PIX that was already settled can later be returned by the receiving institution. When that happens:

  • The original ticket stays PAID.
  • A new incoming ticket credits the returned amount back to your balance. Its externalId is the original ticket's ID, and its reason reads Pay out reversed by customer. Original ticket id: <original ticket id>.

Use the new ticket's externalId to link the reversal back to the original payout.

Insufficient balance​

When a ticket is paid from your Avenia balance (inputPaymentMethod=INTERNAL), the balance is not checked synchronously when you create the quote or the ticket. The ticket is created and the debit happens asynchronously. If the balance is short:

  • The ticket ends in FAILED with failureCode INSUFFICIENT_BALANCE (failureReason reads insufficient balance to complete this transaction).
  • You receive a DEPOSIT-FAILED webhook, followed by TICKET-COMPLETE with status FAILED.
  • Nothing is debited and no payout is sent.

To try again, top up the balance, request a new quote and create a new ticket. To avoid this failure, check your balance with GET /v2/account/balances before quoting.

Markup and Fees​

Markup allows you to add an extra fee on top of Avenia's standard pricing, giving you control over how much you charge your users for transactions.

Avenia's own fees are set in your contract and appear in the quote's appliedFees; whether they are deducted from the transaction or billed separately depends on your fee settlement mode. If you want to charge your own customers on top of that — for example an extra 1% — you can apply a markup.

warning

The markup must be sent to your Avenia Wallet, which belongs to your Business Account (BA) or sub-account if applicable. Avenia will automatically route the markup amount to this wallet. If your account has the markup locked to the main account, it always goes to the main account's wallet.

Markup Types​

1. Markup Floating Fee​

Set the percentage fee you want to charge on each transaction.

ParameterTypeDescriptionExample
markupFloatingFeedecimal (string)A percentage fee added on top of the transaction0.01 for 1%

Example:

cURL
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupFloatingFee=0.01"

2. Markup Input Fixed Fee​

Define a fixed fee applied at the moment of payment.

ParameterTypeDescriptionExample
markupInputFixedFeedecimal (string)A fixed fee applied to the input amount5.00 in input currency

Example:

cURL
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupInputFixedFee=5.00"

3. Markup Output Fixed Fee​

Define a fixed fee applied when receiving funds.

ParameterTypeDescriptionExample
markupOutputFixedFeedecimal (string)A fixed fee applied to the output amount2.00 in output currency

Example:

cURL
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupOutputFixedFee=2.00"

4. Markup Currency​

Choose the currency in which you want to receive the markup.

ParameterTypeDescriptionValid Values
markupCurrencystringThe currency in which the markup fee will be chargedBRLA, USDC, USDT

Examples:

cURL
# Receive markup in BRLA
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupCurrency=BRLA"

# Receive markup in USDC
curl "https://api.sandbox.avenia.io:10952/v2/account/quote/fixed-rate?inputCurrency=BRL&inputPaymentMethod=PIX&inputAmount=100&outputCurrency=BRLA&outputPaymentMethod=POLYGON&markupCurrency=USDC"

Blockchain Transaction Methods​

You will sign a transaction allowing Avenia to instantly pull the tokens from your wallet, ensuring a seamless and automatic transfer. Since the transaction is executed immediately, the final amount will not change.

Advantages:

  • ✅ Instant execution - No manual transfer required
  • ✅ Price protection - Amount locked during quote validity
  • ✅ Automatic processing - Avenia handles everything

When to use:

  • For automated operations
  • When you have signing capabilities
  • When price stability is important

TRANSFER​

You will need to proactively send the tokens to your Avenia Wallet. This means Avenia will lock in the value for a certain period of time, which may result in additional costs due to price fluctuations.

Advantages:

  • ✅ Simple implementation - No special signatures needed
  • ✅ No approval required - Just send tokens

Disadvantages:

  • ❌ Price fluctuation risk - Amount may change before execution
  • ❌ Manual process - Requires user action
  • ❌ Potential additional costs - Due to price movements

Choosing Between PERMIT and TRANSFER​

Use PERMIT when:

  • Building automated systems
  • Price certainty is critical
  • You can handle transaction signing

Use TRANSFER when:

  • Simple implementation is priority
  • Manual process is acceptable
  • You cannot handle signatures

Third Party Fields​

inputThirdParty and outputThirdParty are reserved fields. They are required in quote requests and are kept in the contract so that future changes in Brazilian PIX regulation can be supported without breaking changes.

  • Today, send false for both.
  • The value is not used to validate the destination: paying a third party's PIX key or bank account is not rejected because of this field.
  • We recommend keeping both values configurable on your side, so you can change them without a code release if the rules change.
info

The inputThirdParty quote flag does not bypass deposit screening. Avenia may still compare the actual PIX sender with the account holder and reject/refund the deposit when the account's third-party pay-in policy does not allow it.