> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/guias/pedidos-e-cobrancas/cobrancas-com-cartao-salvo-stored-credential.md).

# Cobranças com cartão salvo (stored credential)

Quando você guarda o cartão do cliente para cobrar de novo depois, cada cobrança precisa dizer como esse cartão está sendo usado. É o objeto `storedCredential`, enviado em `payment` na [criação do pedido](https://docs.barte.com/api-reference/pedidos-e-cobrancas/criar-pedido.md).

A primeira cobrança acontece com o portador presente, que aceita o acordo de cobranças futuras. As cobranças seguintes dependem dela. A declaração diz às bandeiras como tratar cada cobrança, e uma declaração errada pode levar a recusas.

{% hint style="info" %}
As assinaturas criadas na Barte (`/v2/subscriptions`) não usam este campo: você não precisa declarar as renovações. Este guia vale para os pedidos que você cria com `POST /v2/orders`.
{% endhint %}

## Campos

| Campo       | Obrigatório | O que diz                                                                                                                                                           |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initiator` | sim         | Quem inicia a cobrança. `CARDHOLDER`: o portador está presente e autoriza a cobrança. `MERCHANT`: você cobra sem o portador presente, com base num acordo anterior. |
| `reason`    | sim         | O tipo da série: `RECURRING`, `INSTALLMENT`, `UNSCHEDULED` ou `CARD_ON_FILE`.                                                                                       |
| `usage`     | não         | Se a cobrança estabelece a série (`FIRST`) ou usa uma série já estabelecida (`USED`). Sem `usage`, a Barte deriva o uso pela combinação de `initiator` e `reason`.  |

Tipos de série (`reason`):

* `RECURRING`: periodicidade fixa, com valor fixo ou variável. Exemplo: mensalidade.
* `INSTALLMENT`: uma compra dividida em cobranças separadas, em datas combinadas, que você mesmo dispara.
* `UNSCHEDULED`: cobranças sem data ou valor fixos. Exemplo: recarga quando o saldo acaba.
* `CARD_ON_FILE`: compra com o cartão salvo e o portador presente. Exemplo: compra com um clique.
* `INITIAL`: valor anterior, mantido por compatibilidade. Com `CARDHOLDER`, equivale a `usage: FIRST` com `UNSCHEDULED`. Com `MERCHANT`, é tratado como cobrança seguinte (`usage: USED`); prefira declarar o tipo da série.

## O que declarar

| Situação                                                | `initiator`  | `reason`       | `usage` | `cvv` |
| ------------------------------------------------------- | ------------ | -------------- | ------- | ----- |
| Primeira cobrança periódica                             | `CARDHOLDER` | `RECURRING`    | `FIRST` | sim   |
| Cobranças periódicas seguintes                          | `MERCHANT`   | `RECURRING`    | `USED`  | não   |
| Primeira cobrança de um parcelamento feito por você     | `CARDHOLDER` | `INSTALLMENT`  | `FIRST` | sim   |
| Parcelas seguintes                                      | `MERCHANT`   | `INSTALLMENT`  | `USED`  | não   |
| Primeira cobrança sem data ou valor fixos               | `CARDHOLDER` | `UNSCHEDULED`  | `FIRST` | sim   |
| Cobranças seguintes sem data ou valor fixos             | `MERCHANT`   | `UNSCHEDULED`  | `USED`  | não   |
| Primeira compra que salva o cartão para compras futuras | `CARDHOLDER` | `UNSCHEDULED`  | `FIRST` | sim   |
| Compra com o cartão salvo e o portador presente         | `CARDHOLDER` | `CARD_ON_FILE` | `USED`  | sim   |

Regras:

* A primeira cobrança de uma série é sempre `CARDHOLDER` com `usage: FIRST`. Não declare `MERCHANT` na primeira cobrança.
* `USED` pressupõe uma cobrança `FIRST` anterior, aprovada, com o mesmo cartão.
* `CARD_ON_FILE` só é aceito com `CARDHOLDER` e sem `usage: FIRST`. Nas outras combinações a API retorna `400 BAR-0500`.
* `CARDHOLDER` com `usage: USED` equivale a `CARD_ON_FILE`: é uma compra com o cartão salvo e o portador presente.
* Na compra com o cartão salvo, envie o `cvv` e cobre à vista. Sem o `cvv` ou com `installments`, a compra pode ser processada como uma compra comum com o portador presente.
* Sem `usage`, `CARDHOLDER` com `INITIAL` é a primeira cobrança de uma série `UNSCHEDULED`, `CARDHOLDER` com `CARD_ON_FILE` é uma compra com o cartão salvo, e `MERCHANT` com um tipo de série ou com `INITIAL` é uma cobrança seguinte. `CARDHOLDER` com `RECURRING`, `INSTALLMENT` ou `UNSCHEDULED` sem `usage` não estabelece a série: declare `usage: FIRST`.
* A API não recusa `cvv` em cobrança `MERCHANT` nem `MERCHANT` na primeira cobrança; as regras acima são o que as bandeiras esperam.

Na resposta, o `storedCredential.usage` de cada cobrança traz a classificação da Barte:

* `MERCHANT`: sempre `USED`, mesmo com `usage: FIRST`.
* `CARDHOLDER`: `USED` com `usage: USED` ou com `CARD_ON_FILE`; `FIRST` com `usage: FIRST`, ou com `INITIAL` e sem `usage`. Nos outros casos o campo não vem.
* Cobranças seguintes de um pedido `CREDIT_CARD` parcelado: `USED` com `MERCHANT` ou quando a primeira estabeleceu a série. Nos outros casos o campo não vem.

O campo pode aparecer também em cobranças criadas antes de ele existir.

## Primeira cobrança

* O portador está presente e autoriza a cobrança.
* Antes dela, o portador aceita um acordo de cobranças futuras, exibido separado dos termos gerais, com: os últimos quatro dígitos do cartão, o valor ou a forma de calcular o valor, a periodicidade, a validade do acordo e como cancelar. Guarde a evidência do aceite pela duração do acordo.
* Envie o `cvv`.

## Cobranças seguintes

* Use o mesmo cartão (`card.cardToken`) e o mesmo tipo de série da primeira cobrança.
* Não envie o `cvv`.

## Parcelado

O efeito de `installments` depende do `method`:

* **`CREDIT_CARD_EARLY_SELLER` ou `CREDIT_CARD_EARLY_BUYER` com `installments`**: uma cobrança só, parcelada no cartão. Se enviar `storedCredential`, declare como qualquer compra com o portador presente (`CARDHOLDER`); se ela estabelece a série, use `usage: FIRST` e, sem tipo definido, `UNSCHEDULED`.
* **`CREDIT_CARD` com `installments`**: a Barte cria uma cobrança separada por parcela e dispara as cobranças seguintes. Não é preciso enviar `storedCredential`. Se enviar, use `CARDHOLDER`, `INSTALLMENT` e `usage: FIRST`.

`INSTALLMENT` com cobranças disparadas por você é outro caso: cada parcela é uma cobrança à vista, a primeira com `FIRST` e as seguintes com `USED`.

## Exemplos

Os exemplos mostram só os campos de `payment` ligados ao cartão salvo, no `POST /v2/orders`. Envie também o `fraudData` e os demais campos do pedido. O `cardToken` vem da [tokenização do cartão](https://docs.barte.com/api-reference/tokenizacao-de-cartao-one-buy-click/criar-token-do-cartao.md) e precisa ser do comprador do pedido.

**Primeira cobrança periódica**

```json
"payment": {
  "method": "CREDIT_CARD",
  "capture": true,
  "card": {
    "cardToken": "efde9a25-76f9-4d0a-bfbc-1abbdbd8bc07",
    "cvv": "123"
  },
  "storedCredential": {
    "initiator": "CARDHOLDER",
    "reason": "RECURRING",
    "usage": "FIRST"
  }
}
```

**Cobrança periódica seguinte**

```json
"payment": {
  "method": "CREDIT_CARD",
  "capture": true,
  "card": {
    "cardToken": "efde9a25-76f9-4d0a-bfbc-1abbdbd8bc07"
  },
  "storedCredential": {
    "initiator": "MERCHANT",
    "reason": "RECURRING",
    "usage": "USED"
  }
}
```

**Parcela seguinte de um parcelamento feito por você**

```json
"payment": {
  "method": "CREDIT_CARD",
  "capture": true,
  "card": {
    "cardToken": "efde9a25-76f9-4d0a-bfbc-1abbdbd8bc07"
  },
  "storedCredential": {
    "initiator": "MERCHANT",
    "reason": "INSTALLMENT",
    "usage": "USED"
  }
}
```

**Compra com o cartão salvo e o portador presente**

```json
"payment": {
  "method": "CREDIT_CARD",
  "capture": true,
  "card": {
    "cardToken": "efde9a25-76f9-4d0a-bfbc-1abbdbd8bc07",
    "cvv": "123"
  },
  "storedCredential": {
    "initiator": "CARDHOLDER",
    "reason": "CARD_ON_FILE",
    "usage": "USED"
  }
}
```

## Erros

| Código             | Quando                                                                              |
| ------------------ | ----------------------------------------------------------------------------------- |
| `400 PAYMENT-0500` | `initiator`, `reason` ou `usage` fora da lista, ou `initiator` ou `reason` ausente. |
| `400 PAYMENT-1304` | `cardToken` não encontrado.                                                         |
| `400 PAYMENT-1305` | `cardToken` de outro comprador.                                                     |
| `400 BAR-0500`     | `CARD_ON_FILE` com `MERCHANT` ou com `usage: FIRST`.                                |

Uma cobrança `MERCHANT` também pode ser recusada antes de chegar ao banco emissor:

| Código     | Quando                                                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BAR-7995` | A primeira cobrança deste cartão para o comprador foi recusada e nenhuma foi aprovada depois. Refaça a primeira cobrança com o cliente.                             |
| `BAR-7996` | O banco emissor recusou uma cobrança anterior deste cartão indicando que não aceita nova tentativa, e nenhuma foi aprovada depois. Refaça a cobrança com o cliente. |

Veja também a referência de [Criar Pedido](https://docs.barte.com/api-reference/pedidos-e-cobrancas/criar-pedido.md) e de [Criar Pedido com Token do Cartão](https://docs.barte.com/api-reference/tokenizacao-de-cartao-one-buy-click/criar-pedido-com-token-do-cartao.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.barte.com/guias/pedidos-e-cobrancas/cobrancas-com-cartao-salvo-stored-credential.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
