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

# Guardar cartão no Cofre

> Guarda um cartão de crédito no Cofre para o customer informado. Requer o produto `tokenization` habilitado. Se já existir um token ativo para o mesmo customer e cartão, retorna o `cardTokenId` existente (HTTP 201).



## OpenAPI

````yaml POST /v1/vault/tokenize
openapi: 3.0.0
info:
  title: UvviPay Public API
  description: >-
    Endpoints públicos da plataforma UvviPay para integração de subcontas
    (submerchants).
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.uvvipay.com.br
    description: Produção
  - url: https://api-staging.uvvipay.com.br
    description: Staging
security:
  - client-id: []
    client-secret: []
tags: []
paths:
  /v1/vault/tokenize:
    post:
      tags:
        - Cofre
      summary: Guardar cartão no Cofre
      description: >-
        Guarda um cartão de crédito no Cofre para o customer informado. Requer o
        produto `tokenization` habilitado. Se já existir um token ativo para o
        mesmo customer e cartão, retorna o `cardTokenId` existente (HTTP 201).
      operationId: tokenizeCard
      parameters:
        - name: client-id
          in: header
          description: ID público da credencial do merchant
          required: true
          schema:
            type: string
        - name: client-secret
          in: header
          description: Secret da credencial do merchant
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenizeCardDto'
      responses:
        '201':
          description: Cartão guardado no Cofre com sucesso
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenizeCardResponseDto'
        '400':
          description: Dados inválidos
        '401':
          description: Credenciais inválidas ou ausentes
        '403':
          description: Produto `tokenization` não habilitado para o merchant
        '422':
          description: >-
            Provedor não provisionou o cartão no Cofre (erro definitivo para o
            payload enviado)
        '429':
          description: Limite de 30 req/min por IP excedido
        '500':
          description: Falha interna transitória; retry com backoff é recomendado
components:
  schemas:
    TokenizeCardDto:
      type: object
      properties:
        card:
          $ref: '#/components/schemas/TokenizeCardCardDto'
        customer:
          $ref: '#/components/schemas/TokenizeCardCustomerDto'
      required:
        - card
        - customer
    TokenizeCardResponseDto:
      type: object
      properties:
        cardTokenId:
          type: string
          format: uuid
          description: Identificador do token de cartão na UvviPay
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - cardTokenId
    TokenizeCardCardDto:
      type: object
      properties:
        number:
          type: string
          minLength: 13
          maxLength: 19
          description: Número do cartão (apenas dígitos)
          example: '************1111'
        holderName:
          type: string
          example: JOAO DA SILVA
        securityCode:
          type: string
          minLength: 3
          maxLength: 4
          description: CVV/CVC (3 ou 4 dígitos)
          example: '***'
        expirationMonth:
          type: integer
          minimum: 1
          maximum: 12
          example: 12
        expirationYear:
          type: integer
          example: 2029
      required:
        - number
        - holderName
        - securityCode
        - expirationMonth
        - expirationYear
    TokenizeCardCustomerDto:
      type: object
      properties:
        name:
          type: string
          example: João da Silva
        email:
          type: string
          format: email
          example: joao@exemplo.com
        phone:
          type: string
          example: '11987654321'
        documentNumber:
          type: string
          minLength: 11
          maxLength: 14
          description: CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
          example: '12345678901'
        documentType:
          type: string
          enum:
            - cpf
            - cnpj
          example: cpf
        externalCustomerId:
          type: string
          minLength: 20
          maxLength: 255
          description: Identificador único do customer no seu sistema (20 a 255 caracteres)
          example: customer-ext-00000000001
      required:
        - name
        - email
        - documentNumber
        - documentType
        - externalCustomerId
  securitySchemes:
    client-id:
      type: apiKey
      in: header
      name: client-id
    client-secret:
      type: apiKey
      in: header
      name: client-secret

````