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

> Devolve todos os dados de uma assinatura, incluindo plano, cliente, merchant e o histórico de cobranças.

Esta rota traz a ficha completa de uma assinatura: status atual, período vigente, dados do plano e do cliente, `metadata` e o **histórico de todas as tentativas de cobrança**, ciclo a ciclo. É a fonte para conferir o estado real depois de receber um webhook, montar a tela "Minha assinatura" e responder ao atendimento quando o cliente pergunta o que foi cobrado.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Ao receber um webhook `subscription.*` | Consulte pelo `data.id` para confirmar o status antes de liberar ou bloquear acesso |
| Tela "Minha assinatura" | Exiba plano, período atual e histórico de `charges` |
| Atendimento ao cliente | Veja quais ciclos foram pagos, recusados ou estornados, e o motivo da falha |
| Abrir a cobrança de um ciclo em `GET /v1/charges/{id}` | Esta rota não traz o id da cobrança. Veja [Onde obter o id da cobrança](#onde-obter-o-id-da-cobrança) |
| Controlar acesso depois de cancelamento regular | Use o `accessRevokedAt` devolvido por [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md), a data até a qual o acesso vale (fim do período pago) |
| Ver várias assinaturas de uma vez | Use [Listar assinaturas](https://docs.fastpaybrasil.com/referencia/assinaturas/listar.md) |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **visualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager**, **Operador** e **Visualizador**. Os perfis Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* Tenha o `id` da assinatura, devolvido na criação, na listagem ou no campo `data.id` dos webhooks de assinatura.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

## Parâmetros de caminho

**id** `string` *required*

Identificador único da assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

## Respostas

**id** `string`

Identificador único da assinatura.

**status** `string`

Status da assinatura:

| Valor | Significado |
| - | - |
| `pending_activation` | A primeira cobrança foi recusada ou está em análise. A assinatura não está ativa, não cobra, não renova e não tem retentativa automática. Se a análise aprovar o pagamento, passa a `active` automaticamente |
| `active` | Ativa e em dia. Continua `active` durante as retentativas de cobrança |
| `cancelled` | Cancelada |
| `expired` | Encerrada: limite de retentativas esgotado ou o plano chegou ao `endDate` |

**currentPeriodStart** `string | null`

Início do período de cobrança atual (formato `date-time`).

**currentPeriodEnd** `string | null`

Fim do período de cobrança atual (formato `date-time`).

**cancelledAt** `string | null`

Data do cancelamento (formato `date-time`). `null` se não foi cancelada.

**cancellationType** `string | null`

Tipo de cancelamento: `regret` (até 7 dias da criação) ou `regular` (depois de 7 dias). `null` se não foi cancelada.

**refunded** `boolean`

`true` quando havia cobranças pagas e todas foram estornadas (cancelamento por arrependimento). `false` no cancelamento regular, no arrependimento sem cobrança paga (ex.: trial grátis) ou quando um estorno não foi concluído.

**createdAt** `string`

Data de criação (formato `date-time`).

**updatedAt** `string`

Data da última atualização (formato `date-time`).

**plan** `object`

Dados do plano assinado.

**propriedades**

**id** `string`

ID do plano.

**name** `string`

Nome do plano. Ex.: `Plano Premium Mensal`.

**price** `number`

Preço do plano, em reais. Ex.: `99.9`.

**currency** `string`

Código da moeda. Ex.: `BRL`.

**recurrenceType** `string`

Periodicidade. Ex.: `monthly`.

**customer** `object`

Dados do cliente.

**propriedades**

**id** `string`

ID do cliente.

**name** `string`

Nome do cliente.

**email** `string`

E-mail do cliente.

**merchant** `object`

Dados do merchant dono da assinatura.

**propriedades**

**id** `string`

ID do merchant.

**tradeName** `string`

Nome fantasia do merchant. Ex.: `Loja Exemplo`.

**charges** `object[]`

Histórico de tentativas de cobrança da assinatura. Há uma linha por tentativa: as retentativas recusadas de um ciclo repetem o mesmo `billingCycle`. A lista vem ordenada por `billingCycle` decrescente (o ciclo mais recente primeiro).

**propriedades**

**id** `string`

ID do **registro de cobrança da assinatura**, o mesmo valor de `data.charge.id` nos webhooks de assinatura. Não é o id usado em `GET /v1/charges/{id}`.

**billingCycle** `integer`

Número do ciclo de cobrança. `0` é a cobrança do trial pago. Ex.: `1`.

**billingPeriodStart** `string`

Início do período cobrado (formato `date-time`).

**billingPeriodEnd** `string`

Fim do período cobrado (formato `date-time`).

**amount** `number`

Valor cobrado, em reais. Ex.: `99.9`.

**currency** `string`

Código da moeda. Ex.: `BRL`.

**status** `string`

Status da tentativa: `pending` (em análise), `paid` (paga), `failed` (falhou) ou `refunded` (estornada).

**pspTransactionId** `string | null`

ID da transação no processador (PSP). Ex.: `12345`.

**failureReason** `string | null`

Motivo da falha, quando houver.

**createdAt** `string`

Data da cobrança (formato `date-time`).

**metadata** `object | null`

Informações suas guardadas na assinatura. Ex.: `{"referralCode": "PROMO2024"}`.

### Onde obter o id da cobrança

`charges[].id` não serve em `GET /v1/charges/{id}`. O id da cobrança (o mesmo dos webhooks `charge.*`) aparece hoje em:

| Onde | Campo |
| - | - |
| Resposta de [Criar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md) | `firstCharge.chargeId` e `trialCharge.chargeId` |
| Webhooks de assinatura | `data.charge.charge_id` (o `data.charge.id` é o registro, igual a `charges[].id` desta rota) |
| Listagem de cobranças do plano, `GET /v1/subscription-plans/{id}/charges` | `data[].chargeId`. Cada item traz também `id` (o registro), `subscriptionId` e `billingCycle`, o que permite relacionar o registro desta rota à cobrança. `chargeId` vem `null` quando a tentativa nem chegou ao processador (por exemplo, cartão indisponível) |

A listagem de cobranças do plano exige a mesma permissão desta rota (visualizar assinaturas).

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Assinatura encontrada | Objeto da assinatura com `charges` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão visualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Assinatura não encontrada | `{"statusCode": 404, "message": "Subscription not found"}` |

> [!NOTE]
>
> **Para o negócio:** o `plan.price` mostra o preço do plano e o `charges[].amount` mostra o que de fato foi cobrado em cada ciclo. Como editar um plano não muda assinaturas existentes, use o histórico de `charges` para responder ao cliente quanto ele paga. O `failureReason` é um texto descritivo, útil para o atendimento explicar uma recusa.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` "Subscription not found" | `id` errado, de outra conta, ou id de plano ou cobrança no lugar do id da assinatura | Use o `id` devolvido na criação ou o `data.id` do webhook |
| `GET /v1/charges/{id}` não encontra a cobrança de um ciclo | Foi usado `charges[].id`, que é o registro da assinatura | Use o `chargeId` (veja [Onde obter o id da cobrança](#onde-obter-o-id-da-cobrança)) |
| O mesmo ciclo aparece mais de uma vez em `charges` | Cada retentativa recusada gera uma linha com o mesmo `billingCycle` | Considere a linha com `status` `paid` do ciclo, se houver |
| `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão visualizar assinaturas (ex.: Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| Acesso cortado cedo demais após cancelamento regular | O `status` vira `cancelled` assim que a assinatura é cancelada | No cancelamento regular, mantenha o acesso até o `accessRevokedAt` devolvido pelo cancelamento |

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

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q',
  { headers: { Authorization: `Basic ${credentials}` } },
);

const subscription = await response.json();
const ultimaTentativa = subscription.charges[0]; // lista em ordem decrescente de billingCycle
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q",
    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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q');

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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q"))
            .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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q");

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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q", 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/subscriptions/2RhQg9M7ZCg3X3nMb9W1kX8Q")
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 theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "active",
  "currentPeriodStart": "2024-01-15T10:30:00.000Z",
  "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
  "cancelledAt": null,
  "cancellationType": null,
  "refunded": false,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "plan": {
    "id": "2RhQg9M7ZCg3X3nMb9W2kY9R",
    "name": "Plano Premium Mensal",
    "price": 99.9,
    "currency": "BRL",
    "recurrenceType": "monthly"
  },
  "customer": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "name": "Joao Silva",
    "email": "joao@email.com"
  },
  "merchant": {
    "id": "2Mk4pTq8RwZ1yVb6NcX3sLd7Hf9",
    "tradeName": "Loja Exemplo"
  },
  "charges": [
    {
      "id": "3Fh8nQ2wLr5tYb7cXz9VkP4mJd1",
      "billingCycle": 1,
      "billingPeriodStart": "2024-01-15T10:30:00.000Z",
      "billingPeriodEnd": "2024-02-15T10:30:00.000Z",
      "amount": 99.9,
      "currency": "BRL",
      "status": "paid",
      "pspTransactionId": "12345",
      "failureReason": null,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "metadata": {
    "referralCode": "PROMO2024"
  }
}
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Subscription not found"
}
```

## Veja também

> [card] [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, renovação, retentativas e cancelamento.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Fluxo completo, do cliente à cobrança recorrente.

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e status do plano.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos e correlação com os webhooks de cobrança.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guarde o cartão no cofre antes de criar a assinatura.

> [card] [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md)
>
> Cancelamento com ou sem estorno.


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