Skip to main content
POST
/
payment
curl --request POST \
  --url https://api.bestfy.io/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "paymentMethod": "PIX",
  "items": [
    {
      "productTitle": "Produto de teste",
      "description": "Este é um produto de teste na criação do pagamento",
      "quantity": 1,
      "priceCents": 1000
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "johndoe@email.com",
    "phone": "+55 (11) 99999-9999",
    "cpfOrCnpj": "89.415.463/0001-28",
    "postalCode": "59127-490",
    "neighborhood": "Potengi",
    "city": "Natal",
    "state": "RN",
    "streetAddress": "Rua Serra da Esperança"
  }
}
'
{
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "qrCodeText": "00020126580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426614174000..."
}
Use este endpoint para criar uma transação completa informando metadados de pagamento, cliente e itens. O payload usa valores em centavos para manter precisão e valida a posse da companyId via x-api-key. Suporta atualmente PIX e boleto; cartão será adicionado em breve.

​
Regras de uso

Todos os campos listados abaixo são obrigatórios para o processamento da transação.

​
Dados da Transação

  • paymentMethod: Método de pagamento (PIX ou BOLETO).
  • items: Lista de produtos ou serviços (veja detalhes abaixo).
  • customer: Objeto contendo os dados do pagador.

​
Detalhes do Cliente (customer)

Todos os dados de endereço e contato são necessários:
  • name: Nome completo.
  • email: E-mail.
  • phone: Telefone com código do país (ex: +55 (11) 99999-9999).
  • cpfOrCnpj: CPF ou CNPJ.
  • postalCode: CEP no formato brasileiro.
  • neighborhood: Bairro.
  • city: Cidade.
  • state: Sigla do estado (UF, 2 letras).
  • streetAddress: Endereço completo (Rua, número e complemento).

​
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).

​
Erros comuns

CódigoMotivo
400Requisição inválida
404Algum recurso não encontrado
500Erro interno — reenvie após alguns segundos

Authorizations

​
x-api-key
string
header
required

Key pública disponibilizada no dashboard Bestfy.

Body

application/json
​
paymentMethod
enum<string>
required

Método de pagamento.

Available options:
PIX,
BOLETO
​
items
object[]
required

Lista de itens do pagamento. Produtos não existentes serão criados automaticamente.

Minimum length: 1
​
customer
object
required

Dados completos do cliente, validados pelo adquirente.

Response

Pagamento criado com sucesso. O formato da resposta varia conforme o método de pagamento.

​
qrCode
string
required

QR Code em formato base64 (data URI) para exibição imediata.

Example:

"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."

​
qrCodeText
string
required

Código Pix copia e cola para pagamento manual.

Example:

"00020126580014BR.GOV.BCB.PIX0136123e4567-e89b-12d3-a456-426614174000..."