> ## 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 para o cliente e inicia sua tokenização. A resposta retorna imediatamente com `tokenization_status: "pending"`; o resultado da tokenização é entregue de forma assíncrona por webhook (`card.token_created` em caso de sucesso ou `card.token_failed` caso o cartão não possa ser tokenizado). Um evento `card.created` também é emitido ao salvar o cartão.

O número completo (PAN) e o CVV nunca são retornados — apenas os seis primeiros e os quatro últimos dígitos. Aceita o header opcional `Idempotency-Key` para evitar cadastros duplicados em retentativas. Requer o header `account` com o código da conta.


<Note>
  Requer o header `account` com o código da conta. O cartão é salvo para o cliente informado no `clientCode` e a tokenização é iniciada automaticamente.
</Note>

<Tip>
  A resposta retorna imediatamente com `tokenization_status: "pending"`. O resultado da tokenização é entregue de forma assíncrona por webhook — você **não** precisa fazer polling. Envie o header opcional `Idempotency-Key` para evitar cadastros duplicados em caso de retentativa.
</Tip>

## Ciclo de tokenização

Acompanhe a disponibilidade do cartão pelos eventos de webhook:

| Evento               | Quando é disparado                                           |
| -------------------- | ------------------------------------------------------------ |
| `card.created`       | Assim que o cartão é salvo.                                  |
| `card.token_created` | Quando o cartão foi tokenizado e está pronto para cobranças. |
| `card.token_failed`  | Quando não foi possível tokenizar o cartão.                  |

Enquanto o `tokenization_status` estiver `pending`, o cartão ainda está sendo preparado. Aguarde o `card.token_created` antes de usá-lo em uma cobrança.

## Usando o cartão salvo

O campo `card_token` (presente na resposta e no evento `card.token_created`) é o identificador que você envia em `payment.card.card_token` ao criar uma cobrança ou pedido com o cartão salvo.

<Warning>
  **Billing Address** — o billing address do cartão **não** é tokenizado. Ao criar um pedido/cobrança com `card_token`, você **também precisa informar o billing address** (`client.address`) na requisição.
</Warning>

<Warning>
  O número completo (PAN) e o código de segurança (CVV) nunca são retornados. A resposta expõe apenas `first_six_digits` e `last_four_digits`.
</Warning>


## OpenAPI

````yaml POST /v1/clients/{clientCode}/cards/tokens
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)
paths:
  /v1/clients/{clientCode}/cards/tokens:
    post:
      tags:
        - Cartões
      summary: Salvar cartão
      description: >
        Salva um cartão para o cliente e inicia sua tokenização. A resposta
        retorna imediatamente com `tokenization_status: "pending"`; o resultado
        da tokenização é entregue de forma assíncrona por webhook
        (`card.token_created` em caso de sucesso ou `card.token_failed` caso o
        cartão não possa ser tokenizado). Um evento `card.created` também é
        emitido ao salvar o cartão.


        O número completo (PAN) e o CVV nunca são retornados — apenas os seis
        primeiros e os quatro últimos dígitos. Aceita o header opcional
        `Idempotency-Key` para evitar cadastros duplicados em retentativas.
        Requer o header `account` com o código da conta.
      operationId: createClientCardToken
      parameters:
        - $ref: '#/components/parameters/AccountHeader'
        - $ref: '#/components/parameters/ClientCode'
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Chave de idempotência para evitar cadastros duplicados (máx. 128
            caracteres)
          schema:
            type: string
            example: a1b2c3d4-idem-key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCartaoRequest'
            example:
              name: Tony Stark
              number: '5425011234567793'
              month: 1
              year: 2030
              security_code: '123'
              type: credit
              flag: mastercard
      responses:
        '202':
          description: Cartão recebido; tokenização iniciada
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartaoResponse'
              example:
                mensagem: >-
                  Cartão recebido. A tokenização foi iniciada; o resultado será
                  enviado por webhook.
                erro: false
                mensagenserro: []
                codigoretorno: 202
                id: 00000000-0000-0000-0000-000000000000
                data:
                  id: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
                  card_token: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
                  first_six_digits: '542501'
                  last_four_digits: '7793'
                  brand: mastercard
                  holder_name: Tony Stark
                  exp_month: 1
                  exp_year: 2030
                  type: credit
                  status: active
                  tokenization_status: pending
                  created_at: '2026-05-27T10:00:00-03:00'
                  updated_at: '2026-05-27T10:00:00-03:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  parameters:
    AccountHeader:
      name: account
      in: header
      required: true
      description: Código da conta à qual a operação se aplica
      schema:
        type: string
        example: acc_abc123xyz
    ClientCode:
      name: clientCode
      in: path
      required: true
      description: Código único do cliente dono do cartão
      schema:
        type: string
        example: cli_abc123
  schemas:
    CreateCartaoRequest:
      type: object
      required:
        - name
        - number
        - month
        - year
        - security_code
      properties:
        name:
          type: string
          maxLength: 255
          description: Nome do portador impresso no cartão
          example: Tony Stark
        number:
          type: string
          description: Número do cartão (13–19 dígitos, validado por Luhn)
          example: '5425011234567793'
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: Mês de validade
          example: 1
        year:
          type: integer
          description: Ano de validade (2 ou 4 dígitos; deve estar no futuro)
          example: 2030
        security_code:
          type: string
          description: Código de segurança (CVV, 3 ou 4 dígitos)
          example: '123'
        type:
          type: string
          enum:
            - credit
            - debit
          default: credit
          description: Tipo do cartão
          example: credit
        flag:
          type: string
          enum:
            - visa
            - mastercard
            - elo
            - amex
          description: Bandeira do cartão (opcional)
          example: mastercard
    CartaoResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: >-
            Cartão recebido. A tokenização foi iniciada; o resultado será
            enviado por webhook.
        erro:
          type: boolean
          example: false
        mensagenserro:
          type: array
          items:
            type: string
          example: []
        codigoretorno:
          type: integer
          example: 201
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        data:
          $ref: '#/components/schemas/CartaoData'
    CartaoData:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID identificador do cartão
          example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
        card_token:
          type: string
          description: >
            Identificador do cartão salvo, retornado ao salvar o cartão e no
            evento `card.token_created`. É o valor enviado em
            `payment.card.card_token` ao cobrar com o cartão salvo.
          example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
        first_six_digits:
          type: string
          nullable: true
          description: Seis primeiros dígitos do cartão (BIN)
          example: '542501'
        last_four_digits:
          type: string
          nullable: true
          description: Quatro últimos dígitos do cartão
          example: '7793'
        brand:
          type: string
          description: Bandeira do cartão
          enum:
            - visa
            - mastercard
            - elo
            - amex
            - undefined
          example: mastercard
        holder_name:
          type: string
          description: Nome do portador impresso no cartão
          example: Tony Stark
        exp_month:
          type: integer
          nullable: true
          description: Mês de validade (1–12)
          example: 1
        exp_year:
          type: integer
          nullable: true
          description: Ano de validade (YYYY)
          example: 2030
        type:
          type: string
          description: Tipo do cartão
          enum:
            - credit
            - debit
          example: credit
        status:
          type: string
          description: Situação do cartão
          enum:
            - active
            - deleted
          example: active
        tokenization_status:
          type: string
          description: >
            Situação da tokenização do cartão. `pending` enquanto está sendo
            processado, `tokenized` quando o cartão está pronto para cobranças e
            `failed` quando não foi possível tokenizá-lo. As transições
            `tokenized`/`failed` também são notificadas por webhook
            (`card.token_created` / `card.token_failed`).
          enum:
            - pending
            - tokenized
            - failed
          example: pending
        created_at:
          type: string
          format: date-time
          description: Data de criação (ISO 8601)
          example: '2026-05-27T10:00:00-03:00'
        updated_at:
          type: string
          format: date-time
          description: Data da última atualização (ISO 8601)
          example: '2026-05-27T10:00:00-03:00'
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Data de exclusão (ISO 8601) — presente apenas em cartão excluído
          example: '2026-04-04T12:43:30-03:00'
    ErrorResponse:
      type: object
      properties:
        mensagem:
          type: string
          example: Um erro inesperado acabou de acontecer.
        erro:
          type: boolean
          example: true
        mensagenserro:
          type: array
          items:
            type: string
          example:
            - Detalhe do erro ocorrido.
        codigoretorno:
          type: integer
          example: 400
        id:
          type: string
          example: 00000000-0000-0000-0000-000000000000
        data:
          type: array
          example: []
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            client.email:
              - O campo client.email é obrigatório.
            payment.type:
              - O campo payment.type é obrigatório.
  responses:
    Unauthorized:
      description: Não autorizado — token inválido ou ausente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Unauthenticated.
            erro: true
            mensagenserro: []
            codigoretorno: 401
            id: 00000000-0000-0000-0000-000000000000
            data: []
    NotFound:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: The charge code does not match any charge
            erro: true
            mensagenserro: []
            codigoretorno: 404
            id: 00000000-0000-0000-0000-000000000000
            data: []
    ValidationError:
      description: Erro de validação dos dados enviados
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorResponse'
          example:
            message: The given data was invalid.
            errors:
              client.email:
                - O campo client.email é obrigatório.
    ServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            mensagem: Um erro aconteceu.
            erro: true
            mensagenserro:
              - Erro interno. Tente novamente mais tarde.
            codigoretorno: 500
            id: 00000000-0000-0000-0000-000000000000
            data: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
        Bearer <token>`.

````