Vincular Meio de Pagamento
POST/v2/payment-customers/{customerId}/payment-methods
Tokeniza o cartão, armazena com segurança no cofre (AES-256) e associa o registro ao cliente.
Pré-requisitos para Implementação
- Cliente Existente: Antes de vincular um cartão, cadastre o cliente pagador em Criar Cliente para obter o
customerIdexigido no caminho da URL.
Cabeçalhos (Headers)
| Cabeçalho | Valor | Obrigatório | Descrição |
|---|---|---|---|
Authorization | Bearer <token> | Sim | Token JWT Bearer autenticado |
Content-Type | application/json | Sim | Tipo de mídia |
Idempotency-Key | <guid_ou_string> | Sim | Chave de idempotência |
Parâmetros
Exemplo de requisição
{
"cardNumber": "4111111111111111",
"expiryDate": "1228",
"isDefault": true
}Resposta (201 Created)
Exemplo de resposta
{
"id": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"paymentCustomerId": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"cardBrand": "VISA",
"cardBin": "41****",
"cardSuffix": "1111",
"cardExpirationDate": "1228",
"isDefault": true,
"status": "ACTIVE",
"createdOn": "2026-09-09T10:10:00Z"
}Próximos Passos
Após vincular o cartão, utilize o id retornado (PaymentCustomerPaymentMethodId) para:
- Criar Assinatura: Informe este identificador em
PaymentCustomerPaymentMethodIdao Criar Assinatura. - Definir como Padrão: Se não enviou
isDefault: true, defina-o como prioritário em Definir Cartão Padrão. - Substituir em Assinatura Existente: Atualize o cartão de cobrança de uma assinatura ativa em Alterar Meio de Pagamento.
Erros
As respostas de erro conhecidas estão abaixo. Os retornos observados em homologação estão identificados separadamente dos exemplos documentados; as respostas podem variar conforme o ambiente e a configuração.
Ver validações observadas em homologação
Requisição com corpo JSON vazio ou identificador sintético. O retorno abaixo mostra a validação realizada em homologação.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Idempotency-Key": [
"The key field is required."
]
},
"traceId": "00-f5af96ba77b5943732b0e01e482087bd-1b44f9bd2ec465cd-00"
}Observado em homologação
Requisição com o header Idempotency-Key e corpo JSON vazio; os identificadores na rota são sintéticos.
[
{
"tag": "CardNumber",
"description": "O número do cartão é obrigatório."
},
{
"tag": "ExpiryDate",
"description": "A data de expiração do cartão é obrigatória."
}
]Campos da resposta de erro
A tabela reúne os campos presentes nos exemplos acima. Uma resposta HTTP sem corpo não inclui esses campos.
