Documentação
Referência das APIs dos provedores, em Markdown puro — a mesma leitura para pessoas e para agentes de IA.
C6 Bank — API de Checkout
Abrir .md# C6 Bank — API de Checkout
> Documentação de referência da API de Checkout do C6 Bank, transcrita da especificação
> oficial para consulta local (e para leitura por agentes de IA).
>
> - **Fonte:** <https://developers.c6bank.com.br/apis/checkout>
> - **Spec:** `https://developers.c6bank.com.br/yamls/checkout.yaml`
> - **Versão da spec:** 1.1.5 (OAS 3.0.3)
>
> Em caso de divergência, a fonte oficial prevalece. A última seção deste documento
> descreve o que o **DevFakeProviders** implementa desta API — que é um subconjunto.
---
## Visão geral
A API permite a criação, consulta, captura e cancelamento de *checkouts*, com suporte a
múltiplos meios de pagamento.
Um checkout é um **link de pagamento**: você o cria informando valor, pagador e formas de
pagamento aceitas, recebe de volta um `id` e uma `url`, e encaminha o pagador para essa URL.
O `id` é a chave usada em todas as demais operações (consulta, cancelamento, captura).
Meios de pagamento suportados:
- Carteiras digitais
- Cartões (crédito e débito)
- Pix
Cada checkout aceita **até 3 tentativas de pagamento**. A cada tentativa, um webhook
correspondente (se cadastrado) recebe uma notificação.
### Ambientes
| Ambiente | Host | Path |
|----------|----------------------------------------|------------------|
| Sandbox | `https://baas-api-sandbox.c6bank.info` | `/v1/checkouts/` |
| Produção | `https://baas-api.c6bank.info` | `/v1/checkouts/` |
### Autenticação
Todas as operações exigem o header `Authorization`:
```http
Authorization: Bearer {{your_access_token}}
```
Headers opcionais de identificação do parceiro:
| Header | Obrigatório | Exemplo |
|----------------------------|-------------|-------------|
| `partner-software-name` | não | `Super PDV` |
| `partner-software-version` | não | `1.0.0` |
---
## Endpoints
### `POST /` — Criar um checkout
Cria um novo checkout e define as formas de pagamento aceitas.
Se os dados do pagador não forem informados, eles serão solicitados diretamente no checkout,
em tempo de transação. Se forem informados, o pagador **não poderá editá-los**.
Para autorização direta, o cartão tokenizado (`payment.card.card_info.token`) sempre deve ser
enviado.
**Request:** schema [`checkout`](#checkout) — obrigatórios: `amount`, `payment`.
**Resposta `201`:**
```json
{
"id": "e4cf07fc-6b14-4477-a694-5053189726f7",
"url": "https://checkout.c6bank.info/01J3NCKY6Q99QC4D7T733D35QD"
}
```
---
### `POST /authorize` — Autorizar um checkout
Autorização automática e síncrona, usando um token de cartão obtido em autorização anterior.
**Request:** schema `authorizeRequest` — obrigatórios: `payer`, `payment`,
`external_reference_id`, `amount`, `address`. Dentro de `payment.card`, são obrigatórios
`installments` e `card_info`.
**Resposta `200`:** schema `authorizeResponse`. O status da autorização deve ser avaliado
no conteúdo do objeto retornado — um `200` não significa, por si só, que a transação foi
aprovada.
---
### `GET /{id}` — Consultar um checkout
Obtém, de forma síncrona, as informações de um checkout. É por aqui que se identifica se o
pagamento foi realizado com sucesso.
**Resposta `200`:** o objeto `checkout` acrescido dos campos de resultado em
`payment.card`: `authenticate`, `capture`, `capturedAmount`, `interest_type`,
`installments`, `authorization_code`, `message`, `return_code`, `recurrent`, `save_card`,
`card_info`, `soft_descriptor`, `type`.
---
### `PUT /{id}/capture` — Capturar um checkout
> **DISPONÍVEL EM BREVE** — não operacional no momento.
Por padrão, checkouts são criados com captura automática. É possível desativá-la com
`payment.card.capture = false`; nesse caso, a captura precisa ser feita por este método.
Caso de uso comum: validação de estoque pós-compra — a venda é feita com captura manual e,
confirmada a disponibilidade, a transação é capturada.
**Resposta `204`.**
---
### `PUT /{id}/cancel` — Cancelar um checkout
Cancela um checkout a partir de um ID.
> **Checkouts não finalizados (não pagos pelo pagador) são abortados, enquanto checkouts já
> pagos são estornados (sempre que a forma de pagamento permitir).**
Atualiza o status do checkout para `CANCELLED`.
**Resposta `204`.**
Observações relevantes:
- O endpoint **não recebe nem consulta a forma de pagamento** — o único parâmetro é o `id`.
Não existe, na API, cancelamento específico por meio de pagamento.
- A ressalva *"sempre que a forma de pagamento permitir"* incide apenas sobre o caso de
checkout **já pago**. A spec não detalha quais formas permitem o estorno.
---
### `GET /sdk-doc` — Documentação do SDK (Checkout Transparente)
Retorna a documentação do SDK usado no checkout transparente.
### `GET /generate/public-key` — Gerar chave pública
Gera a chave pública usada pelo checkout transparente. As chaves têm validade máxima de
**10 minutos** (recomenda-se renovação periódica).
**Resposta:** `public_key`, `session_key`, `expires_in`.
---
## Ciclo de vida (`status`)
Ao criar um checkout, o status é `CREATED`.
| Status | Terminal | Significado |
|-------------------------------------|----------|------------------------------------------------|
| `CREATED` | não | Checkout criado, pagador ainda não interagiu |
| `IN PROGRESS` | não | Pagador está no fluxo de pagamento |
| `AUTHORIZED, CONFIRMATION PENDING` | não | Autorizado, aguardando confirmação/captura |
| `CONFIRMATION REQUESTED` | não | Confirmação solicitada |
| `PAID` | **sim** | Pago — valor debitado do pagador |
| `CANCELLATION REQUESTED` | não | Cancelamento solicitado |
| `CANCELLED` | **sim** | Cancelado |
| `DECLINED` | **sim** | Recusado |
| `EXPIRED` | **sim** | Expirado sem pagamento |
| `ERROR` | **sim** | Erro no processamento |
Os status terminais não podem ser alterados. Os demais são intermediários e mudam por ação
do usuário ou do adquirente.
Se `expiration_date_time` não for informado, considera-se **7 dias** a partir da criação;
não havendo pagamento, o status vai automaticamente para `EXPIRED`.
---
## Schemas
### checkout
Obrigatórios: `amount`, `payment`.
| Campo | Tipo | Somente leitura | Descrição |
|------------------------|----------|-----------------|--------------------------------------------------------|
| `amount` | number | não | Valor total. Mín. `5`, máx. `500000`. Ex.: `123.45` |
| `description` | string | não | Texto livre para descrição da transação |
| `emission_date_time` | date-time| **sim** | Data/hora da criação |
| `expiration_date_time` | date-time| **sim** | Data/hora da expiração (padrão: criação + 7 dias) |
| `external_reference_id`| string | não | Identificador do lado externo. `^[a-zA-Z0-9]{1,10}$` |
| `id` | string | **sim** | Identificador forte do checkout (UUID) |
| `payer` | object | não | Dados do pagador |
| `payment` | object | não | `card` e/ou `pix` |
| `redirect_url` | string | não | URL de retorno após o uso do checkout |
| `status` | string | **sim** | Ver ciclo de vida |
| `url` | string | **sim** | URL do checkout, para onde encaminhar o pagador |
`external_reference_id` não é consistido pelo C6, **mas não pode ser repetido para um mesmo
cliente**. Se não enviado, um identificador aleatório é gerado.
### payer
Todos os elementos são opcionais **na API** e obrigatórios **para a transação**: se não forem
enviados, serão solicitados ao pagador no momento do pagamento.
| Campo | Tipo | Regras | Exemplo |
|----------------|--------|--------------------------------------------|------------------------|
| `name` | string | máx. 40, não pode ser vazio/espaços | `José da Silva` |
| `tax_id` | string | 11–14 dígitos, sem máscara, com zeros à esq.| `12345678910` |
| `email` | string | máx. 200, formato e-mail | `pagador@email.com.br` |
| `phone_number` | string | — | `11999999999` |
| `address` | object | ver abaixo | — |
### address
Obrigatórios: `city`, `number`, `state`, `street`, `zip_code`.
| Campo | Tipo | Regras | Exemplo |
|--------------|--------|---------------------------------|---------------------|
| `street` | string | máx. 40 | `Av. Nove de Julho` |
| `number` | number | — | `123` |
| `complement` | string | máx. 24 | `Complemento` |
| `city` | string | máx. 40 | `Rio de Janeiro` |
| `state` | string | 2 chars, `[A-Z]{2}` | `RJ` |
| `zip_code` | string | exatamente 8 dígitos, `\d{8}` | `05093000` |
> `street` + `number` somados não podem ultrapassar 40 posições.
### payment.card
Obrigatórios: `type`, `installments`.
| Campo | Tipo | Padrão | Descrição |
|---------------------|---------|----------------|-----------------------------------------------------------------|
| `type` | enum | — | `DEBIT` ou `CREDIT` |
| `installments` | integer | — | Máx. de parcelas. 1–12. Se > 1, `interest_type` é obrigatório |
| `interest_type` | enum | — | `BY_SELLER` (parcelado loja) ou `BY_ISSUER` (parcelado emissor) |
| `fixed_installments`| boolean | `true` | Se o pagador pode escolher a quantidade de parcelas |
| `authenticate` | enum | `NOT_REQUIRED` | `REQUIRED`, `OPTIONAL`, `NOT_REQUIRED` |
| `capture` | boolean | `true` | Captura automática ou posterior |
| `recurrent` | boolean | `false` | Sinaliza transação recorrente ao emissor |
| `save_card` | boolean | `false` | Tokeniza o cartão para cobranças futuras |
| `soft_descriptor` | string | — | DISPONÍVEL EM BREVE |
| `card_info` | — | — | `card_hash` ou `token` |
Em `authenticate: OPTIONAL`, há tentativa de autenticação do portador; não sendo possível,
a transação segue para autorização.
**Campos de retorno** (somente leitura, presentes na consulta):
`authorization_code`, `message`, `return_code`, `captured_amount`.
### payment.pix
| Campo | Obrigatório | Valores | Descrição |
|-------|-------------|---------|--------------------------------------------------------------|
| `key` | sim | `AUTO` | `AUTO` (padrão) gera chave aleatória. Outras chaves em breve. |
### card_info (request) / card_info_response
No **request**, `card_info` é `card_hash` **ou** `token` (string).
Na **resposta**:
| Campo | Exemplo |
|---------------|------------------------------------------|
| `number` | `483430******6234` |
| `brand` | `VISA` |
| `holder_name` | `Jane Doe` |
| `token` | `be4cbeb1-abb2-4913-8165-f86962143fa021` |
O `token` é retornado quando `save_card = true` e a transação é aprovada. Enviá-lo em um novo
checkout dispara automaticamente uma tentativa de pagamento com aquele cartão.
### fraud_analysis
Somente leitura. Resultado da avaliação do antifraude.
| Campo | Tipo | Valores |
|------------------|---------|--------------------|
| `analyzed` | boolean | `true` / `false` |
| `recommendation` | enum | `APPROVE` / `DENY` |
---
## Tokenização e recorrência
1. Crie um checkout com `payment.card.save_card = true`.
2. Aprovada a transação, a resposta traz `card_info.token`.
3. Em cobranças futuras, envie esse token em `payment.card.card_info.token` — inclusive via
`POST /authorize`, para assinaturas e renovações periódicas.
---
## Erros
A spec descreve apenas as famílias `4xx` e `5xx`, remetendo à documentação de erros comum:
<https://developers.c6bank.com.br/apis/errors>
O endpoint de cancelamento, por exemplo, responde `204` no sucesso e `4xx` genérico na recusa
— não há enumeração de códigos por motivo.
---
## O que o DevFakeProviders implementa
O simulador cobre o subconjunto usado pelo Recash. Base local: `/c6/v1/checkouts`.
| Rota | Correspondente oficial | Observação |
|-----------------------------|------------------------|---------------------------------------------|
| `POST /c6/v1/checkouts` | `POST /` | Criação |
| `GET /c6/v1/checkouts/{id}` | `GET /{id}` | Consulta |
| `PUT /{id}/cancel` | `PUT /{id}/cancel` | Recusa com `400` se o status for `PAID` ou `CANCELLED` |
| `PUT /{id}/set_cancelled` | — | Alias do cancelamento |
| `PUT /{id}/status` | — | **Não existe no C6.** Força um status, para teste |
| `PUT /{id}/notify` | — | **Não existe no C6.** Dispara um webhook sem alterar o estado |
Autenticação em `/c6/v1/auth` e webhooks em `/c6/v1/webhooks`.
### Diferenças que importam ao testar
- `PUT /{id}/status` e `PUT /{id}/notify` são endpoints **exclusivos do simulador**. Não
espere que existam em produção.
- Alterar o status por `PUT /{id}/status` **não notifica o Recash**. O status local da
transação continua defasado até que chegue um webhook (`PUT /{id}/notify`) ou que uma
consulta de status seja executada.
- `PUT /{id}/capture` não está implementado no simulador — coerente com o C6, onde a captura
está marcada como *disponível em breve*.
URL direta do arquivo: /docs/c6-checkout.md