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

# Criar uma cobrança

> Cria o pedido de pagamento que o seu cliente vai pagar: Pix, cartão de crédito, cartão salvo ou Apple Pay.

Esta é a rota central da API. Nela você define **quanto** cobrar, **de quem**, **o que** está sendo vendido e **como** o cliente vai pagar. A mesma chamada atende venda avulsa em loja virtual, compra de curso, recompra com cartão salvo, Apple Pay e venda com divisão de valores entre contas (split).

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Checkout de loja virtual | `paymentMethod.type` `pix` ou `credit_card`, com `shippingAddress` se algum item for físico |
| Venda de produto digital | Itens com `type` `digital`, sem endereço de entrega |
| Recompra com um clique | `credit_card` com `cardTokenId` e `cvv` |
| Apple Pay | `credit_card` com o objeto `wallet` |
| Marketplace | Qualquer forma de pagamento, com `split` |
| Cobrança automática todo mês | Use [Assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md). Esta rota exige o CVV do comprador em toda cobrança com cartão |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário **Owner** ou **Manager** ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)). Chave de usuário com perfil Desenvolvedor recebe `403`.
* A sua conta precisa ter taxa configurada para o método e a moeda da cobrança. Sem ela, a API responde `422` `Fees not configured`, inclusive no Modo Teste.
* Se algum item for `physical`, tenha o endereço de entrega.
* Se vai usar split, as contas recebedoras precisam pertencer ao mesmo grupo [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md).

> [!WARNING]
>
> O valor vai em **reais**: `"amount": 10` significa R\$ 10,00. O mínimo é `1`. Enviar `1000` pensando em R\$ 10,00 gera uma cobrança de R\$ 1.000,00.

> [!WARNING]
>
> A API não aceita cabeçalho de idempotência: cada chamada cria uma cobrança nova. Se a criação der timeout, **não reenvie de imediato**. Siga o [procedimento para timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência): mande o número do seu pedido em `metadata`, recupere o `id` pelo webhook `charge.created` ou pela listagem e só crie outra cobrança se nada for encontrado.

## Corpo da requisição

Campos obrigatórios: `amount`, `currency`, `customer`, `paymentMethod` e `items`.

**amount** `number` *required*

Valor da cobrança em reais (ex.: `10` = R\$ 10,00). Mínimo: `1`.

**currency** `string` *required*

Código da moeda no padrão ISO 4217. Ex.: `BRL`. Apple Pay e Pix aceitam só `BRL`.

**customer** `object` *required*

Quem está pagando. Há dois caminhos: informar o `id` de um cliente já cadastrado (os outros campos ficam opcionais e o cadastro existente é usado como está) ou enviar `name` + `email` (ou `phone`) para a API criar ou localizar o cliente na mesma chamada.

**propriedades**

**id** `string`

ID de um cliente existente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**name** `string`

Nome do cliente. Ex.: `Maria Souza`.

**email** `string`

E-mail do cliente. Obrigatório quando não há `id` nem `phone`. Ex.: `maria@email.com`.

**phone** `string`

Telefone do cliente. Pode substituir o `email` quando não há `id`. Ex.: `+5511987654321`.

**document** `object`

Documento do cliente. Obrigatório no Apple Pay.

**propriedades**

**type** `string`

Tipo do documento: `cpf` ou `cnpj`.

**id** `string`

Número do documento. Ex.: `52998224725`.

**address** `object`

**propriedades**

**country** `string`

País no padrão ISO 3166-1 alpha-3. Ex.: `BRA`.

**ipAddress** `string`

IP do cliente no momento da compra. Ex.: `177.128.144.97`.

**paymentMethod** `object` *required*

Como o cliente vai pagar. Aceita quatro formatos, identificados pelo `type` e pelos campos que vêm junto. Veja [Formas de pagamento](#formas-de-pagamento) abaixo.

**items** `object[]` *required*

Lista do que está sendo vendido. Todos os campos do item são obrigatórios.

**propriedades**

**title** `string` *required*

Nome do item. Ex.: `Tênis de corrida`.

**type** `string` *required*

Tipo do item: `physical` (entregue por correio ou transportadora) ou `digital`. Se algum item for `physical`, `shippingAddress` é obrigatório.

**description** `string` *required*

Descrição do item. Ex.: `Tamanho 38`.

**unit\_price** `number` *required*

Preço unitário, na mesma unidade de `amount` (reais, decimal). Ex.: `199.9`.

**quantity** `number` *required*

Quantidade. Ex.: `1`.

**shippingAddress** `object`

Endereço de entrega. Obrigatório quando algum item é `physical`. Sem ele, a API responde `400` antes de criar a cobrança: nenhum `id` é gerado e nenhum webhook é enviado.

**propriedades**

**postalCode** `string` *required*

CEP. Ex.: `01310100`.

**addressLine1** `string` *required*

Logradouro e número. Ex.: `Av. Paulista, 1000`.

**addressLine2** `string`

Complemento (apartamento, sala, bloco). Opcional. Ex.: `Apto 51`.

**neighborhood** `string`

Bairro. Opcional. Ex.: `Bela Vista`.

**city** `string` *required*

Cidade. Ex.: `São Paulo`.

**state** `string` *required*

Estado (UF). Ex.: `SP`.

**country** `string` *required*

País no padrão ISO 3166-1 alpha-3. Ex.: `BRA`. Envie em maiúsculas: o valor volta nos webhooks exatamente como foi enviado.

**trackingInfo** `object`

Dados de rastreio do envio.

**propriedades**

**trackingCode** `string`

Código de rastreio da transportadora. Ex.: `BR123456789BR`.

**shippingProvider** `string`

Nome da transportadora. Ex.: `Correios`.

**trackingUrl** `string`

Link para acompanhar a entrega.

**trackingStatus** `string`

Situação da entrega: `awaiting_shipment`, `on_the_way` ou `delivered`.

**metadata** `object`

Informações suas, em formato livre, que ficam guardadas na cobrança. Ex.: `{"orderId": "ORD-123"}`. Use chaves em camelCase, que voltam iguais em todos os canais. Chaves em snake\_case voltam convertidas para camelCase nas respostas de `GET` e no `charge.updated`. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata).

**postbackUrl** `string`

URL (formato `uri`) que recebe, de forma assíncrona, os eventos desta cobrança. Ela não muda a resposta da criação. Ex.: `https://meusite.com.br/webhooks/finvia`.

A `postbackUrl` recebe os mesmos eventos de cobrança que os endpoints de webhook do painel, no envelope padrão (`id`, `event`, `livemode`, `data`): `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. Ela recebe também o `charge.updated` legado, que vai **só** para a `postbackUrl`, em camelCase e sem `id` nem `livemode`. Veja a [tabela de eventos por canal](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#eventos-por-canal).

**split** `object[]`

Divisão do valor entre contas do mesmo grupo Connect. Se você não enviar `split`, a API aplica a regra de split padrão da conta para aquela moeda e método, quando houver uma.

**propriedades**

**merchantId** `string`

Conta que vai receber a parte. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**percentage** `number`

Percentual destinado a essa conta. Mínimo `0.01`, máximo `100`.

> [!NOTE]
>
> **Para o negócio:** por padrão, o percentual do split incide sobre o **valor líquido** da cobrança, isto é, o valor menos a taxa transacional (fixa + percentual). O uso do valor bruto é configurado pela Finvia, sob consulta. O repasse acontece a cada parcela liquidada. Prazos e exemplos em [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md) e [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

## Formas de pagamento

| Formato | `type` | Campos obrigatórios | Uso típico |
| - | - | - | - |
| Cartão de crédito | `credit_card` | `number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`, `installments` | Checkout com digitação do cartão |
| Cartão salvo | `credit_card` | `cardTokenId`, `cvv`, `installments` | Recompra com um clique |
| Apple Pay | `credit_card` | `wallet`, `installments` | Checkout web com Apple Pay |
| Pix | `pix` | `type` e `expirationInDays` ou `expirationInSeconds` | Pagamento instantâneo |

### Cartão de crédito

**paymentMethod.type** `string` *required*

`credit_card`.

**paymentMethod.number** `string` *required*

Número do cartão, só com dígitos e sem espaços. Ex.: `4444333322221111`.

**paymentMethod.holderName** `string` *required*

Nome impresso no cartão. Ex.: `MARIA SOUZA`.

**paymentMethod.expirationMonth** `string` *required*

Mês de validade com 2 caracteres (`minLength` 2, `maxLength` 2). Ex.: `10`.

**paymentMethod.expirationYear** `string` *required*

Ano de validade com 4 caracteres (`minLength` 4, `maxLength` 4). Ex.: `2028`.

**paymentMethod.cvv** `string` *required*

Código de segurança. Mínimo de 3 caracteres.

**paymentMethod.installments** `integer` *required*

Número de parcelas. Mínimo `1`, máximo `12`. Valor `0`, negativo ou acima de `12` recebe `400`.

**paymentMethod.threeDSMode** `string`

Use `managed` para a Finvia conduzir a autenticação 3D Secure. Com esse valor, envie também `browser` e não envie `threeDS`.

O 3DS só começa quando a política 3DS da sua conta dispara (3DS habilitado e obrigatório, ou valor igual ou acima do mínimo configurado). A partir daí:

* Se o emissor pedir verificação do dispositivo ou desafio, a resposta vem com `status` `authentication_required`, `reason` `Autenticação 3DS gerenciada necessária` e `authenticationUrl`.
* Na autenticação sem atrito (frictionless), a cobrança segue direto e a resposta já traz o status final.
* Sem `browser`, ou se o serviço de 3DS falhar, a cobrança segue sem 3DS. Se o 3DS for obrigatório para a conta, ela é recusada.

Veja [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md).

**paymentMethod.browser** `object`

Dados do navegador do comprador, usados na autenticação 3DS (schema `BrowserInfo`).

**propriedades**

**userAgent** `string` *required*

User agent do navegador.

**ipAddress** `string` *required*

IP do comprador (IP válido). Ex.: `177.128.144.97`.

**acceptHeader** `string`

Valor do cabeçalho Accept do navegador.

**language** `string`

Idioma do navegador. Ex.: `pt-BR`.

**timezoneOffset** `integer`

Diferença do fuso em minutos em relação ao UTC. Ex.: `-180`.

**javascriptEnabled** `boolean`

Se o JavaScript está habilitado.

**javaEnabled** `boolean`

Se o Java está habilitado.

**screenWidth** `integer`

Largura da tela em pixels.

**screenHeight** `integer`

Altura da tela em pixels.

**colorDepth** `integer`

Profundidade de cor da tela, em bits.

**paymentMethod.threeDS** `object`

Resultado de uma autenticação 3DS feita por você antes da cobrança (schema `CreditCardThreeDS`), pelo [SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) ou [via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md). Repasse o objeto recebido em `POST /v1/three-ds/challenge-result`. Nos campos opcionais, **omita o campo quando não tiver valor e não envie `null`**: o `null` é gravado e repassado ao adquirente.

**propriedades**

**type** `string` *required*

Tipo de autenticação 3DS (ex.: `full`).

**state** `string` *required*

Resultado da autenticação: `success`, `failure`, `unenrolled`, `error`, `unsupported_brand` ou `disabled`. Só `success` permite seguir com a cobrança quando o 3DS é obrigatório para a conta.

**cryptogram** `string`

CAVV (valor de autenticação) em Base64. Com `state``success`, envie sempre.

**eci** `string`

Electronic Commerce Indicator. Valores comuns: `05` (autenticado), `06` (tentativa), `07` (não autenticado). Com `state``success`, envie sempre.

**version** `string`

Versão do protocolo 3DS (ex.: `2.2.0`).

**directoryServerTransactionId** `string`

ID da transação no Directory Server (bandeira).

**threeDsServerTransactionId** `string`

ID da transação no 3DS Server.

**acsTransactionId** `string`

ID da transação no ACS (banco emissor).

> [!NOTE]
>
> O contrato também lista em `threeDS` os campos `mode`, `deviceData` e `challenge.returnUrl`. No 3DS da Finvia (SDK, via API ou gerenciado) eles não têm uso: não envie.

### Cartão salvo

Usa um cartão guardado no cofre da Finvia. O `cardTokenId` é o campo `id` devolvido por [`POST /v1/cards`](https://docs.fastpaybrasil.com/referencia/cartoes/registrar).

> [!WARNING]
>
> O **CVV do comprador é obrigatório em toda cobrança** com `cardTokenId`. Sem ele, a API responde `400` `CVV is required when using cardTokenId`. Esta rota não faz cobrança com o comprador ausente. Para cobrar automaticamente a cada ciclo, use [Assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md).

**paymentMethod.type** `string` *required*

`credit_card`.

**paymentMethod.cardTokenId** `string` *required*

ID do cartão salvo (resposta de `POST /v1/cards`). Cartão revogado ou expirado recebe `400`. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**paymentMethod.cvv** `string` *required*

Código de segurança, obrigatório mesmo para cartão salvo. Mínimo de 3 caracteres.

**paymentMethod.installments** `integer` *required*

Número de parcelas. Mínimo `1`, máximo `12`.

**paymentMethod.threeDSMode** `string`

`managed` para 3DS gerenciado. Envie `browser` junto.

Os campos `browser` e `threeDS` também são aceitos, com as mesmas regras do cartão digitado.

> [!NOTE]
>
> No Modo Teste (`sk_test_`), a cobrança com `cardTokenId` é simulada e não movimenta dinheiro. O cofre de cartões é o mesmo para teste e produção: o mesmo `cardTokenId` usado com a chave de produção gera uma cobrança real. Veja [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md).

### Apple Pay

Envie em `wallet.token` o objeto `payment.token` devolvido pelo Apple Pay JS no evento `onpaymentauthorized`, **sem alterações**. Com `wallet`, os campos do cartão (`number`, `holderName`, `expirationMonth`, `expirationYear`, `cvv`) não são exigidos.

* Só a versão `EC_v1` é aceita.
* A moeda precisa ser `BRL` (erro `APPLE_PAY_CURRENCY_NOT_SUPPORTED`).
* `customer.document` é obrigatório (erro `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED`).
* O 3D Secure não se aplica: a autenticação já vem no token. A Finvia não decifra o token, ele é repassado ao processador.
* Antes de cobrar, registre e verifique o domínio ([`POST /v1/apple-pay/domains`](https://docs.fastpaybrasil.com/referencia/apple-pay/registrar-dominio)) e valide a sessão ([`POST /v1/apple-pay/validate-merchant`](https://docs.fastpaybrasil.com/referencia/apple-pay/validar-sessao)). O passo a passo está no [guia de Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md).

**paymentMethod.type** `string` *required*

`credit_card`.

**paymentMethod.installments** `integer` *required*

Número de parcelas. Mínimo `1`, máximo `12`, a mesma regra do cartão digitado.

**paymentMethod.wallet** `object` *required*

Payload da carteira Apple Pay com o token seguro.

**propriedades**

**type** `string` *required*

`applepay`.

**token** `object` *required*

Token de pagamento do Apple Pay, enviado como veio da Apple.

**propriedades**

**paymentData** `object` *required*

Dados de pagamento criptografados.

**propriedades**

**data** `string` *required*

Dados criptografados em Base64 (formato `byte`).

**signature** `string` *required*

Assinatura PKCS #7 destacada (detached), codificada em Base64 (formato `byte`).

**version** `string` *required*

Versão do formato do token: `EC_v1`.

**header** `object` *required*

Cabeçalho com dados de troca de chaves.

**propriedades**

**ephemeralPublicKey** `string` *required*

Chave pública efêmera EC em Base64 (formato `byte`).

**publicKeyHash** `string` *required*

Hash SHA-256 do certificado da chave pública do merchant, em Base64 (formato `byte`).

**transactionId** `string` *required*

Identificador da transação em hexadecimal.

**paymentMethod** `object` *required*

Dados do cartão usado.

**propriedades**

**displayName** `string` *required*

Descrição do cartão. Ex.: `Visa 1234`.

**network** `string` *required*

Bandeira. Ex.: `Visa`.

**type** `string` *required*

Tipo do cartão: `debit`, `credit`, `prepaid` ou `store`.

**transactionIdentifier** `string` *required*

Identificador único da transação Apple Pay.

### Pix

**paymentMethod.type** `string` *required*

`pix`.

**paymentMethod.expirationInDays** `number`

Validade em dias. Mínimo `1`. Obrigatório se `expirationInSeconds` não for enviado.

**paymentMethod.expirationInSeconds** `number`

Validade em segundos. Mínimo `900` (15 minutos). Obrigatório se `expirationInDays` não for enviado.

Como escolher a validade para cada cenário: veja o [guia de Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md#como-escolher-a-validade). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação.

## Respostas

A resposta `201` tem sempre `id`, `status`, `paymentDetails` e `reason`. `authenticationUrl` e `customerId` aparecem só em alguns casos.

**id** `string` *required*

Identificador único da cobrança criada. Guarde este valor: ele é usado para consultar, estornar e conciliar a cobrança com os webhooks.

**status** `string` *required*

Situação da cobrança na criação: `paid`, `pending`, `refused`, `failed`, `in_analysis` ou `authentication_required`. Os status `refunded`, `pre_chargeback` e `chargeback` nunca saem na criação.

**paymentDetails** `object | null` *required*

Detalhes específicos da forma de pagamento. Vem `null` em recusas e quando o status é `authentication_required`.

**Cartão de crédito**

**firstSix** `string` *required*

Seis primeiros dígitos do cartão.

**lastFour** `string` *required*

Quatro últimos dígitos do cartão.

**expirationMonth** `string` *required*

Mês de validade.

**expirationYear** `string` *required*

Ano de validade.

**holderName** `string` *required*

Nome do titular.

**installments** `number` *required*

Número de parcelas usado.

**brand** `string`

Bandeira do cartão. Opcional; aparece no Apple Pay.

**Pix**

**copyPaste** `string` *required*

Código Pix "copia e cola" (BR Code EMV). O pagador cola no app do banco para pagar.

**qrCodeBase64** `string | null`

Imagem do QR Code (PNG, 256x256) em data URI, gerada a partir do `copyPaste`. Pode ser usada direto no `src` de uma tag `<img>`. Vem `null` ou ausente quando o QR Code não pôde ser gerado; nesse caso, mostre o `copyPaste`.

**endToEndId** `string`

Identificador End to End do Pix, preenchido quando o pagamento é confirmado.

**expiresAt** `string`

Data e hora de expiração do Pix, em ISO 8601. Opcional.

**reason** `string | null` *required*

Motivo do status. Em recusas, explica a causa (ex.: `card_declined`, ou um texto iniciado em `3ds_` quando a recusa vem da autenticação). Em `in_analysis`, vem `antifraud_manual_review`. Em `authentication_required` no 3DS gerenciado, vem `Autenticação 3DS gerenciada necessária`.

**authenticationUrl** `string`

Endereço para onde o comprador deve ir para concluir a autenticação. Vem só quando `status` é `authentication_required`. Use exatamente o valor recebido, sem montar nem alterar a URL. Além do 3DS gerenciado, alguns adquirentes também podem pedir autenticação do lado deles e devolver este campo.

**customerId** `string`

ID do cliente criado ou reaproveitado na cobrança. Vem quando a cobrança chega ao adquirente ou é recusada por valor máximo. Não vem quando a cobrança é barrada antes: pelo antifraude (`refused` ou `in_analysis`), pela validação de 3DS obrigatório ou quando vai para o 3DS gerenciado (`authentication_required`).

| `status` na criação | O que significa | O que fazer |
| - | - | - |
| `paid` | Pagamento aprovado | Confirmar o pedido |
| `pending` | Aguardando pagamento (Pix gerado) ou pendente no adquirente | Aguardar `charge.paid` |
| `refused` | Recusada (emissor, antifraude ou 3DS obrigatório) | Mostrar `reason` e oferecer outra forma de pagamento |
| `failed` | Falha no processamento | Oferecer nova tentativa ou outra forma de pagamento |
| `in_analysis` | Enviada para revisão manual do antifraude | Aguardar. O desfecho chega pelo `charge.updated` na `postbackUrl` ou pela consulta |
| `authentication_required` | Aguardando autenticação do comprador | Levar o comprador à `authenticationUrl` |

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Cobrança criada. Uma recusa também volta como `201`: leia `status` | `id`, `status`, `paymentDetails`, `reason` e, quando houver, `authenticationUrl` e `customerId` |
| `400` | Corpo inválido. Inclui item `physical` sem `shippingAddress`, `cardTokenId` sem `cvv`, e os códigos `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` e `APPLE_PAY_TOKEN_INVALID` | Erro de validação com `message` em lista, ou mensagem única |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |
| `422` | Regra de negócio: `Fees not configured` (sem taxa para o método e a moeda) ou `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Mensagem do erro |
| `500` | Erro interno | `{"statusCode": 500, "message": "Internal server error"}` |

Trate o erro pelo código HTTP (e pelo código `APPLE_PAY_*`, quando houver), não pelo texto: as mensagens da API misturam português e inglês.

> [!NOTE]
>
> **Para o negócio:** no cartão, aprovação e recusa voltam **na própria resposta** da criação. Se `status` vier `refused`, o campo `reason` explica o motivo e o checkout pode oferecer outra forma de pagamento sem sair da página. No Pix, a resposta traz o QR Code com `status` `pending`, e a confirmação do pagamento chega depois, por webhook.

## Exemplos por caso de uso

> [tab] Pix (infoproduto)
>
> Venda de um curso online. Produto digital, sem endereço de entrega. O Pix expira em 1 hora.
>
> ```json theme={null}
> {
>   "amount": 297,
>   "currency": "BRL",
>   "customer": {
>     "name": "Joao Silva",
>     "email": "joao@email.com",
>     "document": { "type": "cpf", "id": "52998224725" },
>     "phone": "+5511987654321",
>     "address": { "country": "BRA" }
>   },
>   "paymentMethod": { "type": "pix", "expirationInSeconds": 3600 },
>   "items": [
>     {
>       "title": "Curso de Excel Avançado",
>       "type": "digital",
>       "description": "Acesso ao curso por 12 meses",
>       "unit_price": 297,
>       "quantity": 1
>     }
>   ],
>   "metadata": { "orderId": "ORD-123" },
>   "postbackUrl": "https://meusite.com.br/webhooks/finvia"
> }
> ```
>
> Libere o acesso ao curso só depois de receber `charge.paid` e confirmar o status com [`GET /v1/charges/{id}`](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar).

> [tab] Cartão parcelado (e-commerce)
>
> Produto físico em 3x, com endereço de entrega.
>
> ```json theme={null}
> {
>   "amount": 599.7,
>   "currency": "BRL",
>   "customer": {
>     "name": "Maria Souza",
>     "email": "maria@email.com",
>     "document": { "type": "cpf", "id": "52998224725" },
>     "ipAddress": "177.128.144.97"
>   },
>   "paymentMethod": {
>     "type": "credit_card",
>     "number": "4444333322221111",
>     "holderName": "MARIA SOUZA",
>     "expirationMonth": "10",
>     "expirationYear": "2028",
>     "cvv": "123",
>     "installments": 3
>   },
>   "items": [
>     { "title": "Tênis de corrida", "type": "physical", "description": "Tamanho 38", "unit_price": 199.9, "quantity": 3 }
>   ],
>   "shippingAddress": {
>     "postalCode": "01310100",
>     "addressLine1": "Av. Paulista, 1000",
>     "addressLine2": "Apto 51",
>     "neighborhood": "Bela Vista",
>     "city": "São Paulo",
>     "state": "SP",
>     "country": "BRA"
>   },
>   "metadata": { "orderId": "ORD-3091" }
> }
> ```

> [tab] Cartão salvo (recompra)
>
> ```json theme={null}
> {
>   "amount": 89.9,
>   "currency": "BRL",
>   "customer": { "id": "2RhQgK4vN8pT1wZ6yB3mC7dF" },
>   "paymentMethod": {
>     "type": "credit_card",
>     "cardTokenId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
>     "cvv": "123",
>     "installments": 1
>   },
>   "items": [
>     { "title": "Refil de filtro", "type": "physical", "description": "Refil trimestral", "unit_price": 89.9, "quantity": 1 }
>   ],
>   "shippingAddress": {
>     "postalCode": "01310100",
>     "addressLine1": "Av. Paulista, 1000",
>     "city": "São Paulo",
>     "state": "SP",
>     "country": "BRA"
>   }
> }
> ```

> [tab] Split (marketplace)
>
> Venda criada com a chave da subconta do vendedor, separando 10% para outra conta do mesmo grupo Connect.
>
> ```json theme={null}
> {
>   "amount": 100,
>   "currency": "BRL",
>   "customer": { "name": "Ana Lima", "email": "ana@email.com" },
>   "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 },
>   "items": [
>     { "title": "Aula de cerâmica online", "type": "digital", "description": "Turma de sábado", "unit_price": 100, "quantity": 1 }
>   ],
>   "split": [
>     { "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI", "percentage": 10 }
>   ]
> }
> ```

## 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 (`BR`) | Envie o código de três letras: `BRA` |
| `400` com `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Peça o CVV ao cliente em toda compra |
| `400` de validação em `installments` | Parcelas `0`, negativas ou acima de `12` | Envie um inteiro de `1` a `12` |
| `422` com `Fees not configured` | A conta não tem taxa para o método e a moeda | Fale com o suporte da Finvia para configurar a taxa |
| Valor cobrado 100 vezes maior | `amount` enviado em centavos | Envie em reais: `10` = R\$ 10,00 |
| `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) |
| Cobrança duplicada após timeout | Reenvio do POST sem verificar se a primeira foi criada | Siga o [procedimento para timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência) |
| Apple Pay recusado com `APPLE_PAY_CURRENCY_NOT_SUPPORTED` | Moeda diferente de `BRL` | Envie `currency` `BRL` |
| Apple Pay recusado com `APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED` | `customer.document` ausente | Envie o CPF ou CNPJ do cliente |

```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}
// criar-cobranca.mjs (Node.js 18+, ESM, await no topo)
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' },
  }),
});

const charge = await response.json();
console.log(charge.id, charge.status);
```

```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
```

```json 201 Pix 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"
}
```

```json 201 Cartão theme={null}
{
  "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
  "status": "paid",
  "paymentDetails": {
    "firstSix": "444433",
    "lastFour": "1111",
    "expirationMonth": "10",
    "expirationYear": "2028",
    "holderName": "MARIA SOUZA",
    "installments": 3
  },
  "reason": "success",
  "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
```

```json 201 3DS gerenciado theme={null}
{
  "id": "2vorkQw7Ns2RtY5uIo9Pa3SdFgH",
  "status": "authentication_required",
  "paymentDetails": null,
  "reason": "Autenticação 3DS gerenciada necessária",
  "authenticationUrl": "https://<endereço recebido na resposta>"
}
```

```json 400 Endereço ausente theme={null}
{
  "message": "Shipping info must be provided for merchants selling physical items.",
  "error": "Bad Request",
  "statusCode": 400
}
```

```json 400 Validação theme={null}
{
  "statusCode": 400,
  "message": ["shippingAddress.country must be a valid ISO31661 Alpha3 code"],
  "error": "Bad Request"
}
```

## Veja também

> [card] [Consultar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/consultar.md)
>
> Status atual e detalhes de uma cobrança.

> [card] [Estornar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/estornar.md)
>
> Estorno total de uma cobrança paga.

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Eventos do ciclo de vida da cobrança.

> [card] [Homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenários CHG-01 a CHG-10 e SPL-01 a SPL-06.


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