Credit card

Tokenization, creation of the charge and handling of declines.

A credit card charge is made in two operations. The first converts the card data into a token. The second creates the charge with that token and returns, synchronously, the outcome of the authorization.

​

Tokenization

The POST /card-token operation receives the card data and returns a token. The token replaces the card data in the charge operation, which relieves the integrator of storing them.

curl -X POST https://api.fincle.com.br/card-token \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4111111111111111",
    "holderName": "HELENA M ANDRADE",
    "expirationMonth": "08",
    "expirationYear": "2029",
    "cvv": "123"
  }'

Field	Rule
number	Card number, 13 to 19 digits, validated by the Luhn algorithm.
holderName	Cardholder name, as printed on the card.
expirationMonth	Expiry month, 01 to 12.
expirationYear	Expiry year, with two or four digits.
cvv	Security code, with three or four digits.

The precautions relating to the processing of card data are set out in Security and data protection.

​

Creating the charge

The POST /card operation creates the charge. The card.installments field states the number of installments, from 1 to 12.

curl -X POST https://api.fincle.com.br/card \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c1f0b9e-3a52-4d6c-9e1b-5f2a8c4d7e10" \
  -d '{
    "amountInCents": 125000,
    "description": "Invoice no. 2026/001042",
    "card": { "cardToken": "tok_9f2c1a7b4d6e", "installments": 3 },
    "customer": {
      "name": "Helena Martins Andrade",
      "email": "[e-mail]",
      "documentType": "cpf",
      "document": "31845792041"
    }
  }'

​

Authorization outcome

The operation responds with status 200 for both authorized and declined charges. The outcome is given in the data.status field.

Status	Description
paid	Charge authorized.
pending	Processing in progress at the acquirer. The final outcome is communicated by notification.
refused	Charge declined.

{
  "success": true,
  "message": "Saldo insuficiente",
  "data": {
    "id": "cmddiqpxo09zf1yju2kqkhgga",
    "card": { "token": "tok_9f2c1a7b4d6e", "brand": "visa", "last4": "1111" },
    "status": "refused",
    "fees": 0,
    "refuseReason": "INSUFFICIENT_FUNDS",
    "acquirerCode": "51",
    "acquirerMessage": "Insufficient funds"
  }
}

​

Decline reasons

When a charge is declined, the refuseReason field states the normalized reason, and the acquirerCode and acquirerMessage fields reproduce the acquirer’s response.

refuseReason	Description	Recommended action
INSUFFICIENT_FUNDS	Insufficient balance or limit.	Offer another payment method.
CARD_BLOCKED	Card blocked by the issuer.	Advise the payer to contact the issuer.
INVALID_DATA	Incorrect card data.	Request verification of the data and a new tokenization.
EXPIRED_CARD	Card past its expiry date.	Request another card.
ANTIFRAUD_REJECTED	Transaction rejected in risk analysis.	Do not repeat the charge with the same data.
TIMEOUT	No response from the acquirer in time.	Repeat the request with the same idempotency key.
OTHER	Decline without a specific reason.	Offer another payment method.

​

Temporary block of the payer

Successive declined attempts result in the temporary block of the payer for card charges. In that case, the response is 429, with the code field equal to BUYER_ATTEMPTS_EXCEEDED.

{
  "success": false,
  "message": "Você atingiu o número máximo de tentativas de pagamento com cartão. Aguarde o fim do bloqueio para tentar novamente com cartão ou pague com Pix.",
  "code": "BUYER_ATTEMPTS_EXCEEDED",
  "blockedUntil": "2026-11-12T18:30:00.000Z",
  "retryAfterSeconds": 1800
}

Field	Description
blockedUntil	End of the block, in ISO 8601 (UTC). May be null when the time is not known.
retryAfterSeconds	Remaining time of the block, in seconds. Also reported in the retry-after header.

No amount is charged in that case. The block is restricted to the payer concerned and does not affect others, so that charges to other payers must not be suspended or delayed. Charging by Pix remains available for the blocked payer.

Status 429 is also used for the rate limit. The two cases must be distinguished by the code field, and not by the response status.

​

Idempotency

Sending the Idempotency-Key header in every charge is recommended. In the event of a network failure or a timeout, repeating the request with the same key returns the transaction already recorded, without a new authorization with the issuer.

​

Recurring billing

Recurring billing on card is performed through subscriptions, which use the same token issued by the tokenization operation.

​

Disputes

The cardholder may dispute the charge with the issuer. The dispute is governed by the rules of the payment scheme of the respective card brand and moves the transaction to the statuses described in Transaction lifecycle.