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

# Registrar um cartão

> Guarda o cartão de crédito de um cliente no cofre da Finvia para recompra com um clique e assinaturas.

Esta rota guarda o cartão de crédito de um cliente no cofre de cartões da Finvia (tokenização: o número do cartão fica com a Finvia e você recebe um identificador para usar no lugar dele). O `id` devolvido é o que você envia depois como `cardTokenId` na [cobrança com cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md) e na [assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md). O seu sistema não precisa guardar o número do cartão.

O cartão já nasce `active`: não há transação de teste, valor para conferir na fatura nem etapa de ativação. O registro também não cobra nada do cliente.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Assinatura no fluxo recomendado (cards-first) | Crie o cliente, registre o cartão aqui e crie a assinatura com `cardTokenId` |
| Recompra com um clique | Registre o cartão na primeira compra; nas seguintes, cobre com `cardTokenId` e o CVV |
| Cliente quer trocar o cartão de uma assinatura | Registre o novo cartão, cancele a assinatura e crie outra com o novo `cardTokenId` (não existe troca de cartão na assinatura) |
| Venda avulsa sem intenção de reaproveitar o cartão | Não é preciso registrar. Cobre direto em [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) com os dados do cartão |

## Antes de chamar

* Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* Tenha o `id` de um cliente com **e-mail** e **CPF ou CNPJ** ([Criar cliente](https://docs.fastpaybrasil.com/referencia/clientes/criar.md)). O tipo do documento é deduzido pela quantidade de dígitos de `document.id`: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento, e o registro é recusado.
* O cartão fica vinculado à conta dona da chave que o registrou. Ele não pode ser usado por outro merchant nem por outra subconta.

> [!WARNING]
>
> O cadastro de cartão não tem modo de teste. Mesmo com a chave de teste (`sk_test_`), o cartão é registrado de verdade na adquirente, sem nenhuma cobrança. O cofre é o mesmo para teste e produção: um `cardTokenId` criado na homologação também funciona com a chave de produção, e aí a cobrança é real. Veja como homologar em [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md).

> [!WARNING]
>
> Cartão salvo **não** permite cobrar sem o cliente presente em [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar): o CVV do comprador é obrigatório em toda cobrança com `cardTokenId`. Sem ele, a resposta é `400` com `CVV is required when using cardTokenId`. Para cobrança automática a cada ciclo, use [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

## Corpo da requisição

Campos obrigatórios: `customerId`, `number`, `holderName`, `expirationMonth`, `expirationYear` e `cvv`.

**customerId** `string` *required*

ID do cliente dono do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. O cliente precisa ter e-mail e CPF ou CNPJ.

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

**alias** `string`

Apelido opcional para o cartão. Ex.: `Cartão pessoal`.

**validateCard** `boolean` *deprecated*

Obsoleto. O campo é aceito, mas não tem efeito: o cartão sempre nasce `active`, sem transação de teste. Não é preciso enviá-lo.

## Respostas

**id** `string`

ID do token do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. É o valor usado como `cardTokenId` em cobranças e assinaturas e como `id` nas rotas de cartão.

**token** `string`

Token do cartão para referência futura. Ex.: `tok_abc123xyz`.

**maskedNumber** `string | null`

Número mascarado do cartão (4 últimos dígitos). Ex.: `****1111`. Use para mostrar o cartão ao cliente ("cartão final 1111").

**status** `string`

Situação do cartão. Vem sempre `active`.

**pendingActivation** `boolean`

Vem sempre `false`. O campo continua na resposta por compatibilidade.

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Cartão registrado | `id`, `token`, `maskedNumber`, `status`, `pendingActivation` |
| `400` | Cliente sem e-mail ou sem CPF/CNPJ | `{"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 do cartão inválidos ou outra falha no registro | `{"statusCode": 400, "message": "Failed to register card"}` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |

> [!NOTE]
>
> **Para o negócio:** com o cartão no cofre, o cliente não precisa digitar o número de novo nas próximas compras: em cada recompra, ele informa só o CVV. Em assinaturas, o cartão registrado é cobrado automaticamente a cada ciclo. O cartão fica disponível apenas para a conta que o registrou.

> [!TIP]
>
> **Para o desenvolvedor:** guarde no seu sistema o `id`, o `maskedNumber` e, se quiser, o `alias`. Nunca guarde `number` nem `cvv`. Em evidências de homologação, envie a requisição sem o número completo do cartão. Para saber depois se o cartão ainda pode ser cobrado, use [Listar cartões](https://docs.fastpaybrasil.com/referencia/cartoes/listar.md).

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `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 (passaporte, RG) | Use um cliente com e-mail e CPF ou CNPJ. O documento não pode ser alterado depois da criação: veja o [guia de clientes](https://docs.fastpaybrasil.com/guias/clientes.md) |
| `400` com `Failed to register card` | Dados do cartão inválidos (validade com tamanho errado, CVV curto) | Envie `expirationMonth` com 2 caracteres, `expirationYear` com 4 e `cvv` com pelo menos 3 |
| Cartão registrado não funciona em outra conta ou subconta | O cartão pertence à conta que o registrou | Registre o cartão com a chave da conta que vai cobrar |
| `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` |

## Como testar

O cenário **SUB-01** da [homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) pede o registro de um cartão para um cliente com e-mail e CPF ou CNPJ, com resultado `status: "active"` e `pendingActivation: false`. Na sequência, o **SUB-02** usa o cartão registrado em uma cobrança com `cardTokenId` e `cvv`. Como o cadastro não tem modo de teste, use um cartão real. Com a chave de teste, a cobrança do SUB-02 é simulada e não movimenta dinheiro.

```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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "number": "4111111111111111",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "2028",
  "cvv": "123"
}
```

```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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "number": "4111111111111111",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123"
  }'
```

```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/cards', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    number: cardNumber, // vindo do formulário, nunca gravado no seu banco
    holderName: 'MARIA SOUZA',
    expirationMonth: '10',
    expirationYear: '2028',
    cvv,
    alias: 'Cartão pessoal',
  }),
});

const card = await response.json();
if (!response.ok) {
  throw new Error(`Falha ao registrar o cartão: ${response.status}`);
}
// card.id é o cardTokenId usado em cobranças e assinaturas
```

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

import requests

payload = {
    "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "number": "4111111111111111",
    "holderName": "JOAO SILVA",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "cvv": "123",
}

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' => '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    'number' => '4111111111111111',
    'holderName' => 'JOAO SILVA',
    'expirationMonth' => '12',
    'expirationYear' => '2028',
    'cvv' => '123',
];

$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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
              "number": "4111111111111111",
              "holderName": "JOAO SILVA",
              "expirationMonth": "12",
              "expirationYear": "2028",
              "cvv": "123"
            }
            """;

        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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "number": "4111111111111111",
  "holderName": "JOAO SILVA",
  "expirationMonth": "12",
  "expirationYear": "2028",
  "cvv": "123"
}
""";

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": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
	  "number": "4111111111111111",
	  "holderName": "JOAO SILVA",
	  "expirationMonth": "12",
	  "expirationYear": "2028",
	  "cvv": "123"
	}`)

	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" => "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "number" => "4111111111111111",
  "holderName" => "JOAO SILVA",
  "expirationMonth" => "12",
  "expirationYear" => "2028",
  "cvv" => "123",
})

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",
  "token": "tok_abc123xyz",
  "maskedNumber": "****1111",
  "status": "active",
  "pendingActivation": false
}
```

```json 400 Cliente sem CPF/CNPJ theme={null}
{
  "statusCode": 400,
  "message": "Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador"
}
```

```json 400 theme={null}
{
  "statusCode": 400,
  "message": "Failed to register card"
}
```

## Veja também

> [card] [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
>
> Como funciona o armazenamento e o ciclo de vida do cartão.

> [card] [Cobrança com cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
>
> Recompra com `cardTokenId` e CVV.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Fluxo cards-first: cliente, cartão e assinatura.

> [card] [Guia de clientes](https://docs.fastpaybrasil.com/guias/clientes.md)
>
> Requisitos do cliente para ter cartão salvo.


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