> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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](https://docs.fincle.com.br/guides/security.md).

## Creating the charge

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

```bash theme={null}
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": "helena.andrade@example.com",
      "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. |

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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](https://docs.fincle.com.br/guides/subscriptions.md), 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](https://docs.fincle.com.br/guides/transaction-lifecycle.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.