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

# Tokenize card

> Securely tokenize a credit card

Tokenizes a credit card using the merchant's active acquirer, without storing PAN/CVV in Safefy's database. The returned token can be used in `POST /v1/transactions` via the `cardToken` field.

## Request

`POST /v1/card-tokenize`

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

### Parameters

| Field                 | Type   | Required | Description                 |
| --------------------- | ------ | -------- | --------------------------- |
| `cardNumber`          | string | yes      | Card number (13-19 digits)  |
| `cardHolderName`      | string | yes      | Name printed on the card    |
| `cardExpirationMonth` | int    | yes      | Expiration month (1-12)     |
| `cardExpirationYear`  | int    | yes      | Expiration year (e.g. 2028) |
| `cardCvv`             | string | yes      | Security code (3-4 digits)  |

## Responses

### 200 — Success

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

| Field       | Type   | Description                                       |
| ----------- | ------ | ------------------------------------------------- |
| `cardToken` | string | Card token (prefix `ct_`). Time-limited validity. |
| `last4`     | string | Last 4 digits of the card                         |
| `brand`     | string | Card brand (e.g. `visa`, `mastercard`)            |

### 400 — Invalid data

```json theme={null}
{
  "error": {
    "message": "Invalid card data.",
    "code": "invalid_card_data"
  }
}
```

### 401 — Invalid JWT token

```json theme={null}
{
  "error": {
    "message": "Invalid token.",
    "code": "invalid_token"
  }
}
```

### 422 — Acquirer doesn't support tokenization

```json theme={null}
{
  "error": {
    "message": "Configured acquirer does not natively support tokenization.",
    "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

````