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

# Cofre de cartões

> Salve o cartão do cliente com segurança e use o token em compras com um clique e em assinaturas.

Esta página trata do **cadastro e da gestão** dos cartões: registrar, conferir o status, listar e excluir. A cobrança com um cartão já guardado (compra com um clique) está em [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md).

O cofre de cartões guarda o cartão de crédito do cliente de forma segura e devolve um identificador. Com ele, a sua aplicação deixa de manipular o número do cartão nas próximas compras e pode usar o mesmo cartão em uma assinatura.

> [!NOTE]
>
> **Para o negócio:** o cartão salvo permite a compra com um clique, em que o cliente só confirma o código de segurança, e é a base das assinaturas. O seu sistema guarda só o identificador do cartão e os quatro últimos dígitos para exibição; o número completo fica no cofre da Finvia.

> [!WARNING]
>
> **O cadastro de cartão não tem modo de teste.** Mesmo com a chave de teste (`sk_test_`), `POST /v1/cards` registra o cartão de verdade na adquirente. O cadastro não cobra nada: não há transação de validação. O cofre também é o mesmo para teste e produção: um `cardTokenId` criado na homologação funciona com a chave de produção, e aí a mesma chamada de cobrança é real.

## Quando usar

| Situação | Como o cofre entra |
| - | - |
| Recompra com um clique (loja, app, delivery) | Salve o cartão na primeira compra. A cobrança está em [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) |
| Assinatura mensal | Registre o cartão e crie a assinatura com `cardTokenId` |
| Carteira de cartões na área do cliente | Liste os cartões do cliente com `GET /v1/cards?customerId=...` |
| Cliente pede para remover o cartão | Exclua com `DELETE /v1/cards/{id}`, que revoga o token |
| Cobrar automaticamente sem o cliente presente, fora de uma assinatura | Não é possível. A cobrança avulsa com cartão salvo exige o CVV a cada vez. Use [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md) |

## Como funciona

O desenho abaixo mostra o registro do cartão no cofre e os usos do id do cartão salvo.

```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 A as Seu servidor
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
        participant V as Cofre de cartões
    end
    box rgb(244,240,255) Fora da Finvia
        participant Q as Adquirente
    end
    C->>A: Informa os dados do cartão
    A->>F: POST /v1/cards · customerId · número · validade · CVV
    F->>V: Guarda o cartão
    F->>Q: Registra o cartão, sem cobrar nada
    F-->>A: 201 · id · maskedNumber · status active
    Note over A: Grave só o id e o maskedNumber. Nunca o número completo nem o CVV
    opt Compra com um clique
        C->>A: Digita o CVV
        A->>F: POST /v1/charges · cardTokenId + cvv
    end
    opt Assinatura
        A->>F: POST /v1/subscriptions · cardTokenId
        Note over A,F: As cobranças de cada ciclo não pedem CVV
    end
    opt Cliente pede para remover
        A->>F: DELETE /v1/cards/{id}
        F->>V: Revoga o token
    end
```

**1. Tenha um cliente cadastrado**

O cartão é vinculado a um cliente (`customerId`), que precisa ter e-mail e CPF ou CNPJ. Veja [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md).

**2. Registre o cartão**

Envie os dados do cartão para `POST /v1/cards`. O cartão é guardado no cofre, já nasce `active` e a resposta traz o `id` do cartão salvo.

**3. Guarde o id e o número mascarado**

Grave o `id` e o `maskedNumber` (ex.: `****1111`) no seu sistema. Nunca grave o número completo nem o CVV.

**4. Use o cartão**

Em uma cobrança, envie o `id` como `cardTokenId`, com o CVV digitado pelo cliente ([Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)). Em uma assinatura, envie `cardTokenId`.

**5. Remova quando necessário**

`DELETE /v1/cards/{id}` revoga o token, que deixa de servir para cobranças e assinaturas.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Cliente | Precisa de **e-mail** e **CPF ou CNPJ**. O tipo é deduzido pela quantidade de dígitos do documento (11 é CPF, 14 é CNPJ). Sem isso, a resposta é `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` |
| Dono do cartão | O cartão pertence ao merchant da chave de API que o registrou. Ele não pode ser usado por outro merchant nem por outra subconta |
| Ativação | Não existe etapa de ativação. O cartão nasce `active`, sem transação de teste. O campo `validateCard` é obsoleto e não tem efeito |
| CVV na cobrança | Toda cobrança em `POST /v1/charges` com `cardTokenId` exige o `cvv`. Sem ele, a resposta é `400 CVV is required when using cardTokenId`. A recorrência das assinaturas é a única cobrança que dispensa o CVV |
| Uso em cobrança | A cobrança recusa cartão `revoked` ou `expired` |
| Exclusão | Revoga o token no cofre. O cartão não pode mais ser usado em cobranças nem em assinaturas |
| Listagem | `GET /v1/cards` não é paginada e traz no máximo os 20 cartões mais recentes da conta. Filtre por `customerId` |
| Modo de teste | O cadastro não tem modo de teste: é real mesmo com a chave de teste, sem cobrar nada. A cobrança com `cardTokenId` em `POST /v1/charges` é simulada com a chave de teste. O cofre é compartilhado entre teste e produção |

> [!NOTE]
>
> O cartão salvo não permite cobrar o cliente ausente fora de uma assinatura: a cobrança avulsa exige o CVV a cada vez. As regras da cobrança estão em [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md).

### Status do cartão

A listagem e a consulta individual mostram status diferentes, porque cada uma lê uma informação diferente.

| Status | Onde aparece | Significado |
| - | - | - |
| `active` | Listagem e consulta | Cartão ativo |
| `expired` | Listagem e consulta | A validade do cartão passou |
| `revoked` | Listagem e consulta | Cartão excluído com `DELETE /v1/cards/{id}` |
| `inactive` | Só na consulta | A assinatura que usava o cartão foi cancelada e nenhuma outra o usa. Volta a `active` se o cliente assinar de novo com ele |
| `pending_validation` | Só na consulta | Aparece só em cartões antigos, registrados com o processador anterior |

O desenho abaixo mostra como o status do cartão muda.

```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
    REG(["POST /v1/cards"]):::lojista
    ACT["active<br/>nasce ativo, sem<br/>transação de teste"]:::ok
    EXP["expired<br/>validade passou"]:::erro
    REV["revoked<br/>cartão excluído"]:::erro
    INA["inactive<br/>só na consulta individual,<br/>nenhuma assinatura o usa"]:::neutro
    REC["POST /v1/charges<br/>recusa o cartão"]:::erro
    REG --> ACT
    ACT -->|"o tempo passa"| EXP
    ACT -->|"DELETE /v1/cards/{id}"| REV
    ACT -->|"assinatura<br/>cancelada"| INA
    INA -->|"assina de<br/>novo"| ACT
    EXP --> REC
    REV --> REC
    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 neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

`pending_validation` aparece só em cartões antigos, registrados com o processador anterior.

> [!WARNING]
>
> Para saber se um cartão pode ser usado em `POST /v1/charges`, use a listagem (`GET /v1/cards?customerId=...`). Hoje a consulta individual pode mostrar `active` para um cartão já excluído ou vencido. A cobrança recusa cartão `revoked` ou `expired`.

## Passo a passo

### 1. Registrar o cartão

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

{
  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "number": "1111222233334444",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "2028",
  "cvv": "123",
  "alias": "Cartão pessoal"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/cards" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "number": "1111222233334444",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123",
    "alias": "Cartão pessoal"
  }'
```

```javascript Node.js theme={null}
// registrar-cartao.mjs (Node.js 18+, ESM)
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/cards', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: '2vorkDcXyvzifL63YX09S9VqcnI',
    number: '1111222233334444',
    holderName: 'JOAO SILVA',
    expirationMonth: '12',
    expirationYear: '2028',
    cvv: '123',
  }),
});

const card = await response.json();
if (!response.ok) {
  // 400: confira se o cliente tem e-mail e CPF ou CNPJ
  throw new Error(card.message);
}
// Guarde card.id (o cardTokenId) e card.maskedNumber no cadastro do cliente
console.log('Cartão salvo:', card.id, card.maskedNumber);
```

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

import requests

payload = {
    "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
    "number": "1111222233334444",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123",
    "alias": "Cartão pessoal",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/cards",
    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 = [
    'customerId' => '2vorkDcXyvzifL63YX09S9VqcnI',
    'number' => '1111222233334444',
    'holderName' => 'JOAO SILVA',
    'expirationMonth' => '12',
    'expirationYear' => '2028',
    'cvv' => '123',
    'alias' => 'Cartão pessoal',
];

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

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 = """
            {
              "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
              "number": "1111222233334444",
              "holderName": "JOAO SILVA",
              "expirationMonth": "12",
              "expirationYear": "2028",
              "cvv": "123",
              "alias": "Cartão pessoal"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards"))
            .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 = """
{
  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "number": "1111222233334444",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "2028",
  "cvv": "123",
  "alias": "Cartão pessoal"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/cards");
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(`{
	  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
	  "number": "1111222233334444",
	  "holderName": "JOAO SILVA",
	  "expirationMonth": "12",
	  "expirationYear": "2028",
	  "cvv": "123",
	  "alias": "Cartão pessoal"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/cards", 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/cards")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "customerId" => "2vorkDcXyvzifL63YX09S9VqcnI",
  "number" => "1111222233334444",
  "holderName" => "JOAO SILVA",
  "expirationMonth" => "12",
  "expirationYear" => "2028",
  "cvv" => "123",
  "alias" => "Cartão pessoal",
})

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

puts response.code
puts response.body
```

| Campo | Tipo | Obrigatório | Regra |
| - | - | - | - |
| `customerId` | string | Sim | ID do cliente dono do cartão |
| `number` | string | Sim | Número do cartão |
| `holderName` | string | Sim | Nome impresso no cartão |
| `expirationMonth` | string | Sim | Mês de validade com 2 caracteres (`01` a `12`) |
| `expirationYear` | string | Sim | Ano de validade com 4 caracteres (`YYYY`) |
| `cvv` | string | Sim | Código de segurança. Mínimo de 3 caracteres |
| `alias` | string | Não | Apelido do cartão (ex.: `Cartão pessoal`) |
| `validateCard` | boolean | Não | Obsoleto, sem efeito. Não é preciso enviar |

Resposta `201`:

```json theme={null}
{
  "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "token": "tok_abc123xyz",
  "maskedNumber": "****1111",
  "status": "active",
  "pendingActivation": false
}
```

| Campo | Descrição |
| - | - |
| `id` | ID do cartão salvo. É o valor usado como `cardTokenId` em cobranças e assinaturas |
| `token` | Token do cartão, para referência |
| `maskedNumber` | Número mascarado com os 4 últimos dígitos. Pode ser `null` |
| `status` | Sempre `active` |
| `pendingActivation` | Sempre `false`. Mantido por compatibilidade |

> [!TIP]
>
> **Para o desenvolvedor:** o valor que entra em `cardTokenId` é o campo `id` da resposta. A resposta também traz um campo `token`, que serve só como referência.

### 2. Usar o cartão em uma cobrança

Envie o `id` do cartão como `paymentMethod.cardTokenId`, com o CVV digitado pelo cliente. Sem o `cvv`, a resposta é `400 CVV is required when using cardTokenId`. O exemplo completo e as regras da cobrança estão em [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md).

### 3. Criar uma assinatura com o cartão salvo

```json theme={null}
{
  "subscriptionPlanId": "2RhQg9M7ZCg3X3nMb9W2kY9R",
  "customerId": "2vorkDcXyvzifL63YX09S9VqcnI",
  "cardTokenId": "36OO3bcGjhPjjF3tzrqOGcmQuKo"
}
```

O cartão precisa pertencer ao mesmo merchant da chave de API. Na assinatura, as cobranças de cada ciclo não pedem CVV. Veja [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

### 4. Listar os cartões do cliente

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/cards?customerId=2vorkDcXyvzifL63YX09S9VqcnI" \
  -u "$FINVIA_API_KEY:"
```

A resposta é um **array**, sem paginação, com no máximo os 20 cartões mais recentes. Com o filtro `customerId`, vêm só os cartões não excluídos (`active` ou `expired`):

```json theme={null}
[
  {
    "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "token": "tok_abc123xyz",
    "maskedNumber": "****1111",
    "brand": "visa",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]
```

Use `brand`, `maskedNumber` e a validade para montar a lista de cartões na área do cliente ("Visa terminado em 1111, validade 12/2028").

### 5. Consultar um cartão

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/cards/36OO3bcGjhPjjF3tzrqOGcmQuKo" \
  -u "$FINVIA_API_KEY:"
```

A resposta tem os mesmos campos da listagem. O `status` segue a tabela de [status do cartão](#status-do-cartão): para decidir se o cartão pode ser cobrado, prefira a listagem.

### 6. Excluir um cartão

```bash cURL theme={null}
curl -X DELETE "https://api-global.fastpaybrasil.com/v1/cards/36OO3bcGjhPjjF3tzrqOGcmQuKo" \
  -u "$FINVIA_API_KEY:"
```

Resposta `200`:

```json theme={null}
{
  "id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
  "deleted": true,
  "message": "Card deleted successfully"
}
```

> [!WARNING]
>
> A exclusão revoga o token no cofre. O cartão deixa de servir para cobranças **e para assinaturas**. Se houver uma assinatura usando esse cartão, as próximas renovações não terão como ser cobradas. Antes de excluir, verifique se o cartão está em uso em alguma assinatura ativa.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `400` `Failed to register card` | Dados do cartão inválidos ou falha no registro | Confira número, validade (`MM` e `YYYY`) e CVV |
| `400` `Failed to register card: 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 | Use um cliente com e-mail e CPF ou CNPJ |
| `400` `CVV is required when using cardTokenId` | Cobrança com cartão salvo sem o `cvv` | Peça o CVV ao cliente e envie em `paymentMethod.cvv` |
| Cobrança recusada com cartão que a consulta mostra `active` | Cartão excluído ou vencido. A consulta individual pode mostrar `active` nesse caso | Confira o cartão na listagem com `customerId` |
| Cartão não encontrado ao usar em subconta | O cartão pertence ao merchant que o registrou | Registre o cartão com a chave da conta que vai cobrar |
| `404` `Card not found` | `id` errado ou cartão de outro merchant | Confira o `id` (não o `token`) |
| Assinatura deixou de renovar | Cartão excluído ou vencido | Cancele a assinatura e crie outra com um cartão válido |

## Perguntas frequentes

> [accordion] O cliente precisa confirmar algum valor na fatura para ativar o cartão?
>
> Não. O cartão nasce `active`, sem transação de teste e sem etapa de ativação.

> [accordion] Posso testar o cofre no sandbox?
>
> Em parte. O cadastro (`POST /v1/cards`) não tem modo de teste: com a chave de teste, o cartão é registrado de verdade, sem cobrar nada. Já a cobrança com `cardTokenId` em `POST /v1/charges` é simulada com a chave de teste e não movimenta dinheiro; o resultado segue as regras dos [cartões de teste](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md#cartões-de-teste) aplicadas ao número guardado. As assinaturas não têm modo de teste: as cobranças delas são reais. Use um cartão real para homologar e lembre que o mesmo `cardTokenId` funciona com a chave de produção.

> [accordion] Um cartão salvo pela conta master pode ser usado por uma subconta?
>
> Não. O cartão pertence ao merchant da chave de API que o registrou e não pode ser usado por outro merchant ou subconta.

> [accordion] Como troco o cartão de uma assinatura?
>
> A assinatura não permite troca de cartão. Registre o novo cartão, cancele a assinatura atual e crie outra com o novo `cardTokenId`. A nova assinatura começa um ciclo novo, com cobrança imediata.

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| SUB-01 | Registrar cartão com cliente com e-mail e CPF ou CNPJ | `status: "active"` e `pendingActivation: false` (sem o número do cartão na evidência) |
| SUB-02 | Cobrança com um clique, descrita em [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) | Status `paid` e coleta do CVV a cada cobrança. Com a chave de teste, a cobrança é simulada |
| SUB-04 | Assinatura com `cardTokenId` | Status `active` e primeira cobrança processada. A cobrança é real, mesmo com a chave de teste: cancele em até 7 dias para que as cobranças pagas sejam estornadas |

## Veja também

> [card] [Cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
>
> Cobrança com um clique usando o cartão guardado.

> [card] [Clientes](https://docs.fastpaybrasil.com/guias/clientes.md)
>
> Cadastro do cliente dono do cartão.

> [card] [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Cobrança recorrente com cartão salvo.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Contrato completo da rota.


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