> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Salvar cartão
> Salva um cartão do comprador e inicia a tokenização nas adquirentes da conta. A resposta é sempre 202: use o `id` devolvido como `card.token` em pedidos, assinaturas e faturas. O número completo e o código de segurança nunca são devolvidos.
**A tokenização é assíncrona.** `tokenization_status` vem `pending` quando a tokenização foi iniciada, ou `failed` na hora quando nenhuma adquirente da conta consegue tokenizar. Um cartão com `failed` ainda pode ser usado em compras. O resultado final chega pelos webhooks `card.token_created` e `card.token_failed`, que existem só no formato v1. Limite de 10 cartões por minuto por conta.
A resposta é sempre `202 Accepted`: a tokenização roda em segundo plano. Acompanhe o campo `tokenization_status` (`pending`, `tokenized` ou `failed`) com [`GET /v2/cards/{id}`](/pages/v2/cartoes/get).
Guarde o `id` retornado e use-o como `card.token` em pedidos, assinaturas e faturas. Um cartão com tokenização `pending` ou `failed` continua podendo ser usado em compras.
`customer.document` é obrigatório (`cpf`, `cnpj` ou `passport`), e `customer.phone.ddi` e `customer.phone.ddd` são números inteiros. Um cartão vencido retorna `422` com `param` `card.exp_year`.
Limite de **10 cartões por minuto por conta** (`429` `card_tokenization_rate_limited`). Cartão, e-mail ou documento bloqueado retorna `403` (`customer_blocked`).
## OpenAPI
````yaml POST /v2/cards
openapi: 3.1.0
info:
title: 4Selet Pay API
description: >
API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
version: 1.0.0
contact:
name: 4Selet Pay
email: suporte@4selet.com.br
servers:
- url: https://sandbox.4seletpay.com.br/api
description: Servidor de Sandbox
security:
- bearerAuth: []
tags:
- name: Autenticação
description: Rotas de autenticação e criação de usuários
- name: Cobranças
description: Criação, consulta, cancelamento e reembolso de cobranças
- name: Pedidos
description: Consulta de pedidos e gerenciamento de confirmações desafiadas
- name: Cartões
description: Cadastro e gerenciamento dos cartões salvos de um cliente
- name: Assinaturas
description: Criação e gerenciamento de assinaturas recorrentes
- name: Faturas
description: Gerenciamento de faturas e pagamento de faturas em atraso
- name: Clientes Bloqueados
description: Gerenciamento de lista negra de clientes
- name: Contas
description: Criação e gerenciamento de contas na plataforma
- name: Aplicativo
description: Endpoints para dashboard e uso via aplicativo mobile
- name: Notificações Push
description: Envio e gerenciamento de notificações push
- name: Utilitários
description: Endpoints utilitários como listagem de fusos horários
- name: Gestão
description: Relatórios gerenciais (acesso restrito a Super Admins)
- name: Webhooks
description: Endpoints para receber notificações de gateways de pagamento
- name: Endpoints de Webhook
description: >-
Gerenciamento de endpoints de webhook para receber notificações de eventos
da plataforma
- name: Links de Pagamento
description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
- name: Análise de Fraude
description: >-
API de Risco — consulta o risco de fraude de uma transação (autenticada
por chave de API)
- name: Pedidos (v2)
description: >-
API v2 — pedidos com um ou mais meios de pagamento, captura, cancelamento
e verificação por código
- name: Cobranças (v2)
description: API v2 — consulta e estorno de cobranças
- name: Cartões (v2)
description: API v2 — cadastro e consulta de cartões salvos
- name: Assinaturas (v2)
description: API v2 — criação e gerenciamento de assinaturas recorrentes
- name: Faturas (v2)
description: >-
API v2 — consulta, pagamento e verificação por código das faturas de
assinaturas
paths:
/v2/cards:
post:
tags:
- Cartões (v2)
summary: Salvar cartão
description: >
Salva um cartão do comprador e inicia a tokenização nas adquirentes da
conta. A resposta é sempre 202: use o `id` devolvido como `card.token`
em pedidos, assinaturas e faturas. O número completo e o código de
segurança nunca são devolvidos.
**A tokenização é assíncrona.** `tokenization_status` vem `pending`
quando a tokenização foi iniciada, ou `failed` na hora quando nenhuma
adquirente da conta consegue tokenizar. Um cartão com `failed` ainda
pode ser usado em compras. O resultado final chega pelos webhooks
`card.token_created` e `card.token_failed`, que existem só no formato
v1. Limite de 10 cartões por minuto por conta.
operationId: v2CreateCard
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2CreateCardRequest'
example:
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: 55
ddd: 11
number: '999999999'
document:
type: cpf
number: '12345678909'
card:
number: '4111111111111111'
holder_name: João Silva
exp_month: 12
exp_year: 2030
cvc: '123'
responses:
'202':
description: Cartão salvo, tokenização iniciada
content:
application/json:
schema:
$ref: '#/components/schemas/V2Card'
example:
id: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
object: card
brand: visa
first_six: '411111'
last_four: '1111'
holder_name: João Silva
exp_month: 12
exp_year: 2030
type: credit
tokenization_status: pending
customer:
name: João Silva
email: joao@exemplo.com.br
created_at: '2026-09-14T12:00:00-03:00'
'400':
$ref: '#/components/responses/V2IdempotencyInvalid'
'401':
$ref: '#/components/responses/V2Unauthorized'
'403':
$ref: '#/components/responses/V2CardBlocked'
'409':
$ref: '#/components/responses/V2IdempotencyInUse'
'422':
description: Dados inválidos ou cartão vencido
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
validation_error:
summary: Cartão vencido
value:
error:
type: invalid_request_error
code: validation_error
message: The card has expired.
param: card.exp_year
idempotency_key_conflict:
summary: Idempotency-Key usada com outro corpo
value:
error:
type: idempotency_error
code: idempotency_key_conflict
message: >-
The Idempotency-Key has already been used with a
different request body.
'429':
$ref: '#/components/responses/V2CardRateLimited'
'500':
$ref: '#/components/responses/V2ServerError'
security:
- secretKeyAuth: []
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >
Chave de idempotência opcional e recomendada. Tem até 128 caracteres e
vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a
resposta original (mesmo status e mesmo corpo), sem processar de novo.
Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode
ser reutilizada. A mesma chave com um corpo diferente retorna 422
(`idempotency_key_conflict`), uma requisição original ainda em andamento
retorna 409 (`idempotency_key_in_use`) e uma chave com mais de 128
caracteres retorna 400 (`idempotency_key_invalid`).
schema:
type: string
maxLength: 128
example: pedido-1024-tentativa-1
schemas:
V2CreateCardRequest:
type: object
required:
- customer
- card
properties:
customer:
$ref: '#/components/schemas/V2CustomerWithDocument'
card:
type: object
required:
- number
- holder_name
- exp_month
- exp_year
- cvc
properties:
number:
type: string
description: Número do cartão (validado pelo dígito verificador)
example: '4111111111111111'
holder_name:
type: string
maxLength: 255
example: João Silva
exp_month:
type: integer
minimum: 1
maximum: 12
example: 12
exp_year:
type: integer
description: >-
Ano de validade, com 2 ou 4 dígitos. Um cartão vencido retorna
422 com `param` `card.exp_year`
example: 2030
cvc:
type: string
pattern: ^\d{3,4}$
example: '123'
type:
type: string
enum:
- credit
- debit
V2Card:
type: object
description: >-
Cartão salvo. O número completo e o código de segurança nunca são
devolvidos
properties:
id:
type: string
format: uuid
description: Use este valor como `card.token` em pedidos, assinaturas e faturas
example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
object:
type: string
enum:
- card
brand:
type: string
example: visa
first_six:
type: string
example: '411111'
last_four:
type: string
example: '1111'
holder_name:
type: string
example: João Silva
exp_month:
type: integer
example: 12
exp_year:
type: integer
example: 2030
type:
type: string
enum:
- credit
- debit
nullable: true
tokenization_status:
type: string
enum:
- pending
- tokenized
- failed
description: >
`pending`: tokenização em andamento. `tokenized`: concluída.
`failed`: nenhuma adquirente conseguiu tokenizar. Um cartão com
`failed` ainda pode ser usado em compras.
customer:
type: object
properties:
name:
type: string
example: João Silva
email:
type: string
example: joao@exemplo.com.br
created_at:
type: string
example: '2026-09-14T12:00:00-03:00'
V2Error:
type: object
description: Envelope de erro da API v2
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request_error
- idempotency_error
- authentication_error
- api_error
description: Categoria do erro
code:
type: string
description: Código estável do erro. Use este campo na sua lógica
example: validation_error
message:
type: string
description: Texto técnico, para log e depuração. Não exiba ao pagador
example: The payments field is required.
param:
type: string
description: >-
Campo que causou o erro, em notação de ponto. Presente só quando
se aplica
example: payments
customer_message:
type: string
description: Texto para exibir ao pagador. Presente só quando se aplica
V2CustomerWithDocument:
type: object
description: >
Dados do comprador, com documento obrigatório. A API v2 não tem recurso
de cliente: envie o comprador em cada requisição.
required:
- name
- email
- phone
- document
properties:
name:
type: string
maxLength: 255
example: João Silva
email:
type: string
format: email
example: joao@exemplo.com.br
phone:
type: object
required:
- ddi
- ddd
- number
properties:
ddi:
type: integer
description: Código do país
example: 55
ddd:
type: integer
description: Código de área
example: 11
number:
type: string
maxLength: 20
example: '999999999'
document:
type: object
required:
- type
- number
properties:
type:
type: string
enum:
- cpf
- cnpj
- passport
example: cpf
number:
type: string
maxLength: 50
example: '12345678909'
V2ThrottleError:
type: object
description: >
Corpo padrão, fora do envelope `error`, do limite geral de requisições e
do limite de reenvio do código de verificação
properties:
message:
type: string
example: Too Many Attempts.
responses:
V2IdempotencyInvalid:
description: O header `Idempotency-Key` tem mais de 128 caracteres
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: idempotency_key_invalid
message: Idempotency-Key must be 128 characters or fewer.
V2Unauthorized:
description: Chave de API ausente, inválida, revogada ou de outro ambiente
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: authentication_error
code: invalid_api_secret
message: Invalid API secret.
V2CardBlocked:
description: >-
Conta ou comprador bloqueado (e-mail, documento ou BIN do cartão). A
resposta traz `customer_message`
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
customer_blocked:
summary: Comprador ou BIN do cartão bloqueado
value:
error:
type: invalid_request_error
code: customer_blocked
message: Este comprador está bloqueado para novos pedidos.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente
mais tarde.
account_requests_blocked:
summary: Conta bloqueada
value:
error:
type: invalid_request_error
code: account_requests_blocked
message: As requisições desta conta estão bloqueadas.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente
mais tarde.
V2IdempotencyInUse:
description: >-
Uma requisição com a mesma `Idempotency-Key` ainda está em andamento.
Tente novamente em instantes
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: idempotency_error
code: idempotency_key_in_use
message: >-
A request with this Idempotency-Key is still being processed.
Retry shortly.
V2CardRateLimited:
description: >
Muitos cartões salvos pela conta em pouco tempo (10 por minuto por
conta) — resposta com o envelope `error` — ou limite geral de
requisições excedido, com o corpo padrão `{ "message": "Too Many
Attempts." }`. As duas trazem o header `Retry-After`.
headers:
Retry-After:
description: Segundos até a próxima tentativa
schema:
type: integer
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/V2Error'
- $ref: '#/components/schemas/V2ThrottleError'
examples:
card_tokenization_rate_limited:
summary: Muitos cartões salvos pela conta
value:
error:
type: invalid_request_error
code: card_tokenization_rate_limited
message: >-
Muitos cartões foram salvos para esta conta em pouco tempo.
Tente novamente mais tarde.
too_many_attempts:
summary: Limite geral de requisições
value:
message: Too Many Attempts.
V2ServerError:
description: Erro inesperado ao processar a requisição
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: api_error
code: internal_error
message: Ocorreu um erro inesperado ao processar a requisição.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
Bearer `.
secretKeyAuth:
type: http
scheme: bearer
description: >
Chave de API (secret key) da conta, no formato `sk_live_...` (produção)
ou `sk_test_...` (Dev mode). Envie no header `Authorization: Bearer
`. Autentica todas as rotas da API v2 e as rotas de Análise de
Fraude. A chave identifica a conta, então a API v2 não usa o header
`account`. Uma chave só é aceita no ambiente em que foi criada. Gere a
sua no dashboard em Configurações → Chaves de API.
````