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

# Cartão de crédito

> Cobre com cartão digitado no checkout, à vista ou em até 12 parcelas, e trate aprovação e recusa na própria resposta.

Na cobrança com cartão de crédito digitado, o cliente informa os dados do cartão no seu checkout e o seu servidor envia esses dados à Finvia na criação da cobrança. A aprovação ou a recusa volta **na própria resposta**, e o seu checkout já sabe se pode confirmar o pedido ou oferecer outra forma de pagamento.

> [!NOTE]
>
> **Para o negócio:** o cartão permite parcelar em até 12 vezes e dá a resposta na própria criação da cobrança. Quando a compra é recusada, o campo `reason` explica o motivo, e o checkout pode sugerir outro cartão ou o Pix sem o cliente sair da página.

## Quando usar

| Situação | Recomendação |
| - | - |
| Checkout com parcelamento | Cartão digitado com `installments` de 1 a 12 |
| Primeira compra de um cliente | Cartão digitado. Se quiser recompra com um clique, registre o cartão depois ([Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)) |
| Cliente já tem cartão guardado na sua loja | [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) |
| Checkout com iPhone ou Mac | [Apple Pay](https://docs.fastpaybrasil.com/guias/cobrancas/apple-pay.md) |
| Cobrança mensal sem o cliente presente | [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |
| A sua conta exige autenticação do titular | Cartão com [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) |

## Como funciona

O desenho abaixo mostra a cobrança com cartão digitado e os quatro resultados que podem voltar na resposta da criação.

```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}}}%%
sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant C as Comprador
    end
    box rgb(243,245,248) Sua aplicação
        participant L as Seu checkout e servidor
        participant W as Seu receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant E as Adquirente e emissor
    end
    C->>L: Número, nome, validade, CVV e parcelas
    L->>F: POST /v1/charges · credit_card · installments 1 a 12
    Note over F,E: Antes do adquirente, a Finvia aplica o antifraude e a regra de 3DS da conta
    alt Aprovada
        F->>E: Pede a autorização
        E-->>F: Autorizada
        F-->>L: 201 · paid · reason success
        L-->>C: Pedido confirmado
        F-)W: charge.paid
    else Recusada ou falha
        F-->>L: 201 · refused ou failed · motivo em reason
        L-->>C: Mostra o motivo e oferece outro cartão ou Pix
        F-)W: charge.refused ou charge.failed
    else Em análise ou pendente
        F-->>L: 201 · in_analysis ou pending
        L-->>C: Pedido aguardando confirmação
        F-)W: Desfecho depois · charge.updated, só na postbackUrl
    else threeDSMode managed e o banco pede verificação
        F-->>L: 201 · authentication_required · authenticationUrl
        L-->>C: Leva o comprador à authenticationUrl
    end
```

Uma recusa por 3D Secure obrigatório também chega no ramo de recusa, com `reason` começando em `3ds_`. O caminho com `authentication_required` continua no guia de [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md).

**1. O cliente preenche o cartão no seu checkout**

Número, nome impresso, validade, CVV e quantidade de parcelas.

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

Você chama `POST /v1/charges` com `paymentMethod.type` `credit_card` e os dados do cartão, usando a chave secreta.

**3. A resposta traz o resultado**

`status` `paid` (aprovada), `refused` (recusada) ou `failed` (falha no processamento). Em recusas, `reason` explica o motivo. A resposta também pode vir `in_analysis` (revisão manual do antifraude) ou, com 3DS gerenciado, `authentication_required`.

**4. O checkout mostra o resultado**

Aprovada: confirme o pedido. Recusada: mostre o motivo e ofereça outra forma de pagamento.

**5. Os webhooks acompanham o pós-venda**

`charge.paid`, `charge.refused` ou `charge.failed` registram o resultado nos endpoints e na `postbackUrl`. Estornos, bloqueios e alertas de chargeback chegam depois.

## Campos do cartão

| Campo | Tipo | Obrigatório | Regra |
| - | - | - | - |
| `type` | string | Sim | `credit_card` |
| `number` | string | Sim | Número do cartão, só com dígitos. Espaços são recusados com `400` |
| `holderName` | string | Sim | Nome impresso no cartão |
| `expirationMonth` | string | Sim | 2 caracteres. Ex.: `"03"` |
| `expirationYear` | string | Sim | 4 caracteres. Ex.: `"2028"` |
| `cvv` | string | Sim | Mínimo de 3 caracteres |
| `installments` | integer | Sim | De `1` a `12` |
| `threeDSMode` | string | Não | `managed` para o [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) |
| `browser` | object | Não | Dados do navegador para o 3DS (`userAgent` e `ipAddress` obrigatórios). Envie junto com `threeDSMode` |
| `threeDS` | object | Não | Resultado de uma autenticação 3DS feita antes ([SDK](https://docs.fastpaybrasil.com/guias/3d-secure/sdk.md) ou [via API](https://docs.fastpaybrasil.com/guias/3d-secure/via-api.md)) |

> [!WARNING]
>
> Mês e ano são **strings** com tamanho fixo. `"3"` e `"28"` são rejeitados. Envie `"03"` e `"2028"`.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Parcelamento | De 1 a 12 parcelas (`installments`). A conta precisa ter taxa configurada para o número de parcelas |
| Valor | Em reais: `"amount": 599.7` é R\$ 599,70. Mínimo `1` |
| Resultado | Síncrono: `paid`, `refused` ou `failed` na resposta da criação. Também pode vir `in_analysis` ou `authentication_required` |
| Motivo da recusa | Campo `reason` da resposta (ex.: `card_declined`) |
| Produto físico | Se algum item for `physical`, `shippingAddress` é obrigatório (`postalCode`, `addressLine1`, `city`, `state`, `country`) |
| 3D Secure | Pode ser exigido pela configuração da conta. Sem autenticação, a cobrança é recusada (ver [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)) |
| Tentativas repetidas | Tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas: a listagem mostra só a principal |
| Estorno | Total, só de cobrança `paid` ([Estorno](https://docs.fastpaybrasil.com/guias/estorno.md)) |

### Recusa: resposta síncrona e notificação

A recusa volta na resposta da criação, com `status` `refused` (ou `failed`) e o motivo em `reason`. O seu checkout deve tratar esse resultado ali mesmo, sem esperar webhook. Os webhooks complementam a resposta:

| Situação | O que chega |
| - | - |
| Recusa ou falha na criação | `charge.refused` (status `refused`) ou `charge.failed` (status `failed`), no envelope padrão, para os endpoints do painel e a `postbackUrl`. Sai no máximo uma vez por cobrança |
| Recusa ao final do 3DS gerenciado | `charge.refused` ou `charge.failed` nos endpoints e na `postbackUrl`, mais o `charge.updated` legado na `postbackUrl` |
| Recusa ou falha informada depois pelo adquirente (cobrança que ficou `in_analysis` ou `pending`) | Só o `charge.updated` legado, na `postbackUrl`. Os endpoints do painel não recebem nada. O status final pode ser `failed` |
| Cobrança recorrente de assinatura recusada | `subscription.payment_failed`. Não gera `charge.refused` nem `charge.failed` |

O envelope padrão não traz o motivo da recusa. Ele aparece na resposta da criação, na consulta da cobrança e no `charge.updated`. Para cobranças que ficam em `in_analysis` ou `pending`, acompanhe pela `postbackUrl` ou consulte `GET /v1/charges/{id}`.

## Dados do cliente e IP

O objeto `customer` da cobrança de cartão aceita estes campos:

| Campo | Exemplo | Observação |
| - | - | - |
| `customer.name` | `Maria Souza` | Nome do cliente |
| `customer.email` | `maria@email.com` | Obrigatório sem `id` e sem `phone` |
| `customer.phone` | `+5511987654321` | Pode substituir o e-mail quando não há `id` |
| `customer.document` | `{ "type": "cpf", "id": "52998224725" }` | Documento do cliente |
| `customer.address.country` | `BRA` | ISO 3166-1 alpha-3 |
| `customer.ipAddress` | `177.128.144.97` | IP do cliente no momento da compra |

> [!TIP]
>
> **Para o desenvolvedor:** o IP do cliente é o do navegador, não o do seu servidor. Se a sua aplicação fica atrás de proxy ou balanceador, leia o IP no cabeçalho que o proxy repassa (ex.: `X-Forwarded-For`), conforme a configuração da sua infraestrutura.

## Segurança no checkout

Nesta forma de pagamento, os dados completos do cartão passam pelo seu servidor, porque é ele que chama a API. Isso traz responsabilidades para a sua aplicação:

* **Use HTTPS** em todas as páginas do checkout e em todas as chamadas, do navegador ao seu servidor e do seu servidor à API.
* **Não grave** o número do cartão nem o CVV em banco de dados, arquivos ou caches. Use os dados só na chamada e descarte.
* **Não registre em log** o corpo da requisição de cobrança sem mascarar `number` e `cvv`. Registre apenas os 6 primeiros e os 4 últimos dígitos, que a própria resposta devolve (`firstSix` e `lastFour`).
* **Mantenha a chave secreta no servidor.** O navegador nunca chama `POST /v1/charges` direto.
* **Para recompra**, use o [cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md), que guarda o cartão na Finvia e devolve um identificador.

> [!WARNING]
>
> Verifique com a sua área de segurança e conformidade os requisitos que se aplicam à sua empresa por trafegar dados de cartão no seu servidor.

```javascript theme={null}
// Exemplo de log seguro: nunca registre number e cvv
function logCobranca(payload, resposta) {
  const { number, cvv, ...cartaoSemDadosSensiveis } = payload.paymentMethod;
  console.log({
    amount: payload.amount,
    paymentMethod: cartaoSemDadosSensiveis,
    chargeId: resposta.id,
    status: resposta.status,
    reason: resposta.reason,
  });
}
```

## Passo a passo

### Cobrança parcelada de produto físico

```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": 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"
  },
  "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": 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" },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia"
  }'
```

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

async function cobrarCartao(pedido, cartao, ipCliente) {
  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: pedido.total,
      currency: 'BRL',
      customer: {
        name: pedido.nome,
        email: pedido.email,
        document: { type: 'cpf', id: pedido.cpf },
        ipAddress: ipCliente,
      },
      paymentMethod: {
        type: 'credit_card',
        number: cartao.numero.replace(/\s/g, ''),
        holderName: cartao.nome,
        expirationMonth: cartao.mes.padStart(2, '0'),
        expirationYear: cartao.ano,
        cvv: cartao.cvv,
        installments: cartao.parcelas,
      },
      items: pedido.itens,
      shippingAddress: pedido.endereco,
      metadata: { orderId: pedido.id },
      postbackUrl: 'https://meusite.com.br/webhooks/finvia',
    }),
  });

  const charge = await response.json();

  switch (charge.status) {
    case 'paid':
      return { ok: true, chargeId: charge.id };
    case 'refused':
      return { ok: false, motivo: charge.reason, chargeId: charge.id };
    case 'authentication_required':
      // 3DS gerenciado: leve o comprador à URL recebida, sem alterá-la
      return { ok: false, autenticar: charge.authenticationUrl, chargeId: charge.id };
    case 'in_analysis':
    case 'pending':
      // Aguarde o desfecho pela postbackUrl ou consulte a cobrança depois
      return { ok: false, aguardando: true, chargeId: charge.id };
    default: // failed
      return { ok: false, motivo: charge.reason ?? 'Falha no processamento', chargeId: charge.id };
  }
}
```

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

import requests

payload = {
    "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",
    },
    "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' => 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',
    ],
    '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": 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"
              },
              "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": 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"
  },
  "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": 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"
	  },
	  "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" => 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",
  },
  "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
```

### Respostas possíveis

> [tab] Aprovada
>
> ```json theme={null}
> {
>   "id": "2vorkDcXyvzifL63YX09S9VqcnI",
>   "status": "paid",
>   "paymentDetails": {
>     "firstSix": "444433",
>     "lastFour": "1111",
>     "expirationMonth": "10",
>     "expirationYear": "2028",
>     "holderName": "MARIA SOUZA",
>     "installments": 3
>   },
>   "reason": "success",
>   "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
> }
> ```

> [tab] Recusada
>
> ```json theme={null}
> {
>   "id": "2vorkLm4Qp8TzR1sXc7Yb3NdWkE",
>   "status": "refused",
>   "paymentDetails": null,
>   "reason": "card_declined"
> }
> ```

> [tab] Em análise
>
> ```json theme={null}
> {
>   "id": "2vorkAn5Ls6Is7Ma8Nu9AlRvWxY",
>   "status": "in_analysis",
>   "paymentDetails": null,
>   "reason": "antifraud_manual_review"
> }
> ```

> [tab] Sem endereço (400)
>
> ```json theme={null}
> {
>   "message": "Shipping info must be provided for merchants selling physical items.",
>   "error": "Bad Request",
>   "statusCode": 400
> }
> ```

> [!NOTE]
>
> `paymentDetails` é anulável. Trate o caso em que ele vem `null` e use `status` e `reason` para decidir o que mostrar ao cliente. `customerId` não vem quando a cobrança é barrada antes de chegar ao adquirente (antifraude ou 3DS).

## Cartões de teste

No Modo Teste (chave `sk_test_`), a cobrança vai para um processador simulado e o resultado depende só do número do cartão. Envie o número só com dígitos.

| Número | Resultado | `status` / `reason` |
| - | - | - |
| `4444333322221111` | Aprovado | `paid` / `success` |
| `4444333322221112` | Recusado | `refused` / `card_declined` |
| Qualquer número terminado em `2222` (ex.: `4444333322222222`) | Pendente | `pending` / `pending`. Fica pendente: não há confirmação posterior simulada |
| Qualquer outro número | Aprovado | `paid` / `success` |

Nome, CVV e validade não influenciam o resultado: use qualquer nome, CVV numérico de 3 dígitos e validade futura (mês com 2 dígitos, ex.: `05`, e ano com 4). O parcelamento de 1 a 12 vezes funciona igual, desde que a conta tenha taxa configurada para o número de parcelas. A recusa é síncrona e vem na própria resposta.

> [!WARNING]
>
> Esses números só valem com a chave de teste. Com a chave de produção, a cobrança vai para a adquirente real. As regras de 3D Secure e de antifraude da sua conta continuam valendo no Modo Teste: se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com `reason` começando em `3ds_` ou `antifraud_denied`.

## Estorno e chargeback

* **Estorno:** uma cobrança paga pode ser estornada por `POST /v1/refunds`, sempre pelo valor total. O pedido vai à adquirente na hora, e o crédito aparece na fatura do comprador conforme o prazo do banco emissor. Você recebe `charge.refunded`. Veja [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md).
* **Pré-chargeback:** quando o titular contesta a compra no emissor, a cobrança pode receber um alerta (`pre_chargeback`), avisado pelo `charge.pre_chargeback`.
* **Bloqueio:** durante a disputa, a equipe Finvia pode bloquear a cobrança (`isBlocked: true`, status ainda `paid`), avisado pelo `charge.blocked`.
* **Chargeback formalizado:** chega pelo `charge.updated` com `status: "chargeback"` na `postbackUrl` e, quando o valor é revertido do saldo, também pelo `charge.refunded`.

O fluxo completo está em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `status` `refused` com `reason` | Recusa do emissor, do antifraude ou do processador | Mostre o motivo e ofereça outro cartão ou Pix |
| `refused` com `reason` iniciando em `3ds_required` | A conta exige 3D Secure e a cobrança veio sem autenticação | Integre o [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md) |
| `400` de validação | `number` com espaços, `expirationMonth` ou `expirationYear` com tamanho errado, `cvv` curto, `installments` fora de 1 a 12 | Número só com dígitos, mês com 2 caracteres, ano com 4, CVV com pelo menos 3 e parcelas de 1 a 12 |
| `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie o endereço de entrega |
| `422` com `Fees not configured` | Conta sem taxa para cartão na moeda ou no número de parcelas | Fale com o suporte da Finvia |
| `403` | 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 cobrada duas vezes | O POST foi reenviado depois de um timeout | Siga o [procedimento de timeout](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#timeout-na-criação) antes de repetir |

## Perguntas frequentes

> [accordion] Preciso esperar um webhook para saber se o cartão foi aprovado?
>
> Não. Aprovação e recusa voltam na resposta da criação. Os webhooks `charge.paid`, `charge.refused` e `charge.failed` complementam a resposta. A exceção é a cobrança que fica `in_analysis` ou `pending`: o desfecho chega depois, pelo `charge.updated` na `postbackUrl` ou pela consulta.

> [accordion] Quantas parcelas posso oferecer?
>
> De 1 a 12, desde que a sua conta tenha taxa configurada para o número de parcelas. A quantidade usada volta em `paymentDetails.installments`.

> [accordion] Posso guardar o cartão do cliente para a próxima compra?
>
> Use o [cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md) com `POST /v1/cards` e cobre depois com [cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md). Não guarde número e CVV no seu banco de dados.

> [accordion] Posso cobrar o cartão todo mês sem o cliente informar o CVV?
>
> Não pela rota de cobrança: ela exige o CVV em toda cobrança. Para cobrança recorrente, use [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

> [accordion] Como testo uma recusa?
>
> No Modo Teste, use o cartão `4444333322221112`. A resposta vem `refused` com `reason` `card_declined` e o webhook `charge.refused` é enviado. Use uma conta sem 3DS obrigatório, para a recusa não vir da autenticação.

## Como testar

Com a chave de teste (`sk_test_`) e os [cartões de teste](#cartões-de-teste), execute no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md):

* **CHG-01:** cartão `4444333322221111` à vista, com `paid` e webhook `charge.paid`.
* **CHG-02:** cartão parcelado (ex.: 3x), com `installments` refletido.
* **CHG-03:** cartão `4444333322221112`, com `refused` na própria resposta e o webhook `charge.refused`.
* **CHG-07:** estorno total.
* **CHG-10:** item físico sem endereço (`400`) e com endereço (`201`).

Se a sua conta usa 3D Secure, inclua também o cenário de 3DS da sua conta.

## Veja também

> [card] [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
>
> Recompra com um clique.

> [card] [3D Secure](https://docs.fastpaybrasil.com/guias/3d-secure/visao-geral.md)
>
> Autenticação do titular do cartão.

> [card] [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md)
>
> Como devolver uma cobrança paga.

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