Saved Cards
With the customer's agreement, the card of a payment can be kept for two later uses:
- A charge without the cardholder: a subscription, or a charge at a time you choose.
- The cardholder paying again with it, under 3D Secure: on the hosted page, or through server-to-server.
A purchase the customer makes in front of you is never a charge without the cardholder: it always goes through 3D Secure.
Avenia never returns a card number or a security code. A saved card is described by its brand, last four digits and expiry.
Charging a saved card without the cardholder needs the network transaction id that the card network returns on the first payment, and the sandbox's test acquirer does not return one. In sandbox every saved card lists with chargeable: false and unchargeableReason: "NO_NETWORK_TRANSACTION_ID", and the charge answers 409. Everything else works and is worth testing: saving (with 3D Secure), savedCardId, listing, revoking, paying a saved card with the cardholder present and the refusals of the charge. A successful charge without the cardholder can only be tested in production.
In sandbox, charging saved cards without the cardholder is enabled for your account up to R$ 5,000.00 per charge, 60 charges per hour and 500 per day. In production it is enabled per account on request: tell Avenia the largest amount you expect to charge at once. An account without it gets 409 charges of saved cards are not enabled for this account. Paying a saved card with the cardholder present does not depend on it.
Saving the card on a payment
On a server-to-server payment, add saveCard:
"saveCard": { "customerReference": "customer-8812", "cardholderConsented": true }
customerReferenceis your own id for the customer, at most 128 characters. You use it to list the customer's cards later. Use an internal id, not an email or a tax id.cardholderConsentedmust betrue. By sending it you declare that the cardholder agreed, on your checkout, to have the card kept for future charges by your store, and that you keep a record of that agreement. Show an unticked checkbox with the terms (what will be charged, when, and how to remove the card), and sendsaveCardonly when it is ticked.saveCardsits outsidecard.encrypted, so it is part of the signed body.- A payment that saves a card always goes through 3D Secure, whatever the issuer would ask otherwise. Expect
PENDING_3DSand aredirectUrl. - If that payment does not go through (declined, abandoned challenge), the card is not kept: it shows as
REVOKEDand cannot be charged.
Offering to save the card (hosted page)
On a checkout session, add saveCard with only the customer reference:
"saveCard": { "customerReference": "customer-8812" }
The page shows an unticked checkbox: "Save this card so this store can charge it for future payments. You can ask the store to remove it at any time." The card is saved only if the customer ticks it. A payment that saves a card always goes through 3D Secure.
Learning the saved card's id
The payment answer and every payment webhook carry savedCardId: the id of the card that payment saved, or "" when it saved none. You can also list the customer's cards.
List a customer's cards
Endpoint
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
customerReference | string | Yes | Your id for the customer. |
subAccountId | string | No | List a sub-account's customers. |
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/acquiring/saved-cards?customerReference=customer-8812" \
-H "Authorization: Bearer <token>"
Response
Newest first, at most 100 cards. An unknown customerReference returns an empty list.
{
"cards": [
{
"id": "7c1e0f52-3b9a-4d6e-8f21-0a4b5c6d7e8f",
"customerReference": "customer-8812",
"status": "ACTIVE",
"originPaymentId": "e4b8d1a2-6c3f-4a9e-b7d5-1f2e3a4b5c6d",
"cardBrand": "VISA",
"cardLast4": "0002",
"expirationMonth": 12,
"expirationYear": 2030,
"consentSource": "USER_API",
"createdAt": "2026-10-15T15:02:11Z",
"revokedAt": "",
"chargeable": true,
"unchargeableReason": ""
}
]
}
| Field | Meaning |
|---|---|
status | ACTIVE or REVOKED. |
originPaymentId | The payment that saved the card. |
consentSource | USER_API when the card was saved on a payment of this API, HOSTED_PAGE when the cardholder saved it on the hosted page. |
cardBrand, cardLast4 | Empty while that payment is still in 3D Secure. |
chargeable | Whether the charge can use it now. |
unchargeableReason | When chargeable is false: REVOKED; ORIGIN_NOT_CAPTURED (the payment that saved it is not captured yet); or NO_NETWORK_TRANSACTION_ID (the card network did not return what a later charge needs, so this card can only be charged with the cardholder present). |
Charging a saved card without the cardholder
Use this route only when the cardholder is not there: a subscription renewal, or a charge at a time you agreed with them.
Endpoint
Sent to the API base URL with your usual key. The body has no card, so it does not go through the relay, and it needs no 3D Secure and no device block.
Parameters
Body: required
| Field | Type | Description |
|---|---|---|
quoteToken | string | The quoteToken of a card sale quote, as on a checkout session: the charge's amount is the quote's inputAmount (at most your account's ceiling for charges of saved cards), it is paid in the quote's output currency, and one token opens one charge: it is the idempotency key of the call, and a new quote is needed for each charge. There is no amount field. A quote lasts 5 minutes: quote right before you charge. |
currency | string | BRL. |
country | string | BR. |
reason | string | SUBSCRIPTION (charges at intervals the customer agreed to) or UNSCHEDULED (charges at times you decide, as agreed with the customer). |
payerEmail | string | A bare address. |
payerName | string | The customer's name, as on a payment. |
payerTaxId | string | The customer's CPF or CNPJ, digits only, as on a payment. |
Body: optional: externalId (your own reference, up to 68 characters, not unique, only stored and returned), and:
| Field | Type | Description |
|---|---|---|
beneficiaryWalletId | string | Where this charge is paid, exactly as on a payment: the id of one of your beneficiary wallets, on the chain of the output of the charge's quote. Required when that output is on a blockchain. When it is INTERNAL, leave it out: the charge is paid to your account's balance, and naming a wallet is refused. Refused with 400 InvalidFieldError: beneficiaryWalletId is invalid as on a payment. See settling a sale to a wallet. |
A charge through this route carries no 3D Secure. If the cardholder says they did not authorize it (a fraud chargeback), the chargeback stays with you: there is no shift of liability to the bank, and the chargeback becomes a debt of your account. Do not use this route for a purchase the cardholder is making in front of you.
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/acquiring/saved-cards/7c1e0f52-3b9a-4d6e-8f21-0a4b5c6d7e8f/charges" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"externalId": "subscription-8812-2026-11",
"quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XXXX.XXXX",
"currency": "BRL",
"country": "BR",
"reason": "SUBSCRIPTION",
"payerEmail": "customer@example.com",
"payerName": "Maria Silva",
"payerTaxId": "12345678901",
"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c"
}'
Response
201 (or 200 and the same payment, on a repeat of the same request with the same quoteToken, even after the quote expired, or one that differs only by externalId, which keeps the first request's; the same quoteToken with other terms, or one that already opened a checkout session, is 409, as on a payment):
{
"id": "1f0a5d3e-8b7c-4e21-9a40-6c5d4b3a2f10",
"status": "CAPTURED",
"subStatus": "",
"failureCode": "",
"quote": { "outputCurrency": "USDC", "rate": "5.4", "inputFee": "4.875", "...": "..." },
"receivables": [
{ "installmentNumber": 1, "expectedDate": "2026-11-09", "...": "..." }
],
"beneficiaryWalletId": "76971925-a1ca-423f-badf-0b3f2b03c51c",
"walletAddress": "0x4c7e2a91d3b05f68e1a2c4d6b8f0a3e5c7d9b1f2",
"walletChain": "POLYGON"
}
status, subStatus and failureCode take the values of a payment; quote and receivables are those of the payment answer (quote is the quote the charge was opened from), beneficiaryWalletId, walletAddress and walletChain are the wallet the charge is paid to, as on a payment (all "" when it is paid to your account's balance), and the usual payment webhooks follow. In the webhooks of a charge, savedCardId is "": that field names the card a payment saved, so match a charge to your records with externalId. A charge is refunded like any payment.
| HTTP | error | Meaning |
|---|---|---|
| 404 | NotFoundError: saved card not found | Wrong id, or the card belongs to another account or sub-account. |
| 409 | charges of saved cards are not enabled for this account | Ask Avenia to enable them. |
| 409 | the amount is above this account's ceiling for a charge of a saved card | Quote a smaller amount, or talk to Avenia. |
| 400, 409 | quoteToken errors and QUOTE_EXPIRED | As on a checkout session and a payment. |
| 409 | this saved card was revoked and can no longer be charged | Ask the customer for a card again. |
| 409 | the payment that saved this card has not been captured; the card can be charged once it is | Wait for the first payment's CAPTURED. |
| 409 | the payment that saved this card returned no network transaction id, so the card cannot be charged without the cardholder | Charge the card with the cardholder present. |
| 402 | the payment was refused | Refused by Avenia's risk rules. |
Revoke a saved card
The body is an empty JSON object, {}. Response 200:
{ "id": "7c1e0f52-3b9a-4d6e-8f21-0a4b5c6d7e8f", "status": "REVOKED", "revokedAt": "2026-10-20T09:00:00Z" }
Repeating it is safe and returns the same answer. Revoking stops future charges; it does not refund past ones. Revoke the card when the customer asks for it to be removed, as your consent text promises.
Paying a saved card with the cardholder present
When the cardholder is at your checkout and picks a card they saved, pay it with the same call as a new card (server-to-server payment), sending savedCard in place of card:
{
"externalId": "order-10112",
"quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XXXX.XXXX",
"currency": "BRL",
"country": "BR",
"language": "pt-BR",
"payerEmail": "customer@example.com",
"payerName": "Maria Silva",
"payerTaxId": "12345678901",
"successUrl": "https://shop.example.com/orders/10112/thanks",
"cancelUrl": "https://shop.example.com/orders/10112/payment-failed",
"savedCard": {
"savedCardId": "7c1e0f52-3b9a-4d6e-8f21-0a4b5c6d7e8f",
"customerReference": "customer-8812"
},
"device": {
"ipAddress": "203.0.113.10",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6 Safari/605.1.15",
"screenWidth": 1512,
"screenHeight": 982,
"language": "pt-BR",
"timeZoneOffsetMinutes": 180,
"colorDepth": 30
}
}
- No card travels, so there is nothing to encrypt and no security code. Send the call as any payment: to the relay URL with the payments key. The body has no
card.encrypted, so the signed part is the whole body in canonical form. savedCardIdis the id of the card.customerReferenceis your reference for the customer the card was saved under: by sending it you state that the cardholder at your checkout is that customer. Both are required.- The cardholder must be present. The
deviceblock,successUrlandcancelUrlare required as on any payment, with the cardholder's IP and user agent, never your server's. - It always goes through 3D Secure, whatever the issuer would ask otherwise. Expect
PENDING_3DSand aredirectUrl: redirect the cardholder's browser there and read the result from the webhook. Unlike a charge without the cardholder, the cardholder authenticates. - Send one card only.
cardtogether withsavedCard, orsaveCardbesidesavedCard, is refused with400 InvalidFieldError: card is invalidorsaveCard is invalid, the reason inextraInfo. - One answer for a card that cannot be paid. A card that is unknown, belongs to another account or another customer, was revoked, or was saved by a payment that never concluded is refused with
400 InvalidFieldError: savedCard.savedCardId is invalid, before anything is reserved. - The answer is the one of a normal payment, with
savedCardId""(this payment saved nothing).quoteToken,installments,beneficiaryWalletIdand the rest apply as on any payment, and the payment is refunded like any other.
Paying with a saved card on the page
When your customer is at checkout (signed in on your site or app), the hosted page can offer the cards they saved with you, so they pay without typing the card again. Add savedCards when you create the session:
"savedCards": { "customerReference": "customer-8812" }
customerReferenceis the id you used when the card was saved. Naming it is your statement that the person you send to this page is that customer: send it only for a customer signed in on your side, because the page shows that customer's cards to whoever opens the link.- With
saveCardin the same session, both must name the same customer; otherwise400 InvalidFieldError: savedCards.customerReference is invalid. savedCardsis for hosted checkout sessions only.- The page lists the cards the customer can use now (active, and saved by a payment that was captured), newest first and at most 20, by brand and last four digits, with "Use another card" below them. Choosing a saved card hides the card form.
- A payment with a saved card always goes through 3D Secure, whatever your account's 3D Secure setting: the card is kept without its security code, so the bank's authentication is what shows the cardholder is the one paying. If the authentication fails, the payment is declined.
- It is an ordinary payment of the session: the same webhooks and refunds. Its
savedCardIdis"". - A card that cannot be used any more (revoked after the page opened, for example) is refused before anything is charged, and the page asks the customer to choose another card.
- In sandbox this works end to end: it does not need the network transaction id.