Criar transações
POST
https://api.bestfy.io/payment
O payload utiliza valores em centavos para garantir precisão e valida a posse da
companyId via x-api-key.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.Para testar outros métodos de pagamento, selecione entre:
Regras de uso
Campos obrigatórios
paymentMethoditemscustomerDados 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.address):productType = COMMON.DIGITAL.creditCard):paymentMethod = CREDIT_CARD.Detalhes do Cliente (customer)
name: Nome completo.email: E-mail.phone: Telefone com código do país (ex: 5511999999999).cpfOrCnpj: CPF ou CNPJ.-, /, +).Detalhes dos Itens (items)
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).tdsServerTransId: Identificador da autenticação 3DS (UUID), obtido no navegador do comprador.numberOfInstallments utiliza 1 como valor padrão, portanto não precisa ser enviado em caso de pagamento à vista.Autenticação 3DS
tdsServerTransId simplesmente não precisa ser enviado.tdsServerTransId é recusado com 400 e o código COMPANY_E028.Fluxo de integração
POST /payment:1.
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.
https://3ds-nx-js.stone.com.br/test/v2/3ds2.min.js3.
trans_status e um tds_server_trans_id.4.
trans_status antes de criar o pagamento:trans_status | Significado | O que fazer |
|---|---|---|
Y / A | Autenticada / tentativa registrada | Chamar POST /payment com creditCard.tdsServerTransId |
U | Autenticação indisponível no emissor | Chamar POST /payment sem o campo — a venda não é perdida |
N / R / I | Negada / rejeitada / informativa | Não enviar o pagamento; peça outro meio de pagamento ao comprador |
5.
tds_server_trans_id no campo creditCard.tdsServerTransId. A Bestyfy 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
Indisponibilidade
tdsServerTransId pode ser aceita mesmo com o 3DS habilitado — o comportamento é intencional e não requer nenhuma ação da sua parte.Erros comuns
| Código | Motivo |
|---|---|
400 | Requisição inválida (ex: endereço ausente quando obrigatório) |
400 | COMPANY_E028 — autenticação 3DS obrigatória para esta transação (veja Autenticação 3DS) |
400 | tdsServerTransId fora do formato UUID |
404 | Recurso não encontrado |
500 | Erro interno — tente novamente após alguns segundos |
500 | Erro ao criar pagamento com cartão — dados inválidos |
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
Responses
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"
},
"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-08-19 14:38:13