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

# Como funcionam as cobranças

> O que é uma cobrança, quais formas de pagamento existem, como escolher entre elas e como acompanhar cada cobrança do pedido ao pagamento.

A cobrança (charge) é o pedido de pagamento que o seu cliente vai pagar. Toda venda feita pela API da Finvia nasce de uma única rota, `POST /v1/charges`, e depois é acompanhada pela resposta da criação, pelos webhooks e pela consulta da cobrança. Com esse ciclo claro, a integração libera o pedido só quando ele foi pago e não deixa de liberar um pedido pago.

> [!NOTE]
>
> **Para o negócio:** com uma mesma integração você recebe por Pix, cartão de crédito digitado, cartão salvo e Apple Pay, e pode dividir o valor entre contas (split). A forma de pagamento muda só um bloco da requisição, o `paymentMethod`. O restante (valor, cliente, itens, endereço) é igual para todas.

## Quando usar

| Situação | O que usar |
| - | - |
| Venda avulsa em loja virtual, com o cliente no checkout | `POST /v1/charges` com Pix ou cartão |
| Recompra rápida de um cliente que já comprou com cartão | `POST /v1/charges` com cartão salvo (`cardTokenId` + `cvv`) |
| Cobrança automática todo mês, sem o cliente presente | [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md). A rota de cobrança exige o CVV do comprador em toda cobrança com cartão |
| Venda com comissão para outra conta (marketplace, plataforma) | `POST /v1/charges` com `split` ([Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)) |
| Desfazer uma venda paga | [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md) |

## Formas de pagamento

O campo `paymentMethod.type` define a forma de pagamento. Cartão digitado, cartão salvo e Apple Pay usam o mesmo `type` (`credit_card`) e se diferenciam pelos campos que vão junto.

| Forma | `type` | Campos que identificam | Guia |
| - | - | - | - |
| Pix | `pix` | `expirationInDays` ou `expirationInSeconds` | [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md) |
| Cartão de crédito digitado | `credit_card` | `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` | [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) |
| Cartão salvo | `credit_card` | `cardTokenId`, `cvv`, `installments` | [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) |
| Apple Pay | `credit_card` | `wallet`, `installments` | [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) |

### Qual escolher em cada situação

| Se o seu cenário é... | Forma indicada | Por quê |
| - | - | - |
| Cliente quer pagar à vista | Pix | A resposta traz o QR Code e o código copia e cola. O pagamento é confirmado por webhook |
| Cliente quer parcelar | Cartão de crédito | Aceita de 1 a 12 parcelas (`installments`) |
| Você precisa da aprovação na própria resposta | Cartão de crédito | Aprovação e recusa voltam na resposta da criação |
| Cobrança enviada por link ou mensagem, para o cliente pagar depois | Pix com validade em dias | `expirationInDays` mantém o QR Code válido por um ou mais dias |
| Cliente recorrente que já tem cartão guardado na sua loja | Cartão salvo | O cliente informa só o CVV |
| Checkout web com público que usa iPhone ou Mac | Apple Pay | O cliente paga com o cartão da Wallet, sem digitar dados. Só em `BRL` |
| Cobrança fixa todo mês | Assinaturas | Cobra a cada ciclo sem o cliente presente |

> [!NOTE]
>
> A lista do que está habilitado para a sua conta, por moeda, vem de [`GET /v1/payment-methods`](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar). Para cobrar, a conta também precisa ter taxa configurada para o método e a moeda: sem ela, a API responde `422` `Fees not configured`.

O desenho abaixo resume a tabela: com duas ou três perguntas sobre o seu cenário, você chega à forma de pagamento indicada.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    INI(["Cliente pronto para pagar"]):::comprador
    Q1{"Cobra todo mês, sem<br/>o cliente presente?"}:::decisao
    ASS["<b>Assinaturas</b><br/>POST /v1/subscriptions"]:::neutro
    Q2{"Quer parcelar ou precisa<br/>da aprovação na hora?"}:::decisao
    Q3{"Paga agora, com<br/>o checkout aberto?"}:::decisao
    PIXS["<b>Pix com validade curta</b><br/>expirationInSeconds 900 ou mais"]:::neutro
    PIXD["<b>Pix com validade em dias</b><br/>expirationInDays 1 ou mais"]:::neutro
    Q4{"Já tem cartão<br/>salvo na loja?"}:::decisao
    SALVO["<b>Cartão salvo</b><br/>cardTokenId + cvv"]:::neutro
    Q5{"Usa iPhone ou Mac<br/>e paga em reais?"}:::decisao
    AP["<b>Apple Pay</b><br/>wallet"]:::neutro
    CC["<b>Cartão digitado</b><br/>number, holderName, cvv..."]:::neutro
    INI --> Q1
    Q1 -->|"sim"| ASS
    Q1 -->|"não"| Q2
    Q2 -->|"não, paga à vista"| Q3
    Q3 -->|"sim"| PIXS
    Q3 -->|"não, recebe por link"| PIXD
    Q2 -->|"sim"| Q4
    Q4 -->|"sim"| SALVO
    Q4 -->|"não"| Q5
    Q5 -->|"sim"| AP
    Q5 -->|"não"| CC
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Cartão digitado, cartão salvo e Apple Pay usam o mesmo `type` (`credit_card`) e aceitam de 1 a 12 parcelas. O Pix é sempre à vista.

O desenho abaixo mostra o caminho comum a toda cobrança, da criação até a liberação do pedido, e o que fazer com cada status da resposta.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    SRV["Seu servidor<br/>POST /v1/charges"]:::lojista
    API["Finvia API"]:::finvia
    D{"Qual status veio<br/>na resposta?"}:::decisao
    PAID(["paid<br/>cartão aprovado"]):::ok
    REF(["refused / failed<br/>motivo em reason"]):::erro
    PEN(["pending<br/>mostre o QR Code Pix"]):::alerta
    AN(["in_analysis<br/>revisão do antifraude"]):::alerta
    AUT(["authentication_required<br/>abra a authenticationUrl"]):::alerta
    OUTRA["Ofereça outro cartão<br/>ou outra forma de pagamento"]:::neutro
    EV[["Webhooks<br/>endpoints ou postbackUrl"]]:::evento
    GET["Seu servidor<br/>GET /v1/charges/{id}"]:::lojista
    Q{"Status é paid?"}:::decisao
    LIB(["Libera o pedido"]):::ok
    ESP["Não libera ainda<br/>continua ouvindo os webhooks"]:::neutro
    SRV ==>|"1. cria a cobrança"| API
    API ==>|"2. responde 201"| D
    D --> PAID
    D --> REF
    D --> PEN
    D --> AN
    D --> AUT
    REF --> OUTRA
    PEN -.->|"3. desfecho depois"| EV
    AN -.-> EV
    AUT -.-> EV
    PAID ==> GET
    EV -.->|"4. avisa o seu sistema"| GET
    GET ==>|"5. confere"| Q
    Q ==>|"sim"| LIB
    Q -->|"não"| ESP
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

Depois de `paid`, a cobrança ainda pode ser bloqueada ou mudar para `refunded`, `pre_chargeback` ou `chargeback`. Por isso o receptor de webhooks continua ativo mesmo depois de liberar o pedido.

## Como funciona

**1. Seu servidor cria a cobrança**

Você chama `POST /v1/charges` com a chave secreta, informando valor, moeda, cliente, itens e forma de pagamento. Guarde o `id` devolvido: ele identifica a cobrança em todas as etapas seguintes.

**2. A resposta síncrona diz o que fazer agora**

No cartão, a resposta já traz o resultado (`paid`, `refused` ou `failed`), ou `in_analysis` quando o antifraude manda para revisão manual. No Pix, traz o QR Code com status `pending`. Com 3D Secure gerenciado, pode vir `authentication_required` com a `authenticationUrl` para o comprador se autenticar.

**3. Os webhooks contam o que aconteceu depois**

Mudanças posteriores (Pix pago, estorno, bloqueio, alerta de chargeback) chegam por webhook, uma notificação que a Finvia envia ao seu sistema. Quais eventos vão aos endpoints do painel e quais vão à `postbackUrl` está na [tabela de eventos por canal](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#eventos-por-canal).

**4. Seu sistema confirma e libera o pedido**

Antes de liberar produto ou acesso, confirme o status com [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar). Os webhooks não têm assinatura, então a consulta à API é a sua confirmação.

## Ciclo de vida da cobrança

| Status | Significado | De onde vem |
| - | - | - |
| `pending` | Aguardando pagamento (ex.: Pix gerado) | Resposta da criação, `charge.pending` |
| `paid` | Pago com sucesso | Resposta da criação (cartão), `charge.paid` |
| `refused` | Recusado (emissor, antifraude ou 3DS obrigatório) | Resposta da criação, `charge.refused` |
| `failed` | Falha no processamento | Resposta da criação, `charge.failed` |
| `in_analysis` | Em revisão manual do antifraude | Resposta da criação. O desfecho chega pelo `charge.updated` na `postbackUrl` ou pela consulta |
| `authentication_required` | Aguardando autenticação do comprador | Resposta da criação com 3DS gerenciado ([3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md)) |
| `refunded` | Estornado | Estorno concluído, `charge.refunded` |
| `pre_chargeback` | Alerta de contestação recebido antes da disputa formal | `charge.pre_chargeback` |
| `chargeback` | Chargeback formalizado | `charge.updated` na `postbackUrl` ([Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)) |

Além do status, uma cobrança paga pode ficar **bloqueada** durante uma disputa (MED no Pix ou chargeback no cartão). O status continua `paid` e o bloqueio aparece em `isBlocked` na consulta e no evento `charge.blocked`. O detalhamento de cada status está em [Status de cobrança](https://docs.fastpaybrasil.com/anexos/status-de-cobranca.md).

> [!WARNING]
>
> Trate `pending` como "ainda não pago". Libere o pedido só com `paid` confirmado por `GET /v1/charges/{id}`. Uma cobrança `paid` ainda pode ser bloqueada ou mudar depois para `refunded`, `pre_chargeback` ou `chargeback`, por isso o seu sistema precisa continuar ouvindo os webhooks.

## O que vem na resposta e o que vem por webhook

| Informação | Resposta da criação (síncrona) | Webhook |
| - | - | - |
| `id` da cobrança | Sim | Sim (`data.id`) |
| Aprovação ou recusa do cartão, com `reason` | Sim | `charge.paid`, `charge.refused` ou `charge.failed`. O motivo da recusa não vem no envelope padrão |
| QR Code e copia e cola do Pix | Sim (`paymentDetails`) | Também em `payment_details` |
| Confirmação de pagamento do Pix | Não | `charge.paid` |
| Desfecho de uma cobrança `in_analysis` ou `pending` no cartão | Não | `charge.updated`, só na `postbackUrl`. Ou consulte a cobrança |
| Estorno concluído | Não (o estorno tem resposta própria) | `charge.refunded` |
| Bloqueio por MED ou chargeback | Não | `charge.blocked` (endpoints e `postbackUrl`) |
| Alerta de pré-chargeback | Não | `charge.pre_chargeback` (endpoints e `postbackUrl`) |
| Chargeback formalizado | Não | `charge.updated` com `status: "chargeback"`, só na `postbackUrl` |
| Valor líquido (`net`) e spread aplicado (`spread`) | Não | Sim, e também na consulta |

A resposta da criação traz `id`, `status`, `paymentDetails` e `reason`, mais `authenticationUrl` e `customerId` em alguns casos. Os detalhes completos da cobrança (valor líquido, cliente, metadata, split, datas) vêm na consulta e nos webhooks.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Valor em reais | `"amount": 10` significa R\$ 10,00. Mínimo: `1` |
| Campos obrigatórios | `amount`, `currency`, `customer`, `paymentMethod`, `items` |
| Cliente | Informe o `id` de um cliente já cadastrado ou envie `name` + `email` (ou `phone`) para criar ou localizar o cliente na mesma chamada |
| Itens físicos | Se algum item for `physical`, `shippingAddress` é obrigatório |
| Endereço de entrega | Obrigatórios: `postalCode`, `addressLine1`, `city`, `state` e `country` (alpha-3, ex.: `BRA`). `addressLine2` e `neighborhood` são opcionais |
| Parcelas | `installments` de `1` a `12` |
| Permissão da chave | Chave gerada por usuário com perfil Desenvolvedor recebe `403` ao criar cobrança |
| Idempotência | A API não aceita `Idempotency-Key`: cada chamada cria uma cobrança nova |

> [!WARNING]
>
> Enviar o valor em centavos multiplica a cobrança por 100. `1000` gera uma cobrança de R\$ 1.000,00, e não de R\$ 10,00.

### Itens físicos e digitais

O `type` de cada item diz se você entrega algo pelo correio ou transportadora (`physical`) ou se entrega acesso, arquivo ou serviço online (`digital`).

* **Produto digital** (curso, ebook, software): envie `items[].type` `digital`, sem `shippingAddress`.
* **Produto físico** (roupa, eletrônico, cosmético): envie `items[].type` `physical` e o `shippingAddress`. Se quiser, envie também `trackingInfo` com o código e a situação do envio (`awaiting_shipment`, `on_the_way` ou `delivered`).

Se algum item for `physical` e o corpo não trouxer `shippingAddress`, a API responde `400` com a mensagem literal `Shipping info must be provided for merchants selling physical items.`, antes de criar a cobrança. A regra depende só dos itens enviados.

### Metadata

`metadata` é um objeto livre onde você guarda informações suas na cobrança, como o número do pedido. Ele volta na consulta e nos webhooks, o que ajuda a ligar o evento recebido ao pedido do seu sistema.

```json theme={null}
{
  "metadata": { "orderId": "ORD-123", "productId": "PROD-456" }
}
```

Escreva as chaves de `metadata` em camelCase (`orderId`) ou com uma palavra só (`pedido`). Assim elas voltam iguais em todos os canais, e todos os exemplos desta documentação seguem essa regra.

> [!NOTE]
>
> Chaves com sublinhado (snake\_case, como `order_id`) mudam de formato conforme o canal. Nos webhooks do envelope padrão (`charge.paid`, `charge.refunded` e os demais), elas voltam exatamente como foram enviadas (`order_id`). Nas respostas de `GET /v1/charges` e `GET /v1/charges/{id}` e no `charge.updated` legado, voltam convertidas para camelCase (`orderId`). Se a sua integração já usa snake\_case, leia os dois formatos.

### Timeout na criação

A API não aceita cabeçalho de idempotência e não busca cobranças por `metadata`. Se a chamada de criação der timeout, siga esta ordem:

**1. Não reenvie o POST de imediato**

Se a primeira chamada chegou, um novo POST cria uma segunda cobrança. No cartão, isso é cobrança em dobro.

**2. Procure o charge.created**

Com um endpoint de webhook cadastrado, o `charge.created` chega assim que a cobrança é gravada e traz o `id` e a `metadata` como foram enviadas. É a forma mais confiável de recuperar o `id`.

**3. Busque na listagem**

`GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=<documento ou e-mail do comprador>&size=50`, com a mesma chave usada na criação. Compare `metadata` e `amount` do seu lado.

**4. Só então crie de novo**

Se nada for encontrado, a cobrança não foi criada e é seguro tentar de novo. Use um timeout de cliente generoso (por exemplo, 60 segundos): o cartão é processado de forma síncrona.

Detalhes em [Idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência) e em [Listar cobranças](https://docs.fastpaybrasil.com/referencia/cobrancas/listar.md).

### postbackUrl

`postbackUrl` é uma URL sua, informada na própria cobrança, que recebe de forma **assíncrona** os eventos dessa cobrança. Ela não muda a resposta da criação.

* Recebe os mesmos eventos de cobrança que os endpoints do painel, no envelope padrão: `charge.created`, `charge.pending`, `charge.paid`, `charge.refused`, `charge.failed`, `charge.refunded`, `charge.pre_chargeback` e `charge.blocked`. Não há filtro de eventos nesse canal.
* Recebe também o `charge.updated` legado, que vai **só** para a `postbackUrl`, em camelCase e sem `id` nem `livemode`. Ele avisa mudanças informadas depois pelo adquirente (pagamento, recusa ou falha assíncrona, estorno, chargeback), o fim do 3DS gerenciado com recusa, o bloqueio e o alerta de pré-chargeback.
* Se a mesma URL estiver cadastrada como endpoint e como `postbackUrl`, ela recebe cada evento duas vezes.

Sem `postbackUrl`, você não recebe o desfecho de cobranças que ficaram em `in_analysis` nem o aviso de chargeback formalizado. Os formatos estão na [tabela de eventos por canal](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#eventos-por-canal).

## Passo a passo

Exemplo de uma cobrança Pix para um produto digital, com metadata e postback.

```http REST (JSON) theme={null}
POST /v1/charges HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "pix",
    "expirationInDays": 1
  },
  "items": [
    {
      "title": "Produto XYZ",
      "type": "digital",
      "description": "Descrição do produto",
      "unit_price": 100,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "ORD-123"
  },
  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "BRL",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321",
      "address": { "country": "BRA" }
    },
    "paymentMethod": { "type": "pix", "expirationInDays": 1 },
    "items": [
      {
        "title": "Produto XYZ",
        "type": "digital",
        "description": "Descrição do produto",
        "unit_price": 100,
        "quantity": 1
      }
    ],
    "metadata": { "orderId": "ORD-123" },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia"
  }'
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100,
    currency: 'BRL',
    customer: { name: 'Joao Silva', email: 'joao@email.com' },
    paymentMethod: { type: 'pix', expirationInDays: 1 },
    items: [
      { title: 'Produto XYZ', type: 'digital', description: 'Descrição do produto', unit_price: 100, quantity: 1 },
    ],
    metadata: { orderId: 'ORD-123' },
    postbackUrl: 'https://meusite.com.br/webhooks/finvia',
  }),
});

const charge = await response.json();
// Grave charge.id no pedido ORD-123 antes de qualquer outra coisa
```

```python Python theme={null}
import os

import requests

payload = {
    "amount": 100,
    "currency": "BRL",
    "customer": {
        "name": "Joao Silva",
        "email": "joao@email.com",
        "document": {
            "type": "cpf",
            "id": "52998224725",
        },
        "phone": "+5511987654321",
        "address": {
            "country": "BRA",
        },
    },
    "paymentMethod": {
        "type": "pix",
        "expirationInDays": 1,
    },
    "items": [
        {
            "title": "Produto XYZ",
            "type": "digital",
            "description": "Descrição do produto",
            "unit_price": 100,
            "quantity": 1,
        },
    ],
    "metadata": {
        "orderId": "ORD-123",
    },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/charges",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'amount' => 100,
    'currency' => 'BRL',
    'customer' => [
        'name' => 'Joao Silva',
        'email' => 'joao@email.com',
        'document' => [
            'type' => 'cpf',
            'id' => '52998224725',
        ],
        'phone' => '+5511987654321',
        'address' => [
            'country' => 'BRA',
        ],
    ],
    'paymentMethod' => [
        'type' => 'pix',
        'expirationInDays' => 1,
    ],
    'items' => [
        [
            'title' => 'Produto XYZ',
            'type' => 'digital',
            'description' => 'Descrição do produto',
            'unit_price' => 100,
            'quantity' => 1,
        ],
    ],
    'metadata' => [
        'orderId' => 'ORD-123',
    ],
    'postbackUrl' => 'https://meusite.com.br/webhooks/finvia',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/charges');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "amount": 100,
              "currency": "BRL",
              "customer": {
                "name": "Joao Silva",
                "email": "joao@email.com",
                "document": {
                  "type": "cpf",
                  "id": "52998224725"
                },
                "phone": "+5511987654321",
                "address": {
                  "country": "BRA"
                }
              },
              "paymentMethod": {
                "type": "pix",
                "expirationInDays": 1
              },
              "items": [
                {
                  "title": "Produto XYZ",
                  "type": "digital",
                  "description": "Descrição do produto",
                  "unit_price": 100,
                  "quantity": 1
                }
              ],
              "metadata": {
                "orderId": "ORD-123"
              },
              "postbackUrl": "https://meusite.com.br/webhooks/finvia"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "amount": 100,
  "currency": "BRL",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "pix",
    "expirationInDays": 1
  },
  "items": [
    {
      "title": "Produto XYZ",
      "type": "digital",
      "description": "Descrição do produto",
      "unit_price": 100,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "ORD-123"
  },
  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "amount": 100,
	  "currency": "BRL",
	  "customer": {
	    "name": "Joao Silva",
	    "email": "joao@email.com",
	    "document": {
	      "type": "cpf",
	      "id": "52998224725"
	    },
	    "phone": "+5511987654321",
	    "address": {
	      "country": "BRA"
	    }
	  },
	  "paymentMethod": {
	    "type": "pix",
	    "expirationInDays": 1
	  },
	  "items": [
	    {
	      "title": "Produto XYZ",
	      "type": "digital",
	      "description": "Descrição do produto",
	      "unit_price": 100,
	      "quantity": 1
	    }
	  ],
	  "metadata": {
	    "orderId": "ORD-123"
	  },
	  "postbackUrl": "https://meusite.com.br/webhooks/finvia"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/charges")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "amount" => 100,
  "currency" => "BRL",
  "customer" => {
    "name" => "Joao Silva",
    "email" => "joao@email.com",
    "document" => {
      "type" => "cpf",
      "id" => "52998224725",
    },
    "phone" => "+5511987654321",
    "address" => {
      "country" => "BRA",
    },
  },
  "paymentMethod" => {
    "type" => "pix",
    "expirationInDays" => 1,
  },
  "items" => [
    {
      "title" => "Produto XYZ",
      "type" => "digital",
      "description" => "Descrição do produto",
      "unit_price" => 100,
      "quantity" => 1,
    },
  ],
  "metadata" => {
    "orderId" => "ORD-123",
  },
  "postbackUrl" => "https://meusite.com.br/webhooks/finvia",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

Resposta `201`:

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "pending",
  "paymentDetails": {
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo..."
  },
  "reason": null,
  "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
```

Para cobrar com outra forma de pagamento, troque apenas o `paymentMethod`. Os exemplos completos de cada forma estão nos guias específicos e em [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie o endereço com `postalCode`, `addressLine1`, `city`, `state` e `country` |
| `400` com `shippingAddress.country must be a valid ISO31661 Alpha3 code` | País em duas letras | Envie `BRA` |
| `422` com `Fees not configured` | Conta sem taxa para o método e a moeda | Fale com o suporte da Finvia |
| Valor 100 vezes maior | `amount` em centavos | Envie em reais |
| `403` ao criar cobrança | Perfil do usuário que gerou a chave | Gere a chave com um usuário Owner ou Manager. Veja [Permissões da chave](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#permissões-da-chave) |
| `401` | Chave inválida ou cabeçalho mal montado | Confira [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md) |
| Não recebe o aviso de chargeback formalizado | Cobrança criada sem `postbackUrl` | Informe `postbackUrl` em todas as cobranças |
| Cobrança duplicada após timeout | Reenvio do POST sem verificar a primeira | Siga o [procedimento de timeout](#timeout-na-criação) |

## Perguntas frequentes

> [accordion] Preciso cadastrar o cliente antes de cobrar?
>
> Não. Você pode enviar `name` e `email` (ou `phone`) dentro de `customer` e a API cria ou localiza o cliente na mesma chamada. O `customerId` da resposta traz o cliente usado, quando a cobrança chega ao adquirente. Se você já tem o cliente cadastrado, envie só o `id` dele. Veja [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md).

> [accordion] Posso usar só os webhooks do painel e ignorar a postbackUrl?
>
> Os endpoints do painel recebem pagamento, recusa síncrona, estorno, bloqueio e pré-chargeback. Dois avisos chegam só pelo `charge.updated`, na `postbackUrl`: o desfecho de cobranças que ficaram em `in_analysis` ou `pending` no cartão e o status `chargeback` do chargeback formalizado (quando o valor é revertido do saldo, os endpoints recebem também `charge.refunded`). Se você não usa `postbackUrl`, consulte essas cobranças periodicamente.

> [accordion] A cobrança paga pode mudar de status depois?
>
> Pode. Uma cobrança `paid` pode ser bloqueada (`isBlocked: true`, ainda `paid`) ou ir para `refunded` (estorno), `pre_chargeback` (alerta de contestação) ou `chargeback`. Mantenha o seu endpoint de webhook ativo e o pedido ligado ao `id` da cobrança.

> [accordion] Como acho uma cobrança pelo número do meu pedido?
>
> Não há filtro por `metadata`. Grave o `id` assim que a criação responder. Se perdeu o `id`, use o `charge.created` ou a listagem com período e `searchFor`, como em [Timeout na criação](#timeout-na-criação).

> [accordion] Como sei quais formas de pagamento minha conta aceita?
>
> Chame [`GET /v1/payment-methods`](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar). O filtro `currency` mostra o que está disponível para uma moeda específica. Pix e Apple Pay aceitam somente `BRL`.

## Como testar

Use a chave de teste (`sk_test_`). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação e o resultado do cartão depende do número usado ([cartões de teste](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md#cartões-de-teste)). Execute os cenários da seção "Cobrança sem split" do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md):

* **CHG-01** e **CHG-02**: cartão aprovado à vista e parcelado.
* **CHG-03**: cartão recusado, com `refused` na resposta e o webhook `charge.refused`.
* **CHG-04** e **CHG-05**: Pix gerado e Pix pago.
* **CHG-06**: consulta da cobrança.
* **CHG-07**: estorno total.
* **CHG-08** e **CHG-09**: recebimento e simulação de webhook.
* **CHG-10**: item físico sem endereço (`400`) e com endereço (`201`).

Se você usa split, execute também **SPL-01** a **SPL-06**.

## Veja também

> [card] [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
>
> QR Code, validade e confirmação por webhook.

> [card] [Cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md)
>
> Cartão digitado, parcelamento e recusas.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos e formato dos payloads.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Todos os campos da rota.


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