Skip to main content

Refund a PIX Deposit

Use this when a payer sent you a PIX and the money has to go back to them: a duplicated payment, a cancelled order, a payer you don't want to serve. The refund returns the full amount of the original deposit by PIX to the account it came from.

Before you start​

  • You need the Avenia ticket ID of the deposit (id), not the PIX end-to-end ID. If you only have the end-to-end ID, find the ticket with Get All Tickets filtered by endToEndId.
  • The ticket must be one that received a PIX, and the refund must be requested within 88 days of the deposit.
  • The refund is debited from the account that received the deposit. For a sub-account's deposit, send that subAccountId on the quote and the ticket.
  • The account needs enough BRLA for the quote's inputAmount (see below).
  • The access behind your API key needs the payOut permission — see Accesses Management.
  • A deposit can be refunded once, in full. There are no partial refunds.

1. Quote​

Send the deposit ticket ID in ticketRefundId. Leave the amount out: the refund is always the full original deposit.

GET /v2/account/quote/fixed-rate?inputCurrency=BRLA&inputPaymentMethod=INTERNAL&outputCurrency=BRL&outputPaymentMethod=REFUND&blockchainSendMethod=PERMIT&inputThirdParty=false&outputThirdParty=false&ticketRefundId=DEPOSIT_TICKET_ID

For a R$50 deposit, the sandbox quote was:

{
  "quoteToken": "eyJ...",
  "inputCurrency": "BRLA",
  "inputPaymentMethod": "INTERNAL",
  "inputAmount": "50.5",
  "outputCurrency": "BRL",
  "outputPaymentMethod": "REFUND",
  "outputAmount": "50",
  "appliedFees": [
    { "type": "Markup Fee", "amount": "0", "currency": "BRLA" },
    { "type": "In Fee", "amount": "0", "currency": "BRLA" },
    { "type": "Conversion Fee", "amount": "0", "currency": "BRLA" },
    { "type": "Out Fee", "amount": "0.5", "currency": "BRLA" },
    { "type": "Gas Fee", "amount": "0", "currency": "BRLA" }
  ],
  "feeSettlement": "IMMEDIATE"
}
  • outputAmount is what the payer gets back: the full deposit.
  • inputAmount is what leaves your balance. The refund always uses the deposit's fee settlement mode:
    • IMMEDIATE (as here): the deposit plus the refund's own fees — a R$0.50 Out Fee in this example; yours depends on your contract.
    • EOM or FEE_ACCOUNT: the deposit only; the refund's fees are billed at month end or charged to your fee account, like any other operation.
  • The fees of the original deposit are not given back.
  • Leave feeSettlement out; asking for a mode other than the deposit's returns 400.
  • You may send outputAmount only if it equals the deposit amount. Any other outputAmount, or any inputAmount, returns 400.

2. Ticket​

ticketBlockchainOutput isn't needed: the money always goes back to the account the PIX came from, and you can't choose another destination. ticketBrlPixOutput.pixMessage is optional, and it may not reach the payer.

POST /v2/account/tickets/
{
  "quoteToken": "eyJ...",
  "ticketBrlPixOutput": {
    "pixMessage": "Refund of order 1234"
  }
}
{
  "id": "0f0a2e0a-b561-4c4f-a298-bd3dc1a7251b",
  "expiration": "2026-10-25T18:50:18.361487486Z"
}

3. Confirm​

Read the refund ticket, or wait for its TICKET-COMPLETE webhook:

  • PAID: the PIX went back to the payer.
  • PARTIAL-FAILED: the PIX couldn't be sent, and the BRLA is back in your balance. Read failureReason, which reads ticket failed partially: <reason> - tokens returned to user's wallet:
    • already refunded: this deposit was refunded before.
    • refund time limit exceeded: the 88 days ran out before the PIX went out.
    • Any other reason: contact Avenia with the refund ticket ID.
In sandbox

Sandbox doesn't send the return PIX, so a refund ticket ends PARTIAL-FAILED with ticket failed partially: internal error - tokens returned to user's wallet, and the balance is unchanged. Use sandbox to check your quote and ticket requests; the PAID outcome only happens in production.

Errors you may see​

ErrorCause
404 NotFoundError: ticketRefundId not foundNo ticket with that ID in this account, or its PIX isn't found among the deposits received. Check the ID and the subAccountId: a sub-account's deposit is refunded with that sub-account's subAccountId.
400 InvalidFieldError: ticketRefundId is invalidThe ID isn't a UUID, or the ticket didn't receive a PIX.
400 RefundWindowExpiredError: this pix can no longer be refunded because the refund time limit has been exceededMore than 88 days since the deposit.
400 InvalidFieldError: inputCurrency-inputPaymentMethod is invalidThe input isn't BRLA / INTERNAL.
400 InvalidFieldError: feeSettlement is invalidfeeSettlement differs from the deposit's. Leave it out.
400 InvalidFieldError: outputAmount is invalidoutputAmount differs from the deposit amount. Leave it out.
400 InvalidFieldError: inputAmount is invalidinputAmount sent. Leave it out.
400 InvalidFieldError: ticketBrlPixOutput.pixMessage is invalidpixMessage has characters other than letters, digits and spaces, or is longer than 100 characters.

The summary of this operation is in Refund Deposit Operations.