Criar token de cartão

Use este endpoint para tokenizar um cartão de crédito, associando-o a um cliente já existente na sua empresa. O número completo do cartão (PAN) fica armazenado exclusivamente na adquirente; a Bestfy guarda apenas uma referência opaca, junto com informações não sensíveis como BIN, últimos quatro dígitos, bandeira e nome do titular.

Após a tokenização, utilize o cardId retornado para cobrar o cartão em POST /payment via objeto creditCardToken, sem precisar enviar os dados sensíveis novamente.

Pré-requisito

Para tokenizar um cartão, você precisa de um customerId, o identificador do comprador dentro da sua empresa. Esse valor é retornado na resposta de qualquer transação criada em POST /payment (Pix, boleto ou cartão de crédito).

Campos do request body

customerId (obrigatório): Id do cliente, obtido na resposta de POST /payment.

creditCard (obrigatório): Objeto com os dados do cartão, na mesma forma do campo creditCard de POST /payment:

number: Número do cartão (16 dígitos, sem espaços).

verificationValue: Código de verificação CVV (3 dígitos).

firstName: Primeiro nome do titular.

lastName: Sobrenome do titular.

month: Mês de vencimento (2 dígitos, ex: "09").

year: Ano de vencimento (4 dígitos, ex: "2028").

Resposta de sucesso — 201 Created

{
  "cardId": "01912ce8-b6ee-79b7-bd6a-297f1fef14f7"
}

Guarde o cardId, ele é a referência ao cartão tokenizado e será usado em todas as cobranças futuras com creditCardToken em POST /payment.

Como cobrar com o cartão tokenizado

Após obter o cardId, envie uma cobrança em POST /payment com o objeto creditCardToken no lugar de creditCard e customer:

{
  "paymentMethod": "CREDIT_CARD",
  "items": [{ "..." }],
  "creditCardToken": {
    "customerId": "01912ce8-b6ee-79b7-bd6a-297f1fef14f6",
    "cardId": "01912ce8-b6ee-79b7-bd6a-297f1fef14f7",
    "numberOfInstallments": 1
  }
}

Quando creditCardToken está presente, os campos customer e creditCard não devem ser enviados. O comprador e o endereço são obtidos automaticamente do cliente dono do cartão.

Opcionalmente, envie um address junto com creditCardToken. O endereço será usado nesta cobrança e atualizará o cadastro do cliente.

O campo numberOfInstallments é opcional (1 a 12, padrão: 1).

Observações

Cobranças com cartão tokenizado não passam por autenticação 3DS. O campo tdsServerTransId não se aplica.

Um cardId pode ser reutilizado em múltiplas cobranças sem restrição de quantidade.

Erros comuns

Código	Motivo
400	`CUSTOMER_CREDIT_CARD_TOKEN_E001` — a adquirente de cartão da empresa não suporta tokenização
400	`FINANCIAL_TRANSACTION_E038` — `creditCard` e `creditCardToken` enviados juntos em `POST /payment`
400	`FINANCIAL_TRANSACTION_E039` — `customer` e `creditCardToken` enviados juntos em `POST /payment`
404	`CUSTOMER_E001` — `customerId` não pertence à empresa da API key
404	`CUSTOMER_CREDIT_CARD_TOKEN_E003` — `cardId` não pertence ao `customerId` informado
500	Erro ao criar o cartão na adquirente — verifique os dados do cartão e tente novamente

Criar token de cartão

Pré-requisito

Campos do request body

Resposta de sucesso — 201 Created

Como cobrar com o cartão tokenizado

Observações

Erros comuns

Request

Responses

Criar token de cartão

Pré-requisito#

Campos do request body#

Resposta de sucesso — 201 Created#

Como cobrar com o cartão tokenizado#

Observações#

Erros comuns#

Request

Responses

Pré-requisito

Campos do request body

Resposta de sucesso — 201 Created

Como cobrar com o cartão tokenizado

Observações

Erros comuns