Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

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.

A charge without the cardholder cannot succeed in sandbox

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:

JSON
"saveCard": { "customerReference": "customer-8812", "cardholderConsented": true }
  • customerReference is 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.
  • cardholderConsented must be true. 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 send saveCard only when it is ticked.
  • saveCard sits outside card.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_3DS and a redirectUrl.
  • If that payment does not go through (declined, abandoned challenge), the card is not kept: it shows as REVOKED and cannot be charged.

Offering to save the card (hosted page)​

On a checkout session, add saveCard with only the customer reference:

JSON
"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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/saved-cards?customerReference={customerReference}

Parameters​

FieldTypeRequiredDescription
customerReferencestringYesYour id for the customer.
subAccountIdstringNoList a sub-account's customers.

Request example​

cURL
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.

JSON
{
"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": ""
}
]
}
FieldMeaning
statusACTIVE or REVOKED.
originPaymentIdThe payment that saved the card.
consentSourceUSER_API when the card was saved on a payment of this API, HOSTED_PAGE when the cardholder saved it on the hosted page.
cardBrand, cardLast4Empty while that payment is still in 3D Secure.
chargeableWhether the charge can use it now.
unchargeableReasonWhen 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​

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/saved-cards/{saved-card-id}/charges

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

FieldTypeDescription
quoteTokenstringThe 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.
currencystringBRL.
countrystringBR.
reasonstringSUBSCRIPTION (charges at intervals the customer agreed to) or UNSCHEDULED (charges at times you decide, as agreed with the customer).
payerEmailstringA bare address.
payerNamestringThe customer's name, as on a payment.
payerTaxIdstringThe 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:

FieldTypeDescription
beneficiaryWalletIdstringWhere 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.
The chargeback stays with you

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
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):

JSON
{
"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.

HTTPerrorMeaning
404NotFoundError: saved card not foundWrong id, or the card belongs to another account or sub-account.
409charges of saved cards are not enabled for this accountAsk Avenia to enable them.
409the amount is above this account's ceiling for a charge of a saved cardQuote a smaller amount, or talk to Avenia.
400, 409quoteToken errors and QUOTE_EXPIREDAs on a checkout session and a payment.
409this saved card was revoked and can no longer be chargedAsk the customer for a card again.
409the payment that saved this card has not been captured; the card can be charged once it isWait for the first payment's CAPTURED.
409the payment that saved this card returned no network transaction id, so the card cannot be charged without the cardholderCharge the card with the cardholder present.
402the payment was refusedRefused by Avenia's risk rules.

Revoke a saved card​

POSThttps://api.sandbox.avenia.io:10952/v2/account/acquiring/saved-cards/{saved-card-id}/revoke

The body is an empty JSON object, {}. Response 200:

JSON
{ "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:

JSON
{
"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.
  • savedCardId is the id of the card. customerReference is 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 device block, successUrl and cancelUrl are 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_3DS and a redirectUrl: 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. card together with savedCard, or saveCard beside savedCard, is refused with 400 InvalidFieldError: card is invalid or saveCard is invalid, the reason in extraInfo.
  • 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, beneficiaryWalletId and 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:

JSON
"savedCards": { "customerReference": "customer-8812" }
  • customerReference is 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 saveCard in the same session, both must name the same customer; otherwise 400 InvalidFieldError: savedCards.customerReference is invalid.
  • savedCards is 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 savedCardId is "".
  • 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.