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

# Sua primeira cobrança

> Tutorial completo no sandbox: autentique, crie uma cobrança Pix, receba os webhooks, simule outros status e repita com cartão de crédito.

Este tutorial leva você da chave de teste até uma cobrança acompanhada por webhook, sem dinheiro real. Ao final, você terá o fluxo básico que toda integração com a Finvia usa: criar a cobrança, mostrar o meio de pagamento ao cliente, receber a notificação e confirmar o estado.

> [!NOTE]
>
> **Para o negócio:** este é o mesmo caminho que o seu checkout vai percorrer em produção. Os cenários feitos aqui servem de base para os cenários CHG-01 a CHG-09 do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md), a etapa recomendada antes de ir para produção.

## O que você vai precisar

* A **chave secreta de teste** (`sk_test_`), gerada por um usuário Owner ou Manager. Como gerar: [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#onde-obter-as-chaves).
* Pix habilitado na conta (taxa de Pix em reais configurada). Sem isso, a criação do Pix responde `422` com `Fees not configured`, também no Modo Teste.
* Terminal com `curl`, ou Node.js 18 ou superior.
* Uma URL pública com HTTPS que aponte para a sua máquina, para receber os webhooks. No desenvolvimento, ferramentas como o ngrok fazem isso (`ngrok http 3000`).

> [!WARNING]
>
> Use somente a chave `sk_test_` neste tutorial. Com a chave de produção (`sk_`), as cobranças são reais.

## Visão geral do fluxo

O desenho abaixo mostra a sequência completa do tutorial com Pix no sandbox, da conexão à consulta final.

```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(243,245,248) Sua aplicação
        participant S as Seu script ou servidor
        participant R as Seu receptor (ngrok)
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API (sandbox)
    end
    S->>F: GET /v1/payment-methods (Basic com sk_test_)
    F-->>S: 200 · lista de meios habilitados
    S->>F: POST /v1/charges (type pix, postbackUrl)
    F-->>S: 201 · pending · copyPaste · qrCodeBase64
    Note over S,R: Guarde o id junto com o pedido e mostre o QR Code
    F-)R: charge.created e charge.pending
    R-->>F: 200 OK
    Note over R,F: No Modo Teste, o Pix vira paid sozinho em cerca de 5 s
    F-)R: charge.paid (mesmo id da criação)
    R-->>F: 200 OK, libera o pedido uma vez
    S->>F: POST /v1/charges/{id}/resend-webhook (status refunded)
    F-->>S: 201 · deliveries
    F-)R: charge.refunded simulado, com id novo
    S->>F: GET /v1/charges/{id}
    F-->>S: 200 · status paid (a simulação não altera a cobrança)
```

**1. Autenticar e testar a conexão**

Monte o cabeçalho Basic e chame `GET /v1/payment-methods`.

**2. Subir o receptor de webhooks**

Um servidor mínimo que recebe os avisos da Finvia e responde com status `2xx`.

**3. Criar a cobrança Pix**

`POST /v1/charges` com `postbackUrl` apontando para o seu receptor.

**4. Mostrar o QR Code**

Use `qrCodeBase64` e `copyPaste` da resposta.

**5. Receber os eventos**

Veja `charge.created` e `charge.pending` chegarem e, cerca de 5 segundos depois, o `charge.paid`: no Modo Teste, o Pix é confirmado sozinho.

**6. Simular outros status**

Use a rota de simulação de webhook do sandbox para testar o tratamento de estorno, recusa e falha.

**7. Consultar a cobrança**

`GET /v1/charges/{id}` para confirmar o estado.

**8. Repetir com cartão de crédito**

O resultado do cartão vem na própria resposta.

## 1. Autentique e teste a conexão

A API usa HTTP Basic: a chave vai como usuário, a senha fica vazia. Você converte `sua_chave:` (com os dois pontos no final) para Base64 e envia no cabeçalho `Authorization`.

Configure as variáveis de ambiente:

```bash theme={null}
export FINVIA_API_URL="https://api-global.fastpaybrasil.com"
export FINVIA_API_KEY="sk_test_sua_chave_de_teste"
```

Chame a listagem de meios de pagamento. Resposta `200` significa que a chave e o cabeçalho estão corretos.

```http REST (JSON) theme={null}
GET /v1/payment-methods HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "$FINVIA_API_URL/v1/payment-methods" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
// conexao.mjs (Node.js 18+, ESM, await no topo)
const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(`${API_URL}/v1/payment-methods`, {
  headers: { Authorization: `Basic ${credentials}` },
});

console.log(response.status, await response.json());
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/payment-methods",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

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

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

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$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());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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 request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods");

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"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	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 "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

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

puts response.code
puts response.body
```

A resposta é uma lista com os meios habilitados para a sua conta. Cada item traz `id`, `name`, `countries`, `currencies` e `description`.

> [!TIP]
>
> Recebeu `200` e uma lista em JSON? A autenticação está pronta. Se recebeu `401` com `{"message": "Unauthorized", "statusCode": 401}`, decodifique o Base64 e confira se ele termina em `:`.

## 2. Suba o receptor de webhooks

O **webhook** é a notificação que a Finvia envia ao seu servidor quando algo muda na cobrança. No Pix, ele é a única forma de saber que o cliente pagou sem ficar consultando a API.

Este servidor mínimo em Express recebe as notificações e responde `200` antes de processar. Ele descarta repetições com a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos) e, além disso, só libera um pedido que ainda não foi liberado. Essa segunda proteção cobre o caso de o mesmo aviso chegar com outro `id`.

```javascript server.mjs theme={null}
// server.mjs (Node.js 18+, ESM)
import express from 'express';

const app = express();
app.use(express.json());

// Em produção, guarde estes dados em banco ou Redis.
const processados = new Set();
const pedidosLiberados = new Set();

// Receita de deduplicação da visão geral de webhooks (resumida para cobranças)
function dedupKey(body) {
  if (body.id) return `evt:${body.id}`;
  if (body.event === 'charge.updated') {
    const d = body.data ?? {};
    return ['charge.updated', d.id, d.status, d.isBlocked ?? '', d.chargebackAlertRefunded ?? '', d.updatedAt ?? ''].join(':');
  }
  return null;
}

app.post('/webhooks/finvia', (req, res) => {
  const { event, data } = req.body;

  // Responda rápido. A lógica de negócio roda depois.
  res.status(200).send('OK');

  const key = dedupKey(req.body);
  if (key && processados.has(key)) return;
  if (key) processados.add(key);

  console.log(`Evento ${event} | cobrança ${data?.id} | status ${data?.status}`);

  // Os mesmos endpoints recebem eventos de teste e de produção.
  if (req.body.livemode === false && process.env.NODE_ENV === 'production') return;

  switch (event) {
    case 'charge.created':
      // Cobrança gravada: associe data.id ao pedido (data.metadata volta como foi enviada).
      break;
    case 'charge.pending':
      // QR Code gerado: o pedido aguarda pagamento.
      break;
    case 'charge.paid':
      // Pagamento confirmado: libere o pedido uma única vez.
      // Em produção, confirme antes com GET /v1/charges/{id}.
      if (pedidosLiberados.has(data.id)) {
        console.log('Pedido já liberado, nada a fazer');
        break;
      }
      pedidosLiberados.add(data.id);
      console.log('Pedido liberado');
      break;
    case 'charge.refused':
    case 'charge.failed':
      // Recusa ou falha: o pedido não foi pago.
      break;
    case 'charge.refunded':
      // Estorno concluído: registre a devolução.
      break;
    case 'charge.updated':
      // Canal legado, só na postbackUrl, em camelCase e sem id no envelope.
      break;
    default:
      console.log('Evento não tratado:', event);
  }
});

app.listen(3000, () => console.log('Receptor ouvindo na porta 3000'));
```

```bash theme={null}
npm install express
node server.mjs
ngrok http 3000
```

Anote a URL HTTPS gerada pelo ngrok, por exemplo `https://abc123.ngrok.io`. O endereço do seu receptor será `https://abc123.ngrok.io/webhooks/finvia`.

> [!TIP]
>
> **Para o desenvolvedor:** os eventos `charge.created`, `charge.pending`, `charge.paid` e `charge.refunded` usam campos em snake\_case dentro de `data` (`paid_at`, `payment_details`, `is_test`). A resposta da API usa camelCase (`paidAt`, `paymentDetails`). Não reaproveite o mesmo parser para os dois sem mapear os nomes. Os objetos aninhados (`payment_details`, `payment_method` de cartão) ficam em camelCase, e `metadata` volta exatamente como foi enviada. O `charge.updated` legado vem todo em camelCase, inclusive as chaves de `metadata`. Por isso os exemplos usam `orderId`, que chega igual em todos os canais (veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata)).

## 3. Crie a cobrança Pix

Esta é a cobrança do exemplo de início rápido: R\$ 100,00 em Pix, com validade de 1 dia, para um produto digital. A `postbackUrl` aponta para o seu receptor.

```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
    }
  ],
  "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia"
}
```

```bash cURL theme={null}
curl -X POST "$FINVIA_API_URL/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
      }
    ],
    "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia"
  }'
```

```javascript Node.js theme={null}
// criar-pix.mjs (Node.js 18+, ESM, await no topo)
const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(`${API_URL}/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',
      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,
      },
    ],
    postbackUrl: 'https://abc123.ngrok.io/webhooks/finvia',
  }),
});

const charge = await response.json();
console.log(response.status, charge);
// Guarde charge.id junto com o seu pedido.
```

```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,
        },
    ],
    "postbackUrl": "https://abc123.ngrok.io/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,
        ],
    ],
    'postbackUrl' => 'https://abc123.ngrok.io/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
                }
              ],
              "postbackUrl": "https://abc123.ngrok.io/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
    }
  ],
  "postbackUrl": "https://abc123.ngrok.io/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
	    }
	  ],
	  "postbackUrl": "https://abc123.ngrok.io/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,
    },
  ],
  "postbackUrl" => "https://abc123.ngrok.io/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": {
    "endToEndId": "1231389",
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  },
  "reason": null
}
```

O valor vai em reais: `"amount": 100` significa R\$ 100,00.

Pontos de atenção nesta chamada:

| Campo | Regra |
| - | - |
| `items[].type` | `physical` ou `digital`. Se algum item for `physical`, `shippingAddress` é obrigatório, com `postalCode`, `addressLine1`, `city`, `state` e `country` (`addressLine2` e `neighborhood` são opcionais). Sem o endereço, a API responde `400` e não cria a cobrança |
| `paymentMethod.expirationInDays` | Mínimo `1`. Para validades curtas, use `expirationInSeconds`, com mínimo `900` (15 minutos) |
| `postbackUrl` | Recebe os eventos da cobrança **depois** da criação. Ela não muda a resposta síncrona |

Como escolher a validade do QR Code: veja o [guia de Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md#como-escolher-a-validade).

## 4. Mostre o QR Code

A resposta já traz tudo o que o cliente precisa para pagar:

* `qrCodeBase64`: a imagem PNG do QR Code em formato data URI, pronta para usar como `src` de uma imagem.
* `copyPaste`: o código Pix copia e cola, para quem paga pelo celular.

No Modo Teste, o `copyPaste` e o `qrCodeBase64` são fictícios. Não tente pagar esse código em um aplicativo de banco: a confirmação acontece sozinha, como mostra o passo seguinte.

```html theme={null}
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="QR Code Pix" width="256" height="256" />
<p>Ou copie o código: <code>00020101021226870014br.gov.bcb.pix...6304ABCD</code></p>
```

> [!TIP]
>
> **Para o desenvolvedor:** `qrCodeBase64` pode vir `null` ou ausente quando a imagem não pôde ser gerada. Nesse caso, gere o QR Code no seu front-end a partir do `copyPaste`. Sempre exiba o `copyPaste` também: muitos clientes pagam pelo celular e não conseguem ler a própria tela.

## 5. Receba os webhooks

### O que chega ao receptor

Assim que a cobrança é gravada, sai o `charge.created`. Logo depois, com o QR Code gerado, sai o `charge.pending`. Os dois chegam à `postbackUrl` e aos endpoints cadastrados no painel (**Configurações > Webhooks**). Os eventos de cada canal estão na [tabela de eventos por canal](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#eventos-por-canal).

```json theme={null}
{
  "id": "evt_2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "event": "charge.pending",
  "livemode": false,
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "status": "pending",
    "amount": 100,
    "currency": "BRL",
    "payment_method": { "type": "pix" },
    "payment_details": {
      "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "postback_url": "https://abc123.ngrok.io/webhooks/finvia",
    "paid_at": null,
    "is_test": true
  }
}
```

O exemplo acima mostra os campos principais. O objeto `data` completo está em [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md).

### O Pix de teste é pago sozinho

No Modo Teste não há nada para pagar nem botão de simulação. Cerca de 5 segundos depois da criação, a cobrança passa sozinha para `paid`: `paidAt` é preenchido e `paymentDetails.endToEndId` recebe um valor de teste. Nesse momento chega o `charge.paid`, com o mesmo `id` de cobrança devolvido na criação. É nesse evento que você libera o pedido.

> [!TIP]
>
> O `charge.paid` com o mesmo `id` retornado na criação é a evidência do cenário CHG-05 da homologação. Se, em casos raros, a cobrança não virar `paid` em alguns segundos, crie outra.

> [!NOTE]
>
> No sandbox, todo Pix é aprovado. Não dá para simular expiração ou falha de um Pix. Para testar o tratamento desses casos, use a simulação de webhook abaixo.

### Separe eventos de teste e de produção

Os endpoints de webhook não têm modo: a sua conta tem uma única lista, que recebe tanto os eventos de teste quanto os de produção. O painel não tem uma lista separada para o Modo Teste. Por isso, a integração precisa separar os eventos pelo payload:

| Canal | Como reconhecer um evento de teste |
| - | - |
| Envelope padrão de cobrança (`charge.created`, `charge.paid`...) | `livemode: false` e `data.is_test: true` |
| `charge.updated` legado (só na `postbackUrl`) | `data.isTest: true` |

A `postbackUrl` é definida em cada cobrança. Se quiser URLs diferentes por ambiente, informe uma `postbackUrl` de teste nas cobranças criadas com a chave de teste.

### Simule outros status

Para testar como o seu receptor reage a estorno, recusa ou falha, use a rota de simulação de webhook, disponível só para cobranças de teste. Ela **não reenvia** o evento original e **não altera** a cobrança: gera um evento novo `charge.{status}`, com `id` novo, para a `postbackUrl` e para os endpoints da sua conta.

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

{
  "status": "refunded"
}
```

```bash cURL theme={null}
curl -X POST "$FINVIA_API_URL/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "status": "refunded" }'
```

```javascript Node.js theme={null}
// simular-webhook.mjs (Node.js 18+, ESM, await no topo)
const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const chargeId = '2vorkDcXyvzifL63YX09S9VqcnI';

const response = await fetch(`${API_URL}/v1/charges/${chargeId}/resend-webhook`, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'refunded' }),
});

// 201, com o resultado de cada entrega
console.log(response.status, await response.json());
```

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

import requests

payload = {
    "status": "refunded",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook",
    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 = [
    'status' => 'refunded',
];

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

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 = """
            {
              "status": "refunded"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook"))
            .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 = """
{
  "status": "refunded"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook");
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(`{
	  "status": "refunded"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook", 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/2vorkDcXyvzifL63YX09S9VqcnI/resend-webhook")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "status" => "refunded",
})

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}
{
  "deliveries": [
    { "url": "https://abc123.ngrok.io/webhooks/finvia", "status": 200, "success": true }
  ]
}
```

| Item | Regra |
| - | - |
| Status aceitos em `status` | `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`. Outros valores respondem `400` |
| Resposta de sucesso | `201`, com `deliveries`: uma linha por destino, com `url`, `status`, `success` e, quando houver, `error` |
| Só cobranças de teste | Cobrança de produção responde `403` com `Redisparo de webhook disponível apenas para cobranças de teste` |
| Cobrança inexistente | `404` com `Cobrança não encontrada` |

Um roteiro útil de simulação:

1. `{"status": "paid"}`: confira se o receptor responde `2xx` e se o pedido, já liberado pelo `charge.paid` real, **não** é liberado de novo. O evento simulado tem `id` novo, então quem segura a duplicidade aqui é a checagem do pedido.
2. `{"status": "refunded"}`: confira se o pedido é marcado como estornado.
3. `{"status": "refused"}` e `{"status": "failed"}`: confira se o pedido é marcado como não pago.

> [!NOTE]
>
> O payload simulado não é idêntico ao real: traz campos a mais e não traz `anticipation_fee_estimated`. Use a simulação para testar conectividade e o tratamento de cada evento, e não como referência de formato. O formato real está em [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md).

## 6. Consulte a cobrança

Os webhooks não têm assinatura HMAC ([Webhooks](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#regras-de-negócio)), então confirme o estado da cobrança na API antes de uma ação crítica. A consulta também é o caminho quando o seu receptor ficou fora do ar.

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

```bash cURL theme={null}
curl -X GET "$FINVIA_API_URL/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
// consultar.mjs (Node.js 18+, ESM, await no topo)
const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const chargeId = '2vorkDcXyvzifL63YX09S9VqcnI';

const response = await fetch(`${API_URL}/v1/charges/${chargeId}`, {
  headers: { Authorization: `Basic ${credentials}` },
});
const charge = await response.json();

if (charge.status === 'paid') {
  // Estado confirmado na API: pode liberar.
  console.log('Cobrança paga', charge.id);
}
```

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

import requests

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

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

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

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$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());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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 request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI");

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"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	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 "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

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

puts response.code
puts response.body
```

A resposta `200` traz o objeto completo da cobrança em camelCase: `id`, `status`, `amount`, `currency`, `spread`, `net`, `customer`, `paymentMethod`, `merchantId`, `paymentDetails`, `metadata`, `paidAt`, `createdAt` e `updatedAt`. Nas respostas de consulta, as chaves de `metadata` voltam em camelCase. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata).

> [!WARNING]
>
> Para um `id` que não existe, a API responde hoje `200` com corpo vazio, sem `404`. Trate corpo vazio como "cobrança não encontrada".

## 7. Repita com cartão de crédito

No cartão, a aprovação ou a recusa vem **na própria resposta** da criação. Os webhooks chegam em seguida, como complemento: `charge.paid` na aprovação, `charge.refused` (status `refused`) ou `charge.failed` (status `failed`) na recusa.

O desenho abaixo mostra os dois caminhos da cobrança de cartão no tutorial, aprovada e recusada.

```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 S as Seu servidor
        participant R as Seu receptor
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    C->>S: Envia os dados do cartão
    S->>F: POST /v1/charges (credit_card, installments)
    alt Aprovado (4444333322221111)
        F-->>S: 201 · status paid
        S-->>C: Pedido confirmado
        F-)R: charge.paid
    else Recusado (4444333322221112)
        F-->>S: 201 · status refused · reason card_declined
        S-->>C: Mensagem amigável e outra forma de pagamento
        F-)R: charge.refused ou charge.failed, sem o motivo
    end
    Note over S,F: A resposta síncrona decide o checkout. O webhook é complementar.
```

No Modo Teste, o resultado depende só do número do cartão:

| Número | Resultado |
| - | - |
| `4444333322221111` | Aprovado (`paid`, `reason` `success`) |
| `4444333322221112` | Recusado (`refused`, `reason` `card_declined`) |
| Terminado em `2222` (ex.: `4444333322222222`) | Pendente (`pending`), sem confirmação posterior simulada |
| Qualquer outro número | Aprovado |

A tabela completa e as regras estão em [Cartões de teste](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#cartões-de-teste). Use uma conta sem 3D Secure obrigatório para testar a recusa: com 3DS ou antifraude ligados, a recusa pode vir dessas etapas, com outro `reason`.

```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": 150,
  "currency": "BRL",
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "4444333322221111",
    "holderName": "MARIA SOUZA",
    "expirationMonth": "10",
    "expirationYear": "2030",
    "cvv": "123",
    "installments": 3
  },
  "items": [
    {
      "title": "Curso online",
      "type": "digital",
      "description": "Acesso de 12 meses",
      "unit_price": 150,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "PED-1001"
  },
  "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia"
}
```

```bash cURL theme={null}
curl -X POST "$FINVIA_API_URL/v1/charges" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria.souza@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321",
      "address": { "country": "BRA" }
    },
    "paymentMethod": {
      "type": "credit_card",
      "number": "4444333322221111",
      "holderName": "MARIA SOUZA",
      "expirationMonth": "10",
      "expirationYear": "2030",
      "cvv": "123",
      "installments": 3
    },
    "items": [
      {
        "title": "Curso online",
        "type": "digital",
        "description": "Acesso de 12 meses",
        "unit_price": 150,
        "quantity": 1
      }
    ],
    "metadata": { "orderId": "PED-1001" },
    "postbackUrl": "https://abc123.ngrok.io/webhooks/finvia"
  }'
```

```javascript Node.js theme={null}
// criar-cartao.mjs (Node.js 18+, ESM, await no topo)
const API_URL = process.env.FINVIA_API_URL ?? 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(`${API_URL}/v1/charges`, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 150,
    currency: 'BRL',
    customer: {
      name: 'Maria Souza',
      email: 'maria.souza@email.com',
      document: { type: 'cpf', id: '52998224725' },
      phone: '+5511987654321',
      address: { country: 'BRA' },
    },
    paymentMethod: {
      type: 'credit_card',
      number: '4444333322221111',
      holderName: 'MARIA SOUZA',
      expirationMonth: '10',
      expirationYear: '2030',
      cvv: '123',
      installments: 3,
    },
    items: [
      {
        title: 'Curso online',
        type: 'digital',
        description: 'Acesso de 12 meses',
        unit_price: 150,
        quantity: 1,
      },
    ],
    metadata: { orderId: 'PED-1001' },
    postbackUrl: 'https://abc123.ngrok.io/webhooks/finvia',
  }),
});

const charge = await response.json();

if (charge.status === 'paid') {
  // Aprovado: confirme o pedido.
  console.log('Aprovado', charge.id);
} else if (charge.status === 'refused' || charge.status === 'failed') {
  // Recusado ou falhou: mostre charge.reason e ofereça outra forma de pagamento.
  console.log('Não aprovado', charge.reason);
}
```

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

import requests

payload = {
    "amount": 150,
    "currency": "BRL",
    "customer": {
        "name": "Maria Souza",
        "email": "maria.souza@email.com",
        "document": {
            "type": "cpf",
            "id": "52998224725",
        },
        "phone": "+5511987654321",
        "address": {
            "country": "BRA",
        },
    },
    "paymentMethod": {
        "type": "credit_card",
        "number": "4444333322221111",
        "holderName": "MARIA SOUZA",
        "expirationMonth": "10",
        "expirationYear": "2030",
        "cvv": "123",
        "installments": 3,
    },
    "items": [
        {
            "title": "Curso online",
            "type": "digital",
            "description": "Acesso de 12 meses",
            "unit_price": 150,
            "quantity": 1,
        },
    ],
    "metadata": {
        "orderId": "PED-1001",
    },
    "postbackUrl": "https://abc123.ngrok.io/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' => 150,
    'currency' => 'BRL',
    'customer' => [
        'name' => 'Maria Souza',
        'email' => 'maria.souza@email.com',
        'document' => [
            'type' => 'cpf',
            'id' => '52998224725',
        ],
        'phone' => '+5511987654321',
        'address' => [
            'country' => 'BRA',
        ],
    ],
    'paymentMethod' => [
        'type' => 'credit_card',
        'number' => '4444333322221111',
        'holderName' => 'MARIA SOUZA',
        'expirationMonth' => '10',
        'expirationYear' => '2030',
        'cvv' => '123',
        'installments' => 3,
    ],
    'items' => [
        [
            'title' => 'Curso online',
            'type' => 'digital',
            'description' => 'Acesso de 12 meses',
            'unit_price' => 150,
            'quantity' => 1,
        ],
    ],
    'metadata' => [
        'orderId' => 'PED-1001',
    ],
    'postbackUrl' => 'https://abc123.ngrok.io/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": 150,
              "currency": "BRL",
              "customer": {
                "name": "Maria Souza",
                "email": "maria.souza@email.com",
                "document": {
                  "type": "cpf",
                  "id": "52998224725"
                },
                "phone": "+5511987654321",
                "address": {
                  "country": "BRA"
                }
              },
              "paymentMethod": {
                "type": "credit_card",
                "number": "4444333322221111",
                "holderName": "MARIA SOUZA",
                "expirationMonth": "10",
                "expirationYear": "2030",
                "cvv": "123",
                "installments": 3
              },
              "items": [
                {
                  "title": "Curso online",
                  "type": "digital",
                  "description": "Acesso de 12 meses",
                  "unit_price": 150,
                  "quantity": 1
                }
              ],
              "metadata": {
                "orderId": "PED-1001"
              },
              "postbackUrl": "https://abc123.ngrok.io/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": 150,
  "currency": "BRL",
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "4444333322221111",
    "holderName": "MARIA SOUZA",
    "expirationMonth": "10",
    "expirationYear": "2030",
    "cvv": "123",
    "installments": 3
  },
  "items": [
    {
      "title": "Curso online",
      "type": "digital",
      "description": "Acesso de 12 meses",
      "unit_price": 150,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "PED-1001"
  },
  "postbackUrl": "https://abc123.ngrok.io/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": 150,
	  "currency": "BRL",
	  "customer": {
	    "name": "Maria Souza",
	    "email": "maria.souza@email.com",
	    "document": {
	      "type": "cpf",
	      "id": "52998224725"
	    },
	    "phone": "+5511987654321",
	    "address": {
	      "country": "BRA"
	    }
	  },
	  "paymentMethod": {
	    "type": "credit_card",
	    "number": "4444333322221111",
	    "holderName": "MARIA SOUZA",
	    "expirationMonth": "10",
	    "expirationYear": "2030",
	    "cvv": "123",
	    "installments": 3
	  },
	  "items": [
	    {
	      "title": "Curso online",
	      "type": "digital",
	      "description": "Acesso de 12 meses",
	      "unit_price": 150,
	      "quantity": 1
	    }
	  ],
	  "metadata": {
	    "orderId": "PED-1001"
	  },
	  "postbackUrl": "https://abc123.ngrok.io/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" => 150,
  "currency" => "BRL",
  "customer" => {
    "name" => "Maria Souza",
    "email" => "maria.souza@email.com",
    "document" => {
      "type" => "cpf",
      "id" => "52998224725",
    },
    "phone" => "+5511987654321",
    "address" => {
      "country" => "BRA",
    },
  },
  "paymentMethod" => {
    "type" => "credit_card",
    "number" => "4444333322221111",
    "holderName" => "MARIA SOUZA",
    "expirationMonth" => "10",
    "expirationYear" => "2030",
    "cvv" => "123",
    "installments" => 3,
  },
  "items" => [
    {
      "title" => "Curso online",
      "type" => "digital",
      "description" => "Acesso de 12 meses",
      "unit_price" => 150,
      "quantity" => 1,
    },
  ],
  "metadata" => {
    "orderId" => "PED-1001",
  },
  "postbackUrl" => "https://abc123.ngrok.io/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
```

Exemplo de resposta `201` aprovada:

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "paid",
  "paymentDetails": {
    "firstSix": "444433",
    "lastFour": "1111",
    "expirationMonth": "10",
    "expirationYear": "2030",
    "holderName": "MARIA SOUZA",
    "installments": 3
  },
  "reason": null
}
```

Exemplo de resposta `201` recusada, com o cartão `4444333322221112`:

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "refused",
  "paymentDetails": null,
  "reason": "card_declined"
}
```

Na recusa síncrona, o `charge.refused` ou `charge.failed` sai no máximo uma vez por cobrança, para os endpoints e para a `postbackUrl`. O envelope padrão não traz o motivo: ele está no `reason` da resposta e na consulta da cobrança.

| Regra do cartão | Valor |
| - | - |
| Parcelas (`installments`) | Obrigatório, de `1` a `12` |
| Mês e ano de validade | Texto com 2 e 4 caracteres (`"10"`, `"2030"`) |
| CVV | Texto, mínimo de 3 caracteres |
| Número | Texto, só dígitos, sem espaços |

> [!TIP]
>
> **Para o desenvolvedor:** para não guardar dados de cartão no seu servidor, o caminho é o [cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` com `"message": "Unauthorized"` | Cabeçalho ausente, chave inválida ou Base64 montado sem os dois pontos | Decodifique o Base64 e confira se termina em `:` e se o prefixo é `Basic ` |
| `403` com `"message": "Acesso negado"` ao criar cobrança | O perfil do usuário que gerou a chave não pode criar cobranças (ex.: Desenvolvedor) | 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) |
| `400` com `Shipping info must be provided for merchants selling physical items.` | Item `physical` sem `shippingAddress` | Envie `shippingAddress` com `postalCode`, `addressLine1`, `city`, `state` e `country` |
| `422` com `Fees not configured` | A conta não tem taxa configurada para o método, a moeda ou o número de parcelas | Fale com o suporte da Finvia |
| `400` com `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem `cvv` | Envie o `cvv` junto com o `cardTokenId` |
| `403` na rota de simulação de webhook | A cobrança não é de teste | Use uma cobrança criada com a chave `sk_test_` |
| Webhook não chega | URL inacessível pela internet ou receptor respondendo com erro | Confira a URL do ngrok, se o servidor está rodando e se ele responde com status `2xx`. Qualquer outra resposta conta como falha de entrega |

Mais detalhes em [Erros e como tratar](https://docs.fastpaybrasil.com/primeiros-passos/erros.md).

## Perguntas frequentes

> [accordion] Preciso cadastrar o cliente antes de criar a cobrança?
>
> Não. Ao enviar `name` e `email` (ou `phone`) dentro de `customer`, a API cria ou localiza o cliente na mesma chamada. O cadastro prévio com `POST /v1/customers` é útil quando o cliente volta a comprar, guarda cartão ou assina um plano: aí basta enviar o `customer.id`.

> [accordion] Posso usar só a postbackUrl, sem cadastrar webhook no painel?
>
> Pode, para eventos de cobrança. Os eventos que cada canal recebe estão na [tabela de eventos por canal](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#eventos-por-canal). Os eventos de assinatura chegam só aos endpoints cadastrados no painel.

> [accordion] Se eu já tenho o status na resposta do cartão, preciso do webhook?
>
> Sim. A resposta resolve o checkout, e os eventos posteriores, como estorno, alerta de contestação e bloqueio, só chegam por notificação.

> [accordion] Como sei que a cobrança veio do sandbox?
>
> No webhook, `livemode` vem `false` e `data.is_test` vem `true`. No `charge.updated` legado, o indicador é `data.isTest`. Os mesmos endpoints recebem eventos de teste e de produção, então descarte ou separe os eventos com `livemode: false` no ambiente de produção.

> [accordion] A requisição deu timeout. Posso criar a cobrança de novo?
>
> Não reenvie às cegas: a API não aceita `Idempotency-Key`. Veja a estratégia segura em [Paginação, ordenação e idempotência](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

## Checklist do que você terá ao final

* [ ] Chave de teste guardada em variável de ambiente, nunca no código.
* [ ] `GET /v1/payment-methods` respondendo `200`.
* [ ] Receptor de webhooks em HTTPS respondendo `2xx` rapidamente.
* [ ] Cobrança Pix criada, com `id` guardado junto ao pedido.
* [ ] QR Code exibido a partir de `qrCodeBase64`, com `copyPaste` como alternativa.
* [ ] `charge.created` e `charge.pending` recebidos na `postbackUrl`.
* [ ] `charge.paid` recebido cerca de 5 segundos depois, com o mesmo `id` da criação.
* [ ] Eventos de teste reconhecidos por `livemode: false`.
* [ ] Outros status simulados com `POST /v1/charges/{id}/resend-webhook`, sem liberar o pedido duas vezes.
* [ ] Estado confirmado com `GET /v1/charges/{id}` antes de liberar o pedido.
* [ ] Cobranças de cartão aprovada (`4444333322221111`) e recusada (`4444333322221112`), com tratamento de `paid`, `refused` e `failed` na resposta.

## Como testar

Este tutorial cobre a base dos cenários **CHG-01** (cartão aprovado), **CHG-02** (cartão parcelado), **CHG-03** (cartão recusado, com o cartão `4444333322221112`), **CHG-04** (Pix gerado), **CHG-05** (Pix pago no sandbox), **CHG-06** (consulta), **CHG-08** (recebimento de webhook) e **CHG-09** (simulação de webhook) do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md). Guarde, para cada um, a requisição, a resposta, o `id` e o log do webhook com o status HTTP que o seu receptor devolveu.

## Veja também

> [card] [Pix](https://docs.fastpaybrasil.com/guias/cobrancas/pix.md)
>
> Regras de validade, QR Code e boas práticas do Pix.

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

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Todos os campos e eventos de cobrança.

> [card] [Criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Referência completa de `POST /v1/charges`.


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