1. Transações
Bestfy API
  • Sobre a Bestfy
    • Comece aqui
  • Webhooks
    • O que é um Webhook?
  • Status de transação
    • Status de Pagamento na Bestfy
  • Transações
    • Criar transações
      POST
    • Estornar transação
      POST
    • Buscar transação
      GET
    • Listar transações
      GET
  • 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 listados abaixo são 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.
Regra de obrigatoriedade do endereço (address):
Obrigatório quando existir um ou mais itens com productType = COMMON.
Opcional quando todos os itens forem do tipo DIGITAL.
Regra de obrigatoriedade do cartão de crédito (creditCard):
Obrigatório quando o método de pagamento for paymentMethod = CREDIT_CARD.

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 (-, /, +).

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 (UF, 2 letras).
streetAddress: Logradouro (rua/avenida) e complemento, se houver.
streetNumber: Número do imóvel.

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).
O campo numberOfInstallments utiliza 1 como valor padrão, portanto não precisa ser enviado em caso de pagamento à vista.

Erros comuns#

CódigoMotivo
400Requisição inválida (ex: endereço ausente quando obrigatório)
404Recurso não encontrado
500Erro interno — tente novamente após alguns segundos
500Erro ao criar pagamento com cartão — dados inválidos

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Resposta para pagamento PIX
application/json
Body

🟢201Resposta para pagamento BOLETO
🟢201Resposta para pagamento CREDIT_CARD
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST '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"
  },
  "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-04-02 20:00:37
Previous
Status de Pagamento na Bestfy
Next
Estornar transação
Built with