> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenizar cartão

> Tokenize um cartão de crédito com segurança

Tokeniza um cartão de crédito com o adquirente ativo do estabelecimento, sem armazenar PAN/CVV no banco de dados da Safefy. O token retornado pode ser usado em `POST /v1/transactions` no campo `cardToken`.

## Requisição

`POST /v1/card-tokenize`

```json theme={null}
{
  "cardNumber": "4111111111111111",
  "cardHolderName": "João Silva",
  "cardExpirationMonth": 12,
  "cardExpirationYear": 2028,
  "cardCvv": "123"
}
```

### Parâmetros

| Campo                 | Tipo   | Obrigatório | Descrição                         |
| --------------------- | ------ | ----------- | --------------------------------- |
| `cardNumber`          | string | sim         | Número do cartão (13-19 dígitos)  |
| `cardHolderName`      | string | sim         | Nome impresso no cartão           |
| `cardExpirationMonth` | int    | sim         | Mês de expiração (1-12)           |
| `cardExpirationYear`  | int    | sim         | Ano de expiração (ex: 2028)       |
| `cardCvv`             | string | sim         | Código de segurança (3-4 dígitos) |

## Respostas

### 200 — Sucesso

```json theme={null}
{
  "data": {
    "cardToken": "ct_abc123def456",
    "last4": "1111",
    "brand": "visa"
  }
}
```

| Campo       | Tipo   | Descrição                                                   |
| ----------- | ------ | ----------------------------------------------------------- |
| `cardToken` | string | Token do cartão (prefixo `ct_`). Válido por tempo limitado. |
| `last4`     | string | Últimos 4 dígitos do cartão                                 |
| `brand`     | string | Bandeira do cartão (ex: `visa`, `mastercard`)               |

### 400 — Dados inválidos

```json theme={null}
{
  "error": {
    "message": "Dados do cartão inválidos.",
    "code": "invalid_card_data"
  }
}
```

### 401 — Token JWT inválido

```json theme={null}
{
  "error": {
    "message": "Token inválido.",
    "code": "invalid_token"
  }
}
```

### 422 — Adquirente não suporta tokenização

```json theme={null}
{
  "error": {
    "message": "Adquirente configurado não suporta tokenização nativamente.",
    "code": "tokenization_not_supported"
  }
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/card-tokenize
openapi: 3.1.1
info:
  title: Safefy - Pix Gateway
  description: >

    ## Introducao


    **Seu parceiro financeiro de confianca.**


    Nos somos a Safefy, uma plataforma especializada em solucoes de pagamento
    PIX. Com um servico personalizado e focado nas suas necessidades, estamos
    prontos para apoiar sua empresa em cada etapa do processo.


    - Conte com o **PIX** como metodo de pagamento rapido, seguro e alinhado com
    as melhores praticas de conformidade e prevencao a fraudes.

    - Gerencie suas financas de forma simples e acessivel por meio de uma
    interface completa e intuitiva.

    - Nosso time de suporte esta sempre disponivel para oferecer um atendimento
    exclusivo e eficiente.


    ## Precisa de Ajuda?


    A equipe da Safefy quer garantir que sua integracao seja um sucesso. Se
    tiver duvidas ou precisar de suporte, nao hesite em nos contatar:


    **suporte@safefypay.com.br**


    ---


    ## Valores Monetarios


    Todos os valores monetarios sao representados em **centavos** (menor unidade
    da moeda).


    | Valor Real | Valor na API |

    |------------|--------------|

    | R$ 1,00    | 100          |

    | R$ 10,50   | 1050         |

    | R$ 100,00  | 10000        |
  contact:
    name: Suporte Safefy
    email: suporte@safefypay.com.br
  version: v1
servers:
  - url: https://api-payment.safefypay.com.br
    description: API de Pagamentos Safefy
security:
  - bearerAuth: []
tags:
  - name: Autenticacao
    description: Endpoints de autenticacao OAuth2
  - name: Transacoes
    description: Gerenciamento de transacoes PIX
  - name: Clientes
    description: Gerenciamento de clientes
  - name: Saldo
    description: Consulta de saldo e volumes
  - name: Saques
    description: Solicitacao e gerenciamento de saques
  - name: Disputas
    description: Consulta de disputas e envio de defesa
paths:
  /v1/card-tokenize:
    post:
      tags:
        - Transacoes
      summary: Tokenizar cartao
      operationId: cardTokenize
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardTokenizeRequest'
      responses:
        '200':
          description: Cartao tokenizado com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardTokenizeResponse'
        '400':
          description: Dados invalidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardTokenizeResponse'
        '401':
          description: Token JWT invalido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardTokenizeResponse'
        '422':
          description: Adquirente nao suporta tokenizacao
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardTokenizeResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    CardTokenizeRequest:
      type: object
      required:
        - cardNumber
        - cardHolderName
        - cardExpirationMonth
        - cardExpirationYear
        - cardCvv
      properties:
        cardNumber:
          type: string
          description: Numero do cartao (13-19 digitos)
          example: '4111111111111111'
        cardHolderName:
          type: string
          description: Nome impresso no cartao
          example: JOAO SILVA
        cardExpirationMonth:
          type: string
          description: Mes de expiracao (1-12)
          example: '12'
        cardExpirationYear:
          type: string
          description: Ano de expiracao (4 digitos)
          example: '2028'
        cardCvv:
          type: string
          description: Codigo de seguranca (3-4 digitos)
          example: '123'
    CardTokenizeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CardTokenizeData'
        message:
          type: string
          nullable: true
        error:
          $ref: '#/components/schemas/ApiErrorResponse'
    CardTokenizeData:
      type: object
      properties:
        cardToken:
          type: string
          description: Token do cartao (prefixo ct_). Valido por tempo limitado.
          example: ct_abc123def456
        last4:
          type: string
          description: Ultimos 4 digitos do cartao
          example: '1111'
        brand:
          type: string
          description: Bandeira do cartao
          example: visa
    ApiErrorResponse:
      type: object
      nullable: true
      properties:
        message:
          type: string
          description: Mensagem de erro
          example: Token invalido ou expirado.
        code:
          type: string
          description: Codigo do erro
          example: unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT obtido via /v1/auth/token

````