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

# Pix

> Gere um QR Code Pix, mostre no checkout, receba a confirmação por webhook e concilie o pagamento.

O Pix é o pagamento instantâneo do Brasil. Na Finvia, você cria a cobrança e recebe na resposta o código copia e cola e a imagem do QR Code para mostrar ao cliente. Quando o cliente paga no app do banco, a Finvia avisa o seu sistema por webhook e você libera o pedido.

> [!NOTE]
>
> **Para o negócio:** o Pix é pago à vista, sem parcelamento, e o cliente paga no app do próprio banco. Você define por quanto tempo o QR Code vale: alguns minutos em um checkout com o cliente na tela, ou um ou mais dias em uma cobrança enviada por link ou mensagem.

## Quando usar

| Situação | Recomendação |
| - | - |
| Checkout de loja virtual com o cliente na tela | Pix com validade curta, em segundos (mínimo de 15 minutos) |
| Cobrança enviada por WhatsApp, e-mail ou link | Pix com validade em dias |
| Venda de infoproduto com liberação automática do acesso | Pix, liberando o acesso ao receber `charge.paid` |
| Cliente quer parcelar | Use [cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md) |
| Cobrança automática todo mês | Use [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |

## Como funciona

O desenho abaixo mostra o caminho completo de uma cobrança Pix, do pedido à confirmação, e o que acontece quando o QR Code vence sem pagamento.

```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 B as Banco do comprador
    end
    C->>L: Finaliza o pedido e escolhe Pix
    L->>F: POST /v1/charges · type pix + validade do QR Code
    F-->>L: 201 · pending · copyPaste · qrCodeBase64
    F-)W: charge.created e charge.pending
    L-->>C: Mostra o QR Code e o copia e cola
    alt Comprador paga dentro da validade
        C->>B: Paga no app do banco
        B->>F: Confirma o Pix
        F-)W: charge.paid (e charge.updated na postbackUrl)
        W->>F: GET /v1/charges/{id}
        F-->>W: status paid · endToEndId preenchido
        L-->>C: Checkout mostra o pedido pago e libera
    else A validade acaba sem pagamento
        Note over L,F: Pix vencido ou cancelado. O status final pode vir failed
        F-)W: charge.updated, só na postbackUrl
        L->>F: Sem postbackUrl · GET /v1/charges/{id} após a validade
        L-->>C: Pedido não liberado · novo Pix se ele voltar
    end
```

Os eventos chegam aos endpoints de webhook cadastrados no painel e à `postbackUrl` da cobrança. O `charge.updated` vai só para a `postbackUrl`: sem ela, a única forma de saber que um Pix venceu é consultar a cobrança.

**1. Você cria a cobrança Pix**

Seu servidor chama `POST /v1/charges` com `paymentMethod.type` `pix` e a validade do QR Code.

**2. A resposta traz o QR Code**

A resposta `201` vem com `status` `pending` e `paymentDetails` com o código copia e cola (`copyPaste`), a imagem do QR Code (`qrCodeBase64`) e o identificador `endToEndId`.

**3. Você mostra o QR Code ao cliente**

O checkout exibe a imagem e um botão para copiar o código. Os endpoints de webhook e a `postbackUrl` recebem `charge.created` e `charge.pending`.

**4. O cliente paga no app do banco**

Ele escaneia o QR Code ou cola o código no app do banco e confirma o pagamento.

**5. A Finvia confirma por webhook**

A cobrança passa para `paid` e o seu sistema recebe `charge.paid` (e, na `postbackUrl`, também o `charge.updated` legado). Confirme com `GET /v1/charges/{id}` e libere o pedido.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Validade obrigatória | Envie `expirationInDays` ou `expirationInSeconds`. Um dos dois é obrigatório |
| Validade em dias | `expirationInDays`, mínimo `1` |
| Validade em segundos | `expirationInSeconds`, mínimo `900` (15 minutos) |
| Valor | Em reais: `"amount": 49.9` é R\$ 49,90. Mínimo `1` |
| Moeda | Somente `BRL` |
| Taxa | A conta precisa ter taxa de Pix em BRL configurada. Sem ela, a API responde `422` `Fees not configured` |
| Status na criação | `pending`. O pagamento é confirmado depois, por webhook |
| Pix cancelado ou expirado | O status final pode vir `failed`. Esse desfecho chega só pelo `charge.updated` na `postbackUrl` ou pela consulta |
| Estorno | Total, só de cobrança `paid`, pedido em até 90 dias do pagamento. Veja [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md) |

> [!WARNING]
>
> Nunca libere o pedido com base na resposta da criação. O `pending` indica só que o QR Code foi gerado. Libere só depois de receber `charge.paid` e confirmar o status com `GET /v1/charges/{id}`.

### Como escolher a validade

| Cenário | Sugestão | Campo |
| - | - | - |
| Checkout com o cliente na tela | 15 a 30 minutos | `"expirationInSeconds": 900` a `1800` |
| Reserva de estoque ou ingresso | Tempo da reserva, a partir de 15 minutos | `expirationInSeconds` |
| Cobrança por link ou mensagem | 1 a 3 dias | `"expirationInDays": 1` a `3` |

Uma validade curta mantém o pedido e o estoque alinhados com o pagamento. Uma validade longa dá tempo para o cliente pagar quando puder.

## O que vem na resposta

| Campo | Para que serve |
| - | - |
| `id` | Identificador da cobrança. Grave no seu pedido |
| `status` | `pending` na criação |
| `paymentDetails.copyPaste` | Código Pix copia e cola (BR Code EMV). O cliente cola no app do banco |
| `paymentDetails.qrCodeBase64` | Imagem PNG 256x256 do QR Code, em data URI. Vai direto no `src` de uma tag `<img>` |
| `paymentDetails.endToEndId` | Identificador End to End do Pix, preenchido quando o pagamento é confirmado |
| `paymentDetails.expiresAt` | Data e hora de expiração do Pix (opcional) |
| `customerId` | ID do cliente criado ou reaproveitado |
| `reason` | `null` em cobranças Pix criadas com sucesso |

> [!TIP]
>
> **Para o desenvolvedor:** `qrCodeBase64` pode vir `null` ou ausente quando a imagem não pôde ser gerada (ou em cobranças criadas antes de o campo existir). Nesse caso, gere o QR Code no seu front-end a partir do `copyPaste`, com qualquer biblioteca de QR Code, ou mostre só o código copia e cola.

## Passo a passo

### 1. Crie a cobrança

```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": 149.9,
  "currency": "BRL",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "pix",
    "expirationInSeconds": 1800
  },
  "items": [
    {
      "title": "Curso de Fotografia",
      "type": "digital",
      "description": "Acesso por 12 meses",
      "unit_price": 149.9,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "ORD-2048"
  },
  "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": 149.9,
    "currency": "BRL",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321",
      "address": { "country": "BRA" }
    },
    "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 },
    "items": [
      {
        "title": "Curso de Fotografia",
        "type": "digital",
        "description": "Acesso por 12 meses",
        "unit_price": 149.9,
        "quantity": 1
      }
    ],
    "metadata": { "orderId": "ORD-2048" },
    "postbackUrl": "https://meusite.com.br/webhooks/finvia"
  }'
```

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

async function criarPix(pedido) {
  const response = await fetch(`${API_URL}/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 },
      paymentMethod: { type: 'pix', expirationInSeconds: 1800 },
      items: pedido.itens,
      metadata: { orderId: pedido.id },
      postbackUrl: 'https://meusite.com.br/webhooks/finvia',
    }),
  });

  const charge = await response.json();
  // Grave charge.id no pedido antes de devolver o QR Code ao front-end
  return {
    chargeId: charge.id,
    copyPaste: charge.paymentDetails.copyPaste,
    qrCodeBase64: charge.paymentDetails.qrCodeBase64 ?? null,
  };
}

const pix = await criarPix({
  id: 'ORD-2048',
  total: 149.9,
  nome: 'Maria Souza',
  email: 'maria@email.com',
  itens: [
    { title: 'Curso de Fotografia', type: 'digital', description: 'Acesso por 12 meses', unit_price: 149.9, quantity: 1 },
  ],
});
console.log(pix.chargeId, pix.copyPaste);
```

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

import requests

payload = {
    "amount": 149.9,
    "currency": "BRL",
    "customer": {
        "name": "Maria Souza",
        "email": "maria@email.com",
        "document": {
            "type": "cpf",
            "id": "52998224725",
        },
        "phone": "+5511987654321",
        "address": {
            "country": "BRA",
        },
    },
    "paymentMethod": {
        "type": "pix",
        "expirationInSeconds": 1800,
    },
    "items": [
        {
            "title": "Curso de Fotografia",
            "type": "digital",
            "description": "Acesso por 12 meses",
            "unit_price": 149.9,
            "quantity": 1,
        },
    ],
    "metadata": {
        "orderId": "ORD-2048",
    },
    "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' => 149.9,
    'currency' => 'BRL',
    'customer' => [
        'name' => 'Maria Souza',
        'email' => 'maria@email.com',
        'document' => [
            'type' => 'cpf',
            'id' => '52998224725',
        ],
        'phone' => '+5511987654321',
        'address' => [
            'country' => 'BRA',
        ],
    ],
    'paymentMethod' => [
        'type' => 'pix',
        'expirationInSeconds' => 1800,
    ],
    'items' => [
        [
            'title' => 'Curso de Fotografia',
            'type' => 'digital',
            'description' => 'Acesso por 12 meses',
            'unit_price' => 149.9,
            'quantity' => 1,
        ],
    ],
    'metadata' => [
        'orderId' => 'ORD-2048',
    ],
    '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": 149.9,
              "currency": "BRL",
              "customer": {
                "name": "Maria Souza",
                "email": "maria@email.com",
                "document": {
                  "type": "cpf",
                  "id": "52998224725"
                },
                "phone": "+5511987654321",
                "address": {
                  "country": "BRA"
                }
              },
              "paymentMethod": {
                "type": "pix",
                "expirationInSeconds": 1800
              },
              "items": [
                {
                  "title": "Curso de Fotografia",
                  "type": "digital",
                  "description": "Acesso por 12 meses",
                  "unit_price": 149.9,
                  "quantity": 1
                }
              ],
              "metadata": {
                "orderId": "ORD-2048"
              },
              "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": 149.9,
  "currency": "BRL",
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com",
    "document": {
      "type": "cpf",
      "id": "52998224725"
    },
    "phone": "+5511987654321",
    "address": {
      "country": "BRA"
    }
  },
  "paymentMethod": {
    "type": "pix",
    "expirationInSeconds": 1800
  },
  "items": [
    {
      "title": "Curso de Fotografia",
      "type": "digital",
      "description": "Acesso por 12 meses",
      "unit_price": 149.9,
      "quantity": 1
    }
  ],
  "metadata": {
    "orderId": "ORD-2048"
  },
  "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": 149.9,
	  "currency": "BRL",
	  "customer": {
	    "name": "Maria Souza",
	    "email": "maria@email.com",
	    "document": {
	      "type": "cpf",
	      "id": "52998224725"
	    },
	    "phone": "+5511987654321",
	    "address": {
	      "country": "BRA"
	    }
	  },
	  "paymentMethod": {
	    "type": "pix",
	    "expirationInSeconds": 1800
	  },
	  "items": [
	    {
	      "title": "Curso de Fotografia",
	      "type": "digital",
	      "description": "Acesso por 12 meses",
	      "unit_price": 149.9,
	      "quantity": 1
	    }
	  ],
	  "metadata": {
	    "orderId": "ORD-2048"
	  },
	  "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" => 149.9,
  "currency" => "BRL",
  "customer" => {
    "name" => "Maria Souza",
    "email" => "maria@email.com",
    "document" => {
      "type" => "cpf",
      "id" => "52998224725",
    },
    "phone" => "+5511987654321",
    "address" => {
      "country" => "BRA",
    },
  },
  "paymentMethod" => {
    "type" => "pix",
    "expirationInSeconds" => 1800,
  },
  "items" => [
    {
      "title" => "Curso de Fotografia",
      "type" => "digital",
      "description" => "Acesso por 12 meses",
      "unit_price" => 149.9,
      "quantity" => 1,
    },
  ],
  "metadata" => {
    "orderId" => "ORD-2048",
  },
  "postbackUrl" => "https://meusite.com.br/webhooks/finvia",
})

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

puts response.code
puts response.body
```

Resposta `201`:

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

### 2. Mostre o QR Code no checkout

O seu back-end devolve ao front-end apenas o `copyPaste` e o `qrCodeBase64`. A chave secreta nunca vai para o navegador.

```html theme={null}
<div id="pix">
  <img id="pix-qrcode" alt="QR Code Pix" width="256" height="256" hidden />
  <p>Ou copie o código e cole no app do seu banco:</p>
  <textarea id="pix-codigo" rows="4" readonly></textarea>
  <button id="pix-copiar" type="button">Copiar código Pix</button>
  <p id="pix-status">Aguardando pagamento...</p>
</div>

<script>
  function mostrarPix({ copyPaste, qrCodeBase64 }) {
    const img = document.getElementById('pix-qrcode');
    if (qrCodeBase64) {
      img.src = qrCodeBase64;
      img.hidden = false;
    }
    // Sem imagem, o cliente usa o código copia e cola
    document.getElementById('pix-codigo').value = copyPaste;

    document.getElementById('pix-copiar').addEventListener('click', async () => {
      await navigator.clipboard.writeText(copyPaste);
      document.getElementById('pix-copiar').textContent = 'Código copiado';
    });
  }
</script>
```

> [!TIP]
>
> **Para o desenvolvedor:** para atualizar a tela quando o cliente pagar, faça o front-end consultar o **seu** back-end a cada poucos segundos (ou use WebSocket). O seu back-end responde com o status que gravou ao receber `charge.paid`. O navegador nunca chama a API da Finvia com a chave secreta.

### 3. Receba os webhooks

Os eventos de cobrança chegam aos endpoints do painel e à `postbackUrl` no envelope padrão (`id`, `event`, `livemode`, `data`), com as chaves de `data` em snake\_case. Os objetos internos ficam como foram gravados: `payment_details` do Pix vem em camelCase (`endToEndId`, `copyPaste`, `qrCodeBase64`) e `metadata` volta exatamente como você enviou. O exemplo abaixo é um `charge.paid`.

```json theme={null}
{
  "id": "2xKq7Rm4TzW9bN3pL8cV1dY6hJe",
  "event": "charge.paid",
  "livemode": true,
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "status": "paid",
    "psp_ref_id": "pix_e2e_abc123",
    "amount": 149.9,
    "currency": "BRL",
    "spread": 1.5,
    "anticipation_fee_estimated": 0,
    "net": 148.4,
    "merchant_id": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
    "payment_method": { "type": "pix" },
    "payment_details": {
      "endToEndId": "E12345678202610271035abcdef12345",
      "copyPaste": "00020101021226870014br.gov.bcb.pix...6304ABCD",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "metadata": { "orderId": "ORD-2048" },
    "paid_at": "2026-10-27T10:35:00.000Z",
    "is_test": false,
    "created_at": "2026-10-27T10:30:00.000Z",
    "updated_at": "2026-10-27T10:35:00.000Z"
  }
}
```

O exemplo mostra parte do objeto `data`. O payload completo está em [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md). Na `postbackUrl`, o pagamento gera também um `charge.updated` legado, em camelCase e sem `id`.

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

const API_URL = 'https://api-global.fastpaybrasil.com';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

// Exemplo em memória. Em produção, grave as chaves no seu banco.
const processados = new Set();
const jaProcessado = async (key) => processados.has(key);
const marcarProcessado = async (key) => { processados.add(key); };

async function consultarCobranca(id) {
  const res = await fetch(`${API_URL}/v1/charges/${id}`, {
    headers: { Authorization: `Basic ${credentials}` },
  });
  const texto = await res.text();
  return texto ? JSON.parse(texto) : null;
}

// Troque pela liberação do pedido no seu sistema
async function liberarPedidoPorCobranca(chargeId) { console.log('liberar', chargeId); }

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

app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  res.status(200).send('OK'); // responda rápido e processe em seguida

  // Envelope padrão: a chave de deduplicação é o id do evento
  if (!id) return; // charge.updated (sem id) é tratado à parte
  if (await jaProcessado(id)) return;

  if (event === 'charge.paid') {
    // Confirme na API antes de liberar: os webhooks não têm assinatura
    const charge = await consultarCobranca(data.id); // GET /v1/charges/{id}
    if (charge?.status === 'paid') {
      await liberarPedidoPorCobranca(charge.id);
    }
  }

  await marcarProcessado(id);
});

app.listen(3000);
```

Para descartar eventos repetidos, siga a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos), que cobre também o `charge.updated`.

Depois de criado, um Pix pode passar pelos status abaixo. Cada seta mostra o que provoca a mudança e o aviso que o seu sistema recebe.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    CRI["POST /v1/charges<br/>type pix"]:::lojista
    PEN(["pending<br/>QR Code gerado"]):::alerta
    PAID(["paid<br/>pago"]):::ok
    FAIL(["failed<br/>cancelado ou expirado"]):::erro
    BLK(["paid + isBlocked<br/>bloqueado por MED"]):::alerta
    RFD(["refunded<br/>devolvido"]):::neutro
    DESB(["paid<br/>bloqueio retirado"]):::ok
    CRI -->|"charge.created<br/>charge.pending"| PEN
    PEN ==>|"comprador pagou<br/>charge.paid"| PAID
    PEN -->|"venceu ou foi cancelado<br/>charge.updated<br/>só na postbackUrl"| FAIL
    PAID -->|"estorno em até<br/>90 dias do pagamento<br/>charge.refunded"| RFD
    PAID -->|"MED pedido pelo<br/>banco do pagador<br/>charge.blocked"| BLK
    BLK -->|"devolução aceita<br/>charge.refunded"| RFD
    BLK -.->|"devolução recusada<br/>sem webhook: consulte"| DESB
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

O estorno e o MED estão detalhados nas seções seguintes desta página e em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Conciliação

Conciliar é conferir que cada pedido pago no seu sistema corresponde a um Pix recebido, com o valor certo.

| Dado | Onde está | Uso na conciliação |
| - | - | - |
| `id` da cobrança | Resposta, webhook, consulta | Chave principal entre o seu pedido e a Finvia |
| Número do seu pedido | `metadata.orderId`, igual no webhook, na consulta e na listagem | Liga o evento ao pedido |
| `endToEndId` | `paymentDetails` (consulta) ou `payment_details` (webhook) | Identificador End to End do Pix |
| `amount` e `net` | Webhook e consulta | Valor bruto e valor líquido, em reais |
| `paid_at` / `paidAt` | Webhook / consulta | Data e hora do pagamento |

Para conferir em lote, use [`GET /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/listar) com `status=paid`, `createdAtStart` e `createdAtEnd` no dia desejado, paginando por `page` e `size`. Para achar um Pix pelo `endToEndId`, use `searchFor`.

## Estorno de Pix

Uma cobrança Pix paga pode ser estornada por `POST /v1/refunds`. O estorno é uma devolução Pix do pagamento original, sempre do valor total, enviada na hora. Quando aceita, o dinheiro costuma chegar em segundos na conta de origem. Pelas regras do Pix, a devolução precisa ser pedida em até 90 dias do pagamento: depois disso, o banco pode recusar. A cobrança vai para `refunded` e o seu sistema recebe `charge.refunded`. Detalhes em [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md).

## MED

O MED (Mecanismo Especial de Devolução) é o mecanismo do Pix que permite à instituição do pagador pedir a devolução de um Pix em caso de suspeita de fraude ou falha operacional. Quando a Finvia é notificada de um MED sobre um Pix pago, a equipe Finvia bloqueia a cobrança enquanto o caso é analisado:

* O `status` continua `paid` e a cobrança passa a ter `isBlocked: true`, `blockedAt` e `blockedReason`.
* O evento `charge.blocked` vai aos endpoints de webhook e à `postbackUrl` (que recebe também o `charge.updated`).
* O valor já liquidado da venda sai do saldo disponível e vai para o saldo bloqueado.
* Se a devolução for aceita, a cobrança fica `refunded` e você recebe `charge.refunded`. Se for recusada, o bloqueio é retirado, **sem webhook**: acompanhe pela consulta.

O fluxo completo, o envio da defesa e os desfechos estão em [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` de validação | `expirationInSeconds` menor que `900`, ou nenhum campo de validade enviado | Envie `expirationInSeconds` a partir de `900` ou `expirationInDays` a partir de `1` |
| `422` com `Fees not configured` | A conta não tem taxa de Pix em BRL | Fale com o suporte da Finvia |
| Imagem do QR Code quebrada | `qrCodeBase64` veio `null` ou ausente | Gere o QR Code a partir do `copyPaste` ou mostre só o código |
| Pedido liberado sem pagamento | Liberação feita com base no `pending` da criação | Libere só com `charge.paid` confirmado por `GET /v1/charges/{id}` |
| Pedido liberado duas vezes | O mesmo evento chegou mais de uma vez, ou pelos dois canais | Aplique a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos) |
| Pedido fica pendente para sempre | Pix expirado ou cancelado, sem `postbackUrl` | Informe `postbackUrl` ou consulte a cobrança depois da validade |

## Perguntas frequentes

> [accordion] Posso usar expirationInDays e expirationInSeconds juntos?
>
> Um dos dois é obrigatório. Envie só o que corresponde à sua regra: segundos para checkout com o cliente na tela, dias para cobranças por link.

> [accordion] Qual a validade mínima de um Pix?
>
> 15 minutos: `expirationInSeconds` tem mínimo `900`. Em dias, o mínimo é `1`.

> [accordion] O Pix aceita parcelamento?
>
> Não. O Pix é pago à vista. Para parcelar, use [cartão de crédito](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-de-credito.md).

> [accordion] Como sei que o cliente pagou?
>
> Pelo webhook `charge.paid`. Ao receber, confirme o status com `GET /v1/charges/{id}` antes de liberar o pedido.

> [accordion] Como testo um Pix pago sem pagar de verdade?
>
> Crie a cobrança com a chave `sk_test_`. Cerca de 5 segundos depois, ela passa sozinha para `paid` e você recebe `charge.paid`. Não tente pagar o código de teste em um app de banco.

## Como testar

No Modo Teste (chave `sk_test_`), o Pix é confirmado automaticamente. Não há nada para pagar nem botão de simulação.

**1. Crie a cobrança com a chave de teste**

Use `paymentMethod: { "type": "pix", "expirationInSeconds": 900 }` (ou `expirationInDays`).

**2. Confira a resposta**

Vem `status: "pending"` com `copyPaste` e `qrCodeBase64` fictícios. Não tente pagar esse código.

**3. Aguarde cerca de 5 segundos**

A cobrança passa sozinha para `paid`: `paidAt` é preenchido e `paymentDetails.endToEndId` recebe um valor de teste.

**4. Confira os eventos**

Os endpoints recebem `charge.created` e `charge.pending` na criação e `charge.paid` na confirmação, com `livemode: false`. A `postbackUrl`, se informada, também é notificada. Confirme com `GET /v1/charges/{id}` usando a mesma chave de teste.

> [!NOTE]
>
> No sandbox todo Pix é aprovado: não dá para simular expiração ou falha. Para testar o tratamento de outros status, use [`POST /v1/charges/{id}/resend-webhook`](https://docs.fastpaybrasil.com/referencia/cobrancas/reenviar-webhook-teste), que dispara um evento simulado sem alterar a cobrança. Se, em casos raros, a cobrança não virar `paid` em alguns segundos, gere outra.

Cenários do [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md):

* **CHG-04 (Pix gerado):** cobrança com `pending`, resposta com o copia e cola e webhook `charge.pending`.
* **CHG-05 (Pix pago):** o webhook `charge.paid` chega com o mesmo `id` devolvido na criação.
* **CHG-07 (estorno):** estorno total da cobrança paga, com `charge.refunded`.
* **CHG-08 e CHG-09:** recebimento e simulação de webhook.

## Veja também

> [card] [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
>
> Formato completo dos eventos.

> [card] [Estorno](https://docs.fastpaybrasil.com/guias/estorno.md)
>
> Como devolver um Pix pago.

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> Contestações e bloqueio preventivo.

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