Cofre

O Cofre permite enviar os dados sensíveis do cartão uma vez e receber um cardTokenId para reutilização segura no seu backend. O endpoint exige o produto tokenization habilitado na conta do merchant.

Pré-requisitos

Produto habilitado

O produto Tokenization precisa estar habilitado para o seu merchant. A ativação é feita pela equipe UvviPay; solicite ao seu contato comercial.

Credenciais de API

Use client-id e client-secret no backend. Nunca exponha o client-secret no front-end. Veja Autenticação.

Como funciona

Você envia card + customer para POST /v1/vault/tokenize.
A UvviPay resolve o customer pelo externalCustomerId e, se não encontrar, pelo email na sua conta. Sem correspondência, a API cria o customer. Veja Identidade do customer.
Se já existir um token ativo para o mesmo customer e cartão, a API devolve o cardTokenId existente com HTTP 201.
Caso contrário, o cartão é guardado no Cofre e a API retorna o novo cardTokenId com HTTP 201.

Guarde o cardTokenId no seu sistema. Ele identifica o cartão no Cofre e pode ser usado para cobrar via POST /v1/payments sem reenviar PAN/CVV.

Não envie dados de cartão a partir do browser. Chame o endpoint apenas do seu backend e trate o PAN/CVV como dado sensível (PCI).

Identidade do customer

A API resolve o customer nesta ordem:

Busca o externalCustomerId na sua conta.
Se não encontrar, busca o email na sua conta.
Se não encontrar, cria o customer com os dados do request.

Email e externalCustomerId precisam apontar para o mesmo customer. Se houver conflito, a API responde HTTP 422 e não guarda o cartão:

Conflito	Mensagem
`externalCustomerId` já vinculado a outro email	`Customer external id is already linked to a different email.`
Email já vinculado a outro `externalCustomerId`	`Customer email already linked to a different external customer id.`

NOTA: o segundo conflito também ocorre quando o email pertence a um customer sem externalCustomerId — por exemplo, um customer criado pelo checkout público. A API não vincula o externalCustomerId do request a esse customer. Para evitar os conflitos, envie sempre o mesmo par email + externalCustomerId para a mesma pessoa.

Chamadas concorrentes

Para o mesmo customer e cartão:

Se já houver token ativo, a API reutiliza o cardTokenId sem criar outro.
Chamadas concorrentes sem token ativo podem ambas acionar o provedor; a persistência é serializada. Ao final, as respostas bem-sucedidas convergem para o mesmo cardTokenId ativo (HTTP 201).

Não há header de idempotência neste endpoint. Reutilize o cardTokenId salvo no seu sistema sempre que possível.

Exemplo

curl -X POST https://api.uvvipay.com.br/v1/vault/tokenize \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -d '{
    "card": {
      "number": "************1111",
      "holderName": "JOAO DA SILVA",
      "securityCode": "***",
      "expirationMonth": 12,
      "expirationYear": 2029
    },
    "customer": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "phone": "11987654321",
      "documentNumber": "12345678901",
      "documentType": "cpf",
      "externalCustomerId": "customer-ext-00000000001"
    }
  }'

Resposta (201)

{
  "cardTokenId": "550e8400-e29b-41d4-a716-446655440000"
}

Cobrando com o cardTokenId

Use o token no POST /v1/payments enviando card.cardTokenId no lugar dos dados abertos do cartão, sem PAN, sem CVV e sem customer:

curl -X POST https://api.uvvipay.com.br/v1/payments \
  -H "Content-Type: application/json" \
  -H "client-id: SUA_CLIENT_ID" \
  -H "client-secret: SUA_CLIENT_SECRET" \
  -H "x-idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "externalId": "pedido-123",
    "amount": 7500,
    "paymentMethod": "credit_card",
    "card": {
      "cardTokenId": "550e8400-e29b-41d4-a716-446655440000",
      "installments": 1
    },
    "ip": "192.0.2.1",
    "items": [ ... ]
  }'

Regras:

Envie ip com IPv4 ou IPv6, sem porta e sem colchetes.
A API exige ip.
Texto vazio em ip conta como ausente.
O ip não muda a cobrança para MIT.
card.cardTokenId não pode ser combinado com number/cvv/holderName/expiração; nome do portador, validade e bandeira vêm do Cofre.
customer não pode ser enviado com card.cardTokenId; a cobrança usa o customer já vinculado ao token no Cofre e a transação fica ligada a esse customer.
A reutilização do token não depende de busca por email. O vínculo do token com o customer é definido na tokenização e não muda.
A cobrança é sempre CIT (cliente presente). Não envie iniciação MIT neste endpoint.
Token de outra conta, inativo ou inexistente responde 404.
Recomendamos enviar x-idempotency-key para retry seguro.

Campos importantes

Campo	Observação
`customer.externalCustomerId`	Obrigatório, 20 a 255 caracteres. Identificador estável do customer no seu sistema
`customer.documentNumber`	Apenas dígitos; CPF (11) ou CNPJ (14)
`customer.documentType`	`cpf` ou `cnpj`
`card.number`	13 a 19 dígitos
`card.securityCode`	CVV/CVC, 3 ou 4 dígitos
`card.expirationMonth`	Inteiro de 1 a 12
`card.expirationYear`	Ano com 4 dígitos (ex.: `2029`)

Rate limit

POST /v1/vault/tokenize tem limite de 30 requisições por minuto por IP. Se exceder, a API responde HTTP 429 Too Many Requests. Não há headers Retry-After nem X-RateLimit-* neste endpoint.

Retries

Situação	Recomendação
`429`	Backoff exponencial com jitter e tente de novo
`5xx`	Retry com backoff exponencial e jitter; limite o número de tentativas
`400`, `401`, `403`, `422`	Não repita o mesmo payload sem corrigir a causa

Dados sensíveis

Nunca registre em logs, métricas ou traces:

PAN completo (card.number)
CVV/CVC (card.securityCode)
client-secret
network token completo ou criptogramas

Erros

Status	Tipo	Quando acontece
`400`	Definitivo	Payload inválido (validação de campos)
`401`	Definitivo	`client-id` / `client-secret` ausentes ou inválidos
`403`	Definitivo	Produto `tokenization` não habilitado
`422`	Definitivo	Conflito de identidade do customer ou provedor não provisionou o cartão no Cofre
`429`	Transitório	Rate limit excedido
`5xx`	Transitório	Falha interna ou indisponibilidade temporária

Começando

Funcionalidades

Pré-requisitos

Como funciona

Identidade do customer

Chamadas concorrentes

Exemplo

Resposta (201)

Cobrando com o cardTokenId

Campos importantes

Rate limit

Retries

Dados sensíveis

Erros

Próximos passos

Guardar cartão no Cofre

Cobrar com o token

Começando

Funcionalidades

​Pré-requisitos

​Como funciona

​Identidade do customer

​Chamadas concorrentes

​Exemplo

​Resposta (201)

​Cobrando com o cardTokenId

​Campos importantes

​Rate limit

​Retries

​Dados sensíveis

​Erros

​Próximos passos

Guardar cartão no Cofre

Cobrar com o token

Pré-requisitos

Como funciona

Identidade do customer

Chamadas concorrentes

Exemplo

Resposta (201)

Cobrando com o cardTokenId

Campos importantes

Rate limit

Retries

Dados sensíveis

Erros

Próximos passos