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

# Consultar uma cobrança

> Devolve o estado atual de uma cobrança pelo ID: status, valores, cliente, forma de pagamento, bloqueio, split e dados de pré-chargeback.

Esta rota devolve uma cobrança (charge) pelo seu identificador, com o status atual e todos os detalhes. Ela é a fonte de verdade para decidir o que fazer com um pedido: liberar o produto, cancelar, marcar como estornado ou como em disputa. É também a única rota que mostra a divisão do valor entre as contas (`splits`) e as tentativas agrupadas (`groupCharges`).

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Recebeu um webhook ou postback | Consulte a cobrança pelo `id` do evento e confirme o `status` antes de liberar o pedido |
| Antes de pedir um estorno | Confira se o `status` é `paid` |
| Acompanhar uma disputa | Leia `isBlocked`: a liberação do bloqueio não gera webhook |
| Conferir o split da venda | Leia a lista `splits` |
| Tela de detalhe do pedido | Mostre forma de pagamento, parcelas, valor líquido e datas |
| Mostrar de novo o QR Code Pix | Leia `paymentDetails.copyPaste` e `paymentDetails.qrCodeBase64` |
| A criação deu timeout e você não tem o `id` | Esta rota não ajuda. Siga o [procedimento para timeout](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md#idempotência) |
| Ver várias cobranças de uma vez | Use [`GET /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/listar) |

## Antes de chamar

* Tenha uma chave secreta do mesmo ambiente em que a cobrança foi criada: `sk_test_` para cobranças de teste e `sk_` para cobranças reais ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* Tenha o `id` da cobrança, devolvido por [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar) e presente em todos os webhooks de cobrança (`data.id`).

## Parâmetros de caminho

**id** `string` *required*

Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

## Respostas

A resposta `200` é o objeto de cobrança. Trate a ausência de qualquer campo.

> [!WARNING]
>
> A API não usa `404` nesta rota: para um `id` que não existe, ela responde hoje **`200` com corpo vazio**. Trate corpo vazio como "cobrança não encontrada" e confira se a chave é do mesmo ambiente e da mesma conta da cobrança.

**id** `string`

Identificador único da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**status** `string`

Status da cobrança: `paid`, `pending`, `refused`, `failed`, `refunded`, `in_analysis`, `authentication_required`, `pre_chargeback` ou `chargeback`. Ex.: `paid`.

**isBlocked** `boolean`

`true` enquanto a cobrança está bloqueada por uma disputa (MED no Pix ou chargeback no cartão). O `status` continua `paid` durante o bloqueio. Use este campo para saber se a cobrança está bloqueada.

**blockedAt** `string | null`

Data e hora do bloqueio, em ISO 8601. Continua preenchido depois da liberação, por isso não serve para saber se a cobrança ainda está bloqueada.

**blockedReason** `string | null`

Motivo do bloqueio, em texto livre preenchido pela equipe Finvia (pode indicar MED ou chargeback). Pode vir vazio e é apagado na liberação.

**chargebackAlertRefunded** `boolean | null`

Presente em cobranças com alerta de pré-chargeback (`status` `pre_chargeback`). `true`: o valor já foi estornado ao comprador como parte do tratamento do alerta. `false`: disputa aberta, sem estorno. `null` quando não há alerta.

**chargebackAlertReason** `string | null`

Motivo ou referência informado no alerta de pré-chargeback. Ex.: `Chargeback - NSU 123456789`.

**pspRefId** `string | null`

Identificador da cobrança no sistema do provedor de pagamento (PSP). Ex.: `ch_123456789`.

**amount** `number`

Valor total da cobrança, em reais. Ex.: `100.5`.

**currency** `string`

Moeda no padrão ISO 4217. Ex.: `BRL`.

**spread** `number`

Spread (taxa) aplicado à cobrança. Ex.: `2.5`.

**net** `number`

Valor líquido depois do spread. Ex.: `98`.

**customer** `object`

Cliente que pagou a cobrança.

**propriedades**

**id** `string`

Identificador do cliente. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**name** `string`

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

**email** `string`

E-mail do cliente. Ex.: `maria@email.com`.

**document** `string`

Documento do cliente, como texto. Ex.: `529.982.247-25`.

**paymentMethod** `object`

Forma de pagamento usada. Em cobranças Pix, traz `type` `pix`. Em cartão (digitado, salvo ou Apple Pay):

**Cartão de crédito**

**type** `string` *required*

`credit_card`.

**firstSix** `string` *required*

Seis primeiros dígitos do cartão. Ex.: `444433`.

**lastFour** `string` *required*

Quatro últimos dígitos do cartão. Ex.: `1111`.

**expirationMonth** `string` *required*

Mês de validade. Ex.: `12`.

**expirationYear** `string` *required*

Ano de validade. Ex.: `2030`.

**holderName** `string` *required*

Nome do titular. Ex.: `MARIA SOUZA`.

**installments** `number` *required*

Número de parcelas usado. Ex.: `3`.

**merchantId** `string`

Identificador da conta dona da cobrança. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**paymentDetails** `object | null`

Detalhes do pagamento. O formato muda conforme a forma de pagamento.

**Cartão de crédito**

**firstSix** `string` *required*

Seis primeiros dígitos do cartão. Ex.: `411111`.

**lastFour** `string` *required*

Quatro últimos dígitos do cartão. Ex.: `1111`.

**expirationMonth** `string` *required*

Mês de validade. Ex.: `12`.

**expirationYear** `string` *required*

Ano de validade. Ex.: `2030`.

**holderName** `string` *required*

Nome do titular. Ex.: `JOAO DA SILVA`.

**installments** `number` *required*

Número de parcelas usado. Ex.: `1`.

**brand** `string`

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

**Pix**

**endToEndId** `string`

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

**copyPaste** `string` *required*

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

**qrCodeBase64** `string | null`

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

**expiresAt** `string`

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

**splits** `object[]`

Divisão do valor entre as contas recebedoras. Aparece só nesta consulta (não vem na listagem nem na criação). Vem preenchida quando a cobrança teve `split` no POST ou quando a conta tem regra de split padrão para aquele método e moeda; nesse segundo caso, mesmo sem `split` na criação.

**propriedades**

**id** `string`

ID do registro de split.

**destinyMerchantId** `string`

Conta recebedora. É o `merchantId` enviado em `split[]` na criação.

**destinyMerchantName** `string`

Nome fantasia da conta recebedora.

**splitPercentage** `string`

Percentual, como texto decimal. Ex.: `"30.00000000"`. Converta para número antes de calcular.

**splitAmount** `number`

Valor exibido para o recebedor, com 2 casas (truncado). O significado muda conforme o momento da cobrança: veja a tabela abaixo.

**referenceAmount** `string`

Base de cálculo: `net` (padrão, valor líquido depois da taxa transacional) ou `gross` (valor bruto, quando a conta está configurada assim).

**groupCharges** `object[]`

No cartão, tentativas do mesmo comprador com os mesmos itens em até 15 minutos são agrupadas. A listagem mostra só a cobrança principal do grupo, e as demais tentativas aparecem aqui, na consulta da principal.

**metadata** `object | null`

Informações livres que você enviou na criação. Nesta resposta, as chaves voltam em **camelCase**: chaves enviadas em snake\_case chegam convertidas. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata). Ex.: `{"orderId": "ORD-123"}`.

**paidAt** `string | null`

Data e hora do pagamento, em ISO 8601. Ex.: `2026-10-15T14:30:00Z`.

**createdAt** `string`

Data e hora da criação, em ISO 8601.

**updatedAt** `string`

Data e hora da última atualização, em ISO 8601.

### O que `splitAmount` mostra

Com base `net` (o padrão):

| Momento da cobrança | O que `splitAmount` mostra |
| - | - |
| Parcelas a liquidar, sem antecipação concluída | Uma **simulação**: o valor que o recebedor teria se o originador antecipasse, já descontada a taxa de antecipação estimada. Não é o valor que será repassado |
| Parcelas liquidadas sem antecipação | O repasse efetivo: percentual sobre o valor líquido, sem desconto de antecipação |
| Depois de uma antecipação concluída | O valor efetivamente destinado, recalculado sobre o valor antecipado |

Com base `gross`, mostra sempre percentual × valor bruto. O split pode aparecer também em cobrança recusada, mas o repasse só acontece quando a cobrança é paga.

> [!TIP]
>
> **Para o desenvolvedor:** na conciliação do split, confira `destinyMerchantId` e `splitPercentage` e compare `splitAmount` com valor líquido × percentual. Enquanto a simulação de antecipação estiver ativa, o valor mostrado é menor que esse cálculo.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Cobrança encontrada, ou corpo vazio quando o `id` não existe | Objeto de cobrança ou vazio |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Perfil do usuário dono da chave sem permissão | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |

> [!NOTE]
>
> **Para o negócio:** use o `status` desta consulta como regra para liberar pedidos. `paid` libera; `pending` aguarda; `refused` e `failed` encerram a tentativa; `refunded` cancela o pedido. Uma cobrança `paid` com `isBlocked: true` está em disputa: o valor fica no saldo bloqueado até a decisão. Em `pre_chargeback`, olhe `chargebackAlertRefunded`: `true` significa que o valor já foi devolvido ao comprador.

## Como decidir pelo status

| `status` | O que fazer no pedido |
| - | - |
| `pending` | Aguardar. No Pix, o cliente ainda não pagou o QR Code |
| `paid` | Liberar o produto ou serviço. Se `isBlocked` for `true`, tratar como em disputa |
| `refused` / `failed` | Não liberar. Oferecer nova tentativa ou outra forma de pagamento |
| `in_analysis` | Aguardar a conclusão da análise antifraude |
| `authentication_required` | A cobrança espera a autenticação do comprador. Veja [3DS gerenciado](https://docs.fastpaybrasil.com/guias/3d-secure/gerenciado.md) |
| `refunded` | Cancelar o pedido e, se for o caso, revogar o acesso |
| `pre_chargeback` | Tratar conforme `chargebackAlertRefunded` |
| `chargeback` | Chargeback formalizado. Veja [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md) |

## Exemplos por caso de uso

> [tab] Confirmar webhook
>
> Ao receber `charge.paid`, confirme o status antes de liberar o pedido.
>
> ```javascript theme={null}
> app.post('/webhooks/finvia', async (req, res) => {
>   res.status(200).send('OK');
>
>   const { event, data } = req.body;
>   if (event !== 'charge.paid') return;
>
>   const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
>   const response = await fetch(`https://api-global.fastpaybrasil.com/v1/charges/${data.id}`, {
>     headers: { Authorization: `Basic ${credentials}` },
>   });
>   const texto = await response.text();
>   if (!texto) return; // corpo vazio: cobrança não encontrada para esta chave
>   const charge = JSON.parse(texto);
>
>   if (charge.status === 'paid' && !charge.isBlocked) {
>     await liberarPedido(charge.id);
>   }
> });
> ```

> [tab] Acompanhar bloqueio
>
> A liberação do bloqueio não gera webhook. Consulte as cobranças que o seu sistema marcou como "em disputa".
>
> ```javascript theme={null}
> const charge = await consultarCobranca(chargeId);
>
> if (charge.status === 'paid' && charge.isBlocked === false) {
>   // Bloqueio liberado: o valor voltou ao saldo disponível
> } else if (charge.status === 'refunded' || charge.status === 'chargeback') {
>   // Disputa perdida: registre a perda
> }
> ```

> [tab] Reexibir o Pix
>
> O cliente fechou a página antes de pagar. Mostre o mesmo QR Code de novo.
>
> ```javascript theme={null}
> const charge = await consultarCobranca(chargeId);
>
> if (charge.status === 'pending' && charge.paymentDetails) {
>   const { copyPaste, qrCodeBase64 } = charge.paymentDetails;
>   // Use qrCodeBase64 no src de uma imagem. Se vier null, gere o QR a partir de copyPaste.
> }
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `200` com corpo vazio para uma cobrança que existe | Chave de outro ambiente (teste x produção) ou de outra conta | Use a chave do mesmo ambiente e da mesma conta que criou a cobrança |
| `200` com corpo vazio logo depois de criar | `id` copiado errado ou trocado por outro identificador, como o `pspRefId` | Use o campo `id` devolvido na criação |
| `metadata.order_id` não encontrado | Nas respostas de `GET`, chaves enviadas em snake\_case vêm em camelCase | Leia `metadata.orderId` ou envie as chaves em camelCase. Veja [Metadata](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md#metadata) |
| Pedido continua "em disputa" para sempre | A liberação do bloqueio não gera webhook | Consulte a cobrança periodicamente e leia `isBlocked` |
| `401` | Cabeçalho ausente ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` |
| QR Code não aparece | `qrCodeBase64` veio `null` ou ausente | Gere a imagem a partir de `copyPaste` |

```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 "https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$FINVIA_API_KEY:"
```

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

const response = await fetch('https://api-global.fastpaybrasil.com/v1/charges/2vorkDcXyvzifL63YX09S9VqcnI', {
  headers: { Authorization: `Basic ${credentials}` },
});

const texto = await response.text();
const charge = texto ? JSON.parse(texto) : null; // null: cobrança não encontrada
```

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

```json 200 Cartão com split theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "paid",
  "isBlocked": false,
  "blockedAt": null,
  "blockedReason": null,
  "chargebackAlertRefunded": null,
  "chargebackAlertReason": null,
  "pspRefId": "ch_123456789",
  "amount": 100,
  "currency": "BRL",
  "spread": 5,
  "net": 95,
  "customer": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "name": "Joao da Silva",
    "email": "joao@email.com",
    "document": "529.982.247-25"
  },
  "paymentMethod": {
    "type": "credit_card",
    "firstSix": "411111",
    "lastFour": "1111",
    "expirationMonth": "12",
    "expirationYear": "2030",
    "holderName": "JOAO DA SILVA",
    "installments": 1
  },
  "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
  "paymentDetails": {
    "firstSix": "411111",
    "lastFour": "1111",
    "expirationMonth": "12",
    "expirationYear": "2030",
    "holderName": "JOAO DA SILVA",
    "installments": 1
  },
  "splits": [
    {
      "id": "2vorkSp1It2Re3Gi4St5Ro6AbCd",
      "destinyMerchantId": "2vorkRc9Ab8Cd7Ef6Gh5Ij4KlMn",
      "destinyMerchantName": "Loja Parceira",
      "splitPercentage": "30.00000000",
      "splitAmount": 28.5,
      "referenceAmount": "net"
    }
  ],
  "metadata": { "orderId": "ORD-123" },
  "paidAt": "2026-10-15T14:30:00Z",
  "createdAt": "2026-10-15T14:30:00Z",
  "updatedAt": "2026-10-15T14:30:00Z"
}
```

```json 200 Pix bloqueado theme={null}
{
  "id": "2vorkPx3Bl4Oc5Ke6Dd7Ab8CdEf",
  "status": "paid",
  "isBlocked": true,
  "blockedAt": "2026-10-20T09:00:00Z",
  "blockedReason": "MED em análise",
  "chargebackAlertRefunded": null,
  "chargebackAlertReason": null,
  "amount": 100,
  "currency": "BRL",
  "spread": 1,
  "net": 99,
  "paymentMethod": { "type": "pix" },
  "merchantId": "2vorkMs8Ty1UvW4xZa7Bc0DeFgH",
  "paymentDetails": {
    "endToEndId": "E12345678202610151430abcdef12345",
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565qrcode.example.com/pix/v2/cobv/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865406100.005802BR5913EXAMPLE STORE6009SAO PAULO62070503***6304ABCD"
  },
  "metadata": { "orderId": "ORD-456" },
  "paidAt": "2026-10-15T14:31:00Z",
  "createdAt": "2026-10-15T14:30:00Z",
  "updatedAt": "2026-10-20T09:00:00Z"
}
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Veja também

> [card] [Listar cobranças](https://docs.fastpaybrasil.com/referencia/cobrancas/listar.md)
>
> Várias cobranças com filtros por status, data e busca.

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

> [card] [Bloqueio, chargeback e MED](https://docs.fastpaybrasil.com/guias/bloqueio-chargeback-med.md)
>
> O que significam `isBlocked` e o bloqueio de saldo.

> [card] [Split](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
>
> Prazos e regras do repasse.


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