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

# Criar uma assinatura

> Vincula um cliente a um plano, registra ou reutiliza o cartão e processa a primeira cobrança da assinatura.

Esta é a rota do checkout de assinatura. Com ela você liga um **cliente** a um **plano** e define o **cartão** que será cobrado automaticamente a cada ciclo, sem que o cliente precise digitar o CVV de novo. A primeira cobrança (ou a validação do cartão, no trial grátis) acontece na própria chamada, e as renovações seguintes ficam por conta da Finvia.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Cliente já cadastrado com cartão salvo (fluxo recomendado) | `customerId` + `cardTokenId` |
| Cliente já cadastrado digitando o cartão no checkout | `customerId` + `paymentMethod` |
| Cliente novo no checkout | Objeto `customer` (com `document`) + `paymentMethod` |
| Plano com trial, mas o cliente quer começar pagando | `skipTrial: true` |
| Guardar dados seus na assinatura (campanha, ID interno) | `metadata` |
| Venda avulsa ou recompra com o cliente presente | Use [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) |
| Trocar cartão ou plano de uma assinatura | Não existe troca. Cancele a assinatura e crie outra por esta rota |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **criar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* Tenha um plano **ativo** ([Criar plano](https://docs.fastpaybrasil.com/referencia/planos/criar.md), [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md)). Plano inexistente ou inativo devolve `404`.
* O cliente precisa ter **e-mail** e **CPF ou CNPJ** quando o cartão é cadastrado nesta chamada (cartão em `paymentMethod`). O tipo do documento é deduzido pela quantidade de dígitos: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento.
* No fluxo recomendado, registre antes o cartão em [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md). O cartão precisa pertencer ao mesmo merchant da chave usada. Com `cardTokenId`, o cartão já está cadastrado e não há nova checagem de documento.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R\$ 1,00 do trial grátis. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

## O que acontece no checkout

**1. Validação do plano**

O plano informado em `subscriptionPlanId` precisa existir e estar ativo.

**2. Cliente**

Com `customerId`, o cliente existente é usado. Com o objeto `customer`, a Finvia localiza o cliente pelo e-mail ou cria um novo. Se o cliente já existe, vale o documento do cadastro, e não o enviado na requisição.

**3. Cartão**

Com `paymentMethod`, o cartão é registrado no cofre da Finvia e nasce `active`. Sem e-mail ou sem CPF/CNPJ no cliente, a resposta é `400` e a assinatura não é criada. Com `cardTokenId`, o cartão já registrado é usado.

**4. Validação do trial grátis**

Só em plano com trial grátis e sem `skipTrial: true`: a Finvia cobra R\$ 1,00 e estorna em seguida (o estorno é assíncrono). Se essa cobrança for recusada, ficar em análise ou o processador não responder, a resposta é `422 CARD_VALIDATION_FAILED` e nada é criado: nem assinatura, nem webhook. Nos demais planos, a própria primeira cobrança valida o cartão.

**5. Primeira cobrança**

A cobrança acontece na criação da assinatura: sem trial, cobra o valor cheio; com trial pago, cobra o valor do trial; com `skipTrial: true`, cobra o valor cheio.

**6. Assinatura criada**

Se a cobrança for aprovada, a assinatura fica `active`. Se for recusada ou ficar em análise, fica `pending_activation`. O ciclo fica ancorado na data e hora da contratação (ou no fim do trial, em planos com trial).

## Corpo da requisição

Campo obrigatório: `subscriptionPlanId`. Informe também o cliente (`customerId` **ou** `customer`) e o cartão (`cardTokenId` **ou** `paymentMethod`).

**subscriptionPlanId** `string` *required*

ID do plano de assinatura. Ex.: `2RhQg9M7ZCg3X3nMb9W2kY9R`.

> [!NOTE]
>
> Não há como escolher o dia de cobrança. O ciclo é ancorado na data e hora da contratação, ou no fim do trial. Um campo `billingDay` enviado é ignorado, sem erro e sem efeito. As regras de renovação estão em [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md).

**customerId** `string`

ID de um cliente já cadastrado. Use este campo **ou** o objeto `customer`, nunca os dois. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**customer** `object`

Dados do cliente. Use este objeto **ou** `customerId`, nunca os dois. A Finvia procura o cliente pelo e-mail e, se não encontrar, cria um novo.

**propriedades**

**name** `string` *required*

Nome do cliente. Ex.: `Joao Silva`.

**email** `string` *required*

E-mail do cliente (formato `email`). Ex.: `joao@email.com`.

**document** `object`

Documento do cliente. Obrigatório quando o cartão vai em `paymentMethod`. Se já existir na conta um cliente com o mesmo e-mail, vale o documento desse cadastro, e não o desta requisição.

**propriedades**

**type** `string`

Tipo do documento: `cpf` ou `cnpj`. O tipo efetivo é deduzido pela quantidade de dígitos de `id`, e não por este campo.

**id** `string`

CPF (11 dígitos) ou CNPJ (14 dígitos). A pontuação é aceita e removida. Qualquer outro tamanho conta como cliente sem documento. Ex.: `52998224725`.

**phoneNumber** `string`

Telefone do cliente. Ex.: `+5511987654321`.

**cardTokenId** `string`

ID de um cartão já registrado em [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md), pela mesma conta. Use este campo **ou** `paymentMethod`, nunca os dois. As cobranças da assinatura não pedem CVV. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

**paymentMethod** `object`

Dados de um cartão novo, que é registrado junto com a assinatura. Use este objeto **ou** `cardTokenId`, nunca os dois.

**propriedades**

**number** `string` *required*

Número do cartão. Ex.: `4111111111111111`.

**holderName** `string` *required*

Nome impresso no cartão. Ex.: `JOAO SILVA`.

**expirationMonth** `string` *required*

Mês de validade, de `01` a `12`, com 2 caracteres (`minLength` 2, `maxLength` 2). Ex.: `12`.

**expirationYear** `string` *required*

Ano de validade no formato `YYYY`, com 4 caracteres (`minLength` 4, `maxLength` 4). Ex.: `2028`.

**cvv** `string` *required*

Código de segurança. Mínimo de 3 caracteres. Ex.: `123`.

**validateCard** `boolean` *deprecated*

Obsoleto. O campo é aceito, mas não tem efeito: o cartão nasce `active`, sem transação de teste e sem etapa de ativação. A única validação extra é a de R\$ 1,00 do trial grátis, que não depende deste campo.

**skipTrial** `boolean`

Quando `true`, ignora o trial do plano (se houver) e cobra o valor cheio na criação da assinatura. O padrão é `false`.

**metadata** `object`

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

> [!NOTE]
>
> **Para o negócio:** no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R\$ 1,00 (a cobrança de validação e o estorno). Avise isso no checkout. Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até 15 minutos, a API reaproveita a validação aprovada e não cobra o R\$ 1,00 de novo.

## Respostas

**id** `string`

Identificador único da assinatura. Guarde este valor: ele é usado para consultar, atualizar, cancelar e conciliar com os webhooks (`data.id` nos eventos `subscription.*`).

**status** `string`

Situação da assinatura:

| Valor | Significado |
| - | - |
| `active` | Assinatura ativa e cobrando normalmente |
| `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 |

Na criação, só esses dois status são possíveis.

### Assinatura em `pending_activation`

A API não tenta de novo a primeira cobrança, e [Atualizar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/atualizar.md) só aceita assinaturas `active`. A assinatura só sai desse status sozinha em um caso: a primeira cobrança (ou a do trial pago) ficou em análise (`firstCharge.pending: true` ou `trialCharge.pending: true`) e a análise aprovou. Aí ela passa a `active` e o webhook `subscription.activated` é enviado. Se a análise recusar, chega `subscription.payment_failed` e a assinatura continua `pending_activation`.

Para tentar de novo (por exemplo, com outro cartão), crie uma **nova** assinatura por esta rota. A API não reaproveita a pendente: a nova assinatura tem outro `id`. Cancele a pendente em [Cancelar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/cancelar.md) para que ela não fique na listagem; enquanto estiver pendente, ela não cobra nada.

**cardTokenId** `string`

ID do cartão registrado usado na assinatura. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

**currentPeriodStart** `string`

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

**currentPeriodEnd** `string`

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

**cardValidation** `object`

Só em plano com trial grátis (sem `skipTrial`). Resultado da validação de R\$ 1,00.

**propriedades**

**validated** `boolean`

`true` quando a validação foi aprovada.

**amount** `number`

Valor da validação, em reais. Ex.: `1`.

**firstCharge** `object | null`

Resultado da primeira cobrança.

**propriedades**

**success** `boolean`

`true` quando a cobrança foi aprovada.

**pending** `boolean`

`true` quando o pagamento está **em análise** no processador. Não crie outra assinatura: aguarde o webhook `subscription.activated` (aprovado) ou `subscription.payment_failed` (recusado).

**chargeId** `string`

Id da cobrança, o mesmo usado em `GET /v1/charges/{id}` e nos webhooks `charge.*`. Guarde este valor: [Consultar assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/consultar.md) não o devolve.

**nsuOperacao** `string`

Identificador da operação no processador (PSP). Ex.: `123456789`.

**codigoAutorizacao** `string`

Código de autorização. Ex.: `ABC123`.

**message** `string`

Mensagem do resultado. Ex.: `Transaction approved`.

**trialCharge** `object | null`

Resultado da cobrança do trial pago. Traz os mesmos campos de `firstCharge`, inclusive `success`, `pending` e `chargeId`.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Assinatura criada | `id`, `status`, `cardTokenId`, `currentPeriodStart`, `currentPeriodEnd`, `firstCharge` e, conforme o plano, `trialCharge` e `cardValidation` |
| `400` | Cliente sem e-mail ou sem CPF/CNPJ ao cadastrar o cartão | `{"statusCode": 400, "message": "Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador"}` |
| `400` | Dados inválidos ou falha na criação | `{"statusCode": 400, "message": "Failed to create subscription"}` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão criar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Plano não encontrado ou inativo | `{"statusCode": 404, "message": "Subscription plan not found or inactive"}` |
| `409` | Já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo) | `{"code": "CARD_VALIDATION_IN_PROGRESS", "message": "..."}` |
| `422` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | `{"code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: <motivo>"}` |
| `429` | 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora | `{"code": "CARD_VALIDATION_RATE_LIMITED", "message": "..."}` |

### Erros da validação do trial grátis

Os erros `409`, `422` e `429` têm o formato `{ code, message }`, sem `statusCode`. Decida o fluxo pelo `code` e use a `message` só para exibir. No `422`, o `<motivo>` é texto livre: pode ser o motivo devolvido pelo processador, `pagamento em análise. Use outro cartão.`, `cobrança recusada.` ou `processador indisponível.`. Nesses casos nada é criado: nem assinatura, nem webhook.

> [!NOTE]
>
> **Para o negócio:** a primeira cobrança acontece na criação da assinatura. Se ela for recusada, a assinatura fica `pending_activation`, não cobra e não renova: o checkout deve oferecer em seguida outro cartão, criando uma nova assinatura. Depois de ativa, as renovações são feitas por uma rotina que roda às 6h, 12h e 18h (horário de Brasília), com retentativas em caso de recusa. Os detalhes estão em [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md).

## Exemplos por caso de uso

> [tab] Cartão salvo (recomendado)
>
> Cliente e cartão já cadastrados. O cartão foi registrado em `POST /v1/cards` e nasceu `active`.
>
> ```json theme={null}
> {
>   "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>   "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
>   "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
> }
> ```

> [tab] Cartão digitado no checkout
>
> Cliente já cadastrado, cartão novo informado na própria chamada.
>
> ```json theme={null}
> {
>   "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>   "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
>   "paymentMethod": {
>     "number": "4111111111111111",
>     "holderName": "JOAO SILVA",
>     "expirationMonth": "12",
>     "expirationYear": "2028",
>     "cvv": "123"
>   }
> }
> ```

> [tab] Cliente novo
>
> Primeiro acesso do cliente. A Finvia procura pelo e-mail e cria o cadastro se não existir.
>
> ```json theme={null}
> {
>   "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>   "customer": {
>     "name": "Joao Silva",
>     "email": "joao@email.com",
>     "document": { "type": "cpf", "id": "52998224725" },
>     "phoneNumber": "+5511987654321"
>   },
>   "paymentMethod": {
>     "number": "4111111111111111",
>     "holderName": "JOAO SILVA",
>     "expirationMonth": "12",
>     "expirationYear": "2028",
>     "cvv": "123"
>   },
>   "metadata": { "referralCode": "PROMO2024" }
> }
> ```

> [tab] Pular o trial
>
> Plano com trial, mas o cliente quer começar já no plano pago.
>
> ```json theme={null}
> {
>   "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
>   "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
>   "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
>   "skipTrial": true
> }
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` "Subscription plan not found or inactive" | Plano inexistente, de outra conta ou `inactive` | Confira o plano em [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md) |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão criar assinaturas (ex.: Visualizador, 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) |
| `400` "Failed to create subscription" | Dados inválidos ou falha na criação | Revise o corpo: cliente e cartão informados uma vez cada, campos do cartão completos |
| Cobrança real feita com a chave de teste | Assinaturas não têm modo de teste | Homologue com cartão real de valor baixo e cancele em até 7 dias para que as cobranças pagas sejam estornadas |
| `400` com `O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos | Informe e-mail e CPF ou CNPJ |
| Mesmo erro de documento, com CPF na requisição | Já existe um cliente com o mesmo e-mail, cadastrado com outro documento. Vale o documento do cadastro | Crie um cliente com e-mail e CPF ou CNPJ e envie o `customerId` dele |
| `cardTokenId` rejeitado | Cartão registrado por outro merchant ou subconta | Registre o cartão com a mesma chave usada para criar a assinatura |
| `422 CARD_VALIDATION_FAILED` | Validação de R\$ 1,00 do trial grátis recusada, em análise ou sem resposta do processador | Peça outro cartão ao comprador |
| `409 CARD_VALIDATION_IN_PROGRESS` | A mesma requisição foi enviada em paralelo | Aguarde a resposta da primeira chamada antes de reenviar |
| `429 CARD_VALIDATION_RATE_LIMITED` | Recusas demais do mesmo cartão (3 em 24 horas) ou da conta (30 em 1 hora) | Peça outro cartão e revise o fluxo de checkout que está gerando as tentativas |
| `status` `pending_activation` | Primeira cobrança recusada ou em análise | Se em análise (`firstCharge.pending: true`), aguarde os webhooks. Se recusada, crie uma nova assinatura com outro cartão e cancele a pendente |
| Assinatura duplicada após timeout | Reenvio sem verificar se a primeira foi criada | A API não suporta `Idempotency-Key`. Liste as assinaturas do cliente com `customerId` antes de reenviar |

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

{
  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscriptions" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
    "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
  }'
```

```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', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    subscriptionPlanId: '2RhQg9M7ZCg3X3nMb9W2kY9R',
    customerId: '2vorkDcXyvzifL63YX09S9VqcnI',
    cardTokenId: '36OO3bcGjhPjjF3tzrqOGcmQuKo',
    metadata: { internalUserId: '12345' },
  }),
});

const subscription = await response.json();
if (subscription.status === 'pending_activation') {
  // primeira cobrança recusada ou em análise: não libere o acesso ainda
}
```

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

import requests

payload = {
    "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
    "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/subscriptions",
    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 = [
    'subscriptionPlanId' => '2RhQg9M7ZCg3X3nMb9W2kY9R',
    'customerId' => '2vorkDcXyvzifL63YX09S9VqcnI',
    'cardTokenId' => '36OO3bcGjhPjjF3tzrqOGcmQuKo',
];

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

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 = """
            {
              "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
              "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
              "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscriptions"))
            .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 = """
{
  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscriptions");
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(`{
	  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
	  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
	  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
	}`)

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

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

puts response.code
puts response.body
```

```json 201 theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "status": "active",
  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "currentPeriodStart": "2024-01-15T10:30:00.000Z",
  "currentPeriodEnd": "2024-02-15T10:30:00.000Z",
  "firstCharge": {
    "success": true,
    "chargeId": "2xKp7QmR4tVw9YzA1bC3dE5fG6h",
    "nsuOperacao": "123456789",
    "codigoAutorizacao": "ABC123",
    "message": "Transaction approved"
  }
}
```

```json 422 theme={null}
{
  "code": "CARD_VALIDATION_FAILED",
  "message": "Não foi possível validar o cartão: cobrança recusada."
}
```

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

```json 400 theme={null}
{
  "statusCode": 400,
  "message": "Failed to create subscription"
}
```

## Veja também

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

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> `subscription.created`, `subscription.activated` e demais eventos.

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

> [card] [Homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenários SUB-01 a SUB-06.


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