1. Transações
Bestfy API
  • Sobre a Bestfy
    • Comece aqui
  • Webhooks
    • O que é um Webhook?
  • Tokenização
    • O que é Tokenização?
    • Criar token de cartão
      POST
  • Status de transação
    • Status de Pagamento na Bestfy
  • Transações
    • Anotações
      • Criar anotações
      • Listar anotações
      • Buscar anotação
      • Editar anotação
      • Remover anotação
    • Criar transações
      POST
    • Estornar transação
      POST
    • Buscar transação
      GET
    • Listar transações
      GET
    • Atualizar status de rastreio
      PATCH
    • Obter Token 3DS
      GET
    • Obter configurações do 3DS
      GET
  • Links de pagamento
    • Listar links de pagamento
      GET
    • Criar link de pagamento
      POST
    • Buscar link de pagamento
      GET
    • Atualizar link de pagamento
      PUT
    • Ativar ou desativar link de pagamento
      PATCH
    • Excluir link de pagamento
      DELETE
  • Saldo
    • Buscar saldo
      GET
  • API Key
    • Validar API Key
      GET
  1. Transações

Criar transações

POST
https://api.bestfy.io/payment
Use este endpoint para criar uma transação completa, informando metadados de pagamento, cliente, itens e endereço.
O payload utiliza valores em centavos para garantir precisão e valida a posse da companyId via x-api-key.
Atualmente, são suportados os métodos de pagamento: PIX, CREDIT_CARD e BOLETO.
Também é suportado o header x-end-user-ip, que deve conter o IP do usuário final. Esse campo é opcional, mas é extremamente recomendado que ele seja enviado para transações com cartão de crédito.
Ao clicar em "Try it", logo abaixo dos headers será exibido um seletor com o padrão "Exemplo PIX".
Para testar outros métodos de pagamento, selecione entre:
"Exemplo de CREDIT_CARD"
"Exemplo PIX"
"Exemplo BOLETO"
Isso atualizará automaticamente o body da requisição conforme o método escolhido.

Regras de uso#

Todos os campos permitidos para o processamento da transação.

Campos obrigatórios#

Os seguintes campos são sempre obrigatórios no payload:
paymentMethod
items
customer
Os demais campos são opcionais ou condicionais, conforme descrito abaixo.

Dados da Transação#

paymentMethod: Método de pagamento (PIX, CREDIT_CARD ou BOLETO).
finalAmountInCents: Valor final da transação em centavos (ex: R$ 10,00 = 1000), pode ser usado para aplicar descontos (quando enviado, sobrescreve o somatório da unidade dos itens como valor final da transação)
items: Lista de produtos ou serviços (veja detalhes abaixo).
customer: Objeto contendo os dados do pagador.
metadata: Metadados do pagamento (string).
postbackUrl: URL de callback para notificações assíncronas.
address: Objeto contendo os dados do endereço do pagador.
creditCard: Objeto contendo os dados do cartão de crédito.
creditCardToken: Objeto contendo a referência a um cartão previamente tokenizado (veja Tokenização de cartão de crédito).
Regra de obrigatoriedade do endereço (address):
Obrigatório quando houver itens com productType = COMMON.
Opcional quando todos os itens forem do tipo DIGITAL.
Regra de obrigatoriedade do cartão de crédito (creditCard ou creditCardToken):
Obrigatório quando o método de pagamento for paymentMethod = CREDIT_CARD.
Exatamente um dos dois deve ser enviado: creditCard (cartão digitado) ou creditCardToken (cartão salvo). Nunca ambos.

Detalhes do Cliente (customer)#

Todos os dados de contato são obrigatórios:
name: Nome completo.
email: E-mail.
phone: Telefone com código do país (ex: 5511999999999).
cpfOrCnpj: CPF ou CNPJ.
Envie o CPF/CNPJ e o telefone sem formatação (-, /, +).
Exceção: quando creditCardToken está presente, o campo customer não deve ser enviado — o comprador é automaticamente o dono do cartão tokenizado.

Detalhes dos Itens (items)#

Para cada item na lista, informe:
productTitle: Nome do produto.
description: Breve descrição do produto.
quantity: Quantidade comprada.
priceCents: Valor em centavos de cada unidade (ex: R$ 10,00 = 1000).
productType: Tipo do produto (DIGITAL ou COMMON).

Detalhes do Endereço (address)#

postalCode: CEP no formato brasileiro.
neighborhood: Bairro.
city: Cidade.
state: Sigla do estado (2 caracteres).
streetAddress: Logradouro (rua/avenida).
streetNumber: Número do imóvel.
complement: Complemento (opcional, máx. 100 caracteres).

Dados do Cartão de Crédito#

number: Número do cartão (sem espaços).
verificationValue: Código de verificação (CVV).
firstName: Primeiro nome do titular.
lastName: Sobrenome do titular.
month: Mês de vencimento (ex: 04).
year: Ano de vencimento (ex: 2035).
numberOfInstallments: Número de parcelas (de 1 a 12, default 1).
tdsServerTransId: Identificador da autenticação 3DS (UUID), obtido no navegador do comprador.
O campo numberOfInstallments utiliza 1 como valor padrão, portanto não precisa ser enviado em caso de pagamento à vista.

Tokenização de cartão de crédito#

A tokenização permite que o integrador salve um cartão de crédito de forma segura e reutilize esse cartão em cobranças futuras sem precisar enviar os dados sensíveis novamente. 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.
Isso é útil para:
Cobranças recorrentes — assinaturas, planos ou renovações sem pedir o cartão novamente.
Compra com um clique — experiências de checkout mais rápidas para clientes que já compraram.
Conformidade com PCI — o integrador não precisa armazenar nem trafegar o número do cartão após a tokenização.

Como funciona#

O fluxo acontece em três etapas:
1.
Obtenha o customerId — ao criar qualquer transação (POST /payment com Pix, boleto ou cartão), a resposta devolve um customerId que identifica o comprador dentro da sua empresa. Guarde esse valor.
2.
Tokenize o cartão — chame POST /payment/credit-card-token informando o customerId e os dados do cartão (mesma forma do campo creditCard de POST /payment). A rota cria o cartão na adquirente e devolve um cardId.
3.
Cobre com o token — chame POST /payment com paymentMethod: CREDIT_CARD e o objeto creditCardToken contendo customerId e cardId, sem enviar customer e sem enviar creditCard. O comprador e o endereço são obtidos automaticamente do cliente dono do cartão.
Uma vez tokenizado, o mesmo cardId pode ser usado em quantas cobranças forem necessárias.

Cobrança com cartão tokenizado#

Ao enviar creditCardToken, os campos customer e creditCard não devem estar presentes no body.
Campos de creditCardToken:
customerId (obrigatório): Id do cliente dono do cartão.
cardId (obrigatório): Id do cartão tokenizado.
numberOfInstallments (opcional): Quantidade de parcelas (1 a 12, padrão: 1).
Opcionalmente, envie um address junto com creditCardToken. O endereço será usado nesta cobrança e atualizará o cadastro do cliente.

Observações#

Cobranças com cartão tokenizado não passam por autenticação 3DS. O campo tdsServerTransId não se aplica a creditCardToken.
Um cardId pode ser reutilizado em múltiplas cobranças sem restrição de quantidade.

Autenticação 3DS#

O 3DS (3-D Secure) autentica o portador do cartão junto ao banco emissor, antes da cobrança. Quando a autenticação é aprovada, a responsabilidade por um eventual chargeback fraudulento passa do lojista para o emissor (liability shift).
O 3DS não é habilitado por padrão: ele é ativado por empresa pela equipe da Bestfy, junto com um valor mínimo opcional de transação. Enquanto sua empresa não tiver o 3DS habilitado, nada muda — o campo tdsServerTransId simplesmente não precisa ser enviado.
Se a sua empresa tem 3DS habilitado, a autenticação é obrigatória: um pagamento com cartão que deveria ser autenticado e chega sem o tdsServerTransId é recusado com 400 e o código COMPANY_E028.
Exceção: cobranças com creditCardToken (cartão tokenizado) não passam por 3DS, independentemente da configuração da empresa.

Fluxo de integração#

A autenticação acontece no navegador do comprador, antes de chamar POST /payment:
1.
Peça um token de sessão ao endpoint GET /payment/tds-token, autenticando com o mesmo header x-api-key. A resposta é { "tdsToken": "<JWT>" }. O token expira em cerca de 20 segundos — gere um por tentativa de pagamento, imediatamente antes de iniciar a autenticação. Nunca reaproveite nem armazene.
2.
Carregue o SDK JavaScript da Stone na sua página de checkout e execute a autenticação com o token, os dados do cartão e o valor:
Script: https://3ds-nx-js.stone.com.br/test/v2/3ds2.min.js
Documentação para implementação: Autenticação via 3DS
Atenção: o TDS token é gerado por nossa rota backend, siga o tutorial acima apenas para integração do SDK no frontend.
3.
Leia o resultado devolvido pelo SDK. Ele retorna um trans_status e um tds_server_trans_id.
4.
Decida pelo trans_status antes de criar o pagamento:
trans_statusSignificadoO que fazer
Y / AAutenticada / tentativa registradaChamar POST /payment com creditCard.tdsServerTransId
UAutenticação indisponível no emissorChamar POST /payment sem o campo — a venda não é perdida
N / R / INegada / rejeitada / informativaNão enviar o pagamento; peça outro meio de pagamento ao comprador
5.
Crie o pagamento enviando o tds_server_trans_id no campo creditCard.tdsServerTransId. A Bestfy repassa a autenticação à adquirente, que valida o identificador contra o próprio servidor 3DS — um valor inventado, já usado ou de outro cartão faz a transação falhar sem cobrança.

Bandeiras suportadas#

O servidor 3DS da adquirente roteia autenticação apenas para Visa e Mastercard. Cartões de outras bandeiras (Elo, Amex, Hipercard) são processados normalmente sem autenticação e sem liability shift, mesmo com o 3DS habilitado na empresa — não é necessário nenhum tratamento especial da sua parte.

Indisponibilidade#

Se o serviço de autenticação estiver fora do ar no momento da cobrança, a Bestfy processa o pagamento sem 3DS em vez de recusar a venda. Na prática, isso significa que uma transação sem tdsServerTransId pode ser aceita mesmo com o 3DS habilitado — o comportamento é intencional e não requer nenhuma ação da sua parte.

Status após a criação#

PIX e boleto respondem com a transação já PENDING: a cobrança foi emitida e aguarda o pagamento. O mesmo status vai no webhook de criação.
Cartão de crédito responde apenas o financialTransactionId. A transação fica PROCESSING até o meio de pagamento confirmar, e o desfecho (PAID ou REJECTED) chega por webhook. Quando o emissor recusa o cartão na hora, a resposta é 400 com o código FINANCIAL_TRANSACTION_E025 e nenhum webhook é enviado.
O ciclo de vida completo está em Status de Pagamento na Bestfy.

Idempotência#

A API impede que a mesma cobrança seja criada duas vezes, como em requisições simultâneas ou num reenvio imediato depois de um timeout. Não é preciso enviar cabeçalho de idempotência: a proteção é automática.
Duas requisições representam a mesma cobrança quando coincidem a empresa, o paymentMethod, o comprador (cpfOrCnpj e email), os itens (productTitle, quantity e priceCents, na mesma ordem) e o valor final. Os dados do cartão e o número de parcelas não contam: trocar de cartão não torna a compra diferente.
Se existe uma cobrança igual criada há menos de 10 segundos, e ela não foi recusada nem expirou, a nova requisição responde 400 com o código FINANCIAL_TRANSACTION_E002 e nenhuma cobrança nova é criada. A resposta não devolve a cobrança existente.
Se a cobrança anterior foi recusada ou expirou, a nova tentativa é aceita na hora.
Depois de 10 segundos, uma requisição igual cria uma nova cobrança.
Se você reenviar depois de um timeout e receber o FINANCIAL_TRANSACTION_E002, a cobrança da primeira tentativa já existe: aguarde o webhook dela, que traz o transactionId, em vez de insistir no reenvio.

Erros comuns#

CódigoMotivo
400Requisição inválida (ex: endereço ausente quando obrigatório)
400COMPANY_E028 — autenticação 3DS obrigatória para esta transação (veja Autenticação 3DS)
400tdsServerTransId fora do formato UUID
400FINANCIAL_TRANSACTION_E038 — creditCard e creditCardToken enviados juntos
400FINANCIAL_TRANSACTION_E039 — customer e creditCardToken enviados juntos
400FINANCIAL_TRANSACTION_E002: cobrança idêntica criada há menos de 10 segundos (veja Cobrança duplicada)
400FINANCIAL_TRANSACTION_E025: cartão recusado pelo emissor
404Recurso não encontrado
404CUSTOMER_E001 — customerId não pertence à empresa da API key
404CUSTOMER_CREDIT_CARD_TOKEN_E003 — cardId não pertence ao customerId informado
500Erro interno — tente novamente após alguns segundos
500Erro ao criar pagamento com cartão — dados inválidos
O endpoint GET /payment/tds-token responde 400 com o código COMPANY_E027 ("3DS não habilitado para esta empresa") quando a autenticação não está ativa para a sua empresa. Trate esse retorno como "siga o pagamento sem 3DS", não como falha.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Resposta para pagamento PIX
application/json
Bodyapplication/json

🟢201Resposta para pagamento BOLETO
🟢201Resposta para pagamento CREDIT_CARD
🟠400creditCard e creditCardToken enviados juntos
🟠400customer enviado junto com creditCardToken
🟠400customer ausente sem creditCardToken
🟠404Recurso não encontrado
🟠404Cartão tokenizado não pertence ao cliente informado
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api.bestfy.io/payment' \
--header 'User-Agent: <nome-do-projeto>' \
--header 'x-api-key: <api-key>' \
--header 'x-end-user-ip: <ip-do-usuário>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "paymentMethod": "PIX",
  "items": [
    {
      "productTitle": "Produto XYZ",
      "description": "Descrição do produto XYZ",
      "quantity": 1,
      "priceCents": 1000,
      "productType": "COMMON"
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "johndoe@email.com",
    "phone": "11999999999",
    "cpfOrCnpj": "89415463000128"
  },
  "metadata": "{\"key\": \"value\"}",
  "address": {
    "postalCode": "59127-490",
    "neighborhood": "Potengi",
    "city": "Natal",
    "state": "RN",
    "streetAddress": "Rua Serra da Esperança",
    "streetNumber": "123"
  },
  "creditCardToken": {
    "customerId": "01912ce8-b6ee-79b7-bd6a-297f1fef14f6",
    "cardId": "01912ce8-b6ee-79b7-bd6a-297f1fef14f7",
    "numberOfInstallments": 1
  },     
  "postbackUrl": "https://example.com/postback"
}'
Response Response Example
201 - Exemplo PIX
{
    "financialTransactionId": "019c009b-ae07-2c60-cf14-abc48d02ca1d",
    "qrCode": "https://faturas.iugu.com/qr_code/7d531bed-3d3f-4088-a4be-c82e5f08ed5e-7fbd",
    "qrCodeText": "00020101021226890014br.gov.bcb.pix2567qr.iugu.com/public/payload/v2/cobv/7D531BED3D3F4088A4BEC82E5F08ED5E520400005303986540510.005802BR5919JOAO PEDRO PRODUCER6012PORTO ALEGRE62070503***6304D647"
}
Modified at 2026-10-01 18:56:09
Previous
Remover anotação
Next
Estornar transação
Built with