Documentação para desenvolvedores

Criar um pedido de pagamento em stablecoins

Crie pedidos USDT / USDC no servidor com requisições API assinadas. Confira campos, rede, valor completo, URL de pagamento, validade e configuração do Webhook.

POST /api/v1/order/create

Autenticação necessária

Inclui X-Bolt-Key, X-Bolt-Timestamp e X-Bolt-Signature. Use um timestamp atual em milissegundos e assine o timestamp junto com o corpo exato da solicitação bruta.

USDTUSDC

Correspondência exata do valor

Por que o valor retornado pela API pode ser um pouco maior?

Plano de lançamento

3 dígitos fixos

Profissional de Negócios

2-6 configuráveis

O sistema arredonda para cima conforme a precisão de identificação configurada. Se outro pedido pendente na mesma rede, moeda e carteira já usa esse valor, uma pequena diferença distingue o novo pedido. O valor devido nunca é menor que o original. Contas gratuitas usam 3 casas decimais; membros Pro podem escolher de 2 a 6. Use payment.amount da resposta.

Fluxo correspondente

Criar pedido

1

amount

Seu back-end envia o valor da liquidação e BoltUtil retorna o valor pagável na rede.

Mostrar finalização da compra

2

payment.amount

Exibe o valor exato devolvido, a rede e o endereço de recebimento ao pagador.

Verificar o pagamento na blockchain

3

Webhook

O monitor faz a correspondência por rede, endereço, token, valor e status do pedido antes de notificá-lo.

Notas de integração

1

Exibir payment.amount da resposta de criação do pedido, não o valor da solicitação ou o preço original do produto.

2

Não arredonde, trunque ou remova o pequeno deslocamento decimal ao mostrar instruções de pagamento.

3

A alteração da precisão do deslocamento afeta apenas os pedidos recém-criados, e não os pedidos pendentes existentes.

4

Verifique a assinatura Webhook e desduplicar as notificações antes de preencher por externalOrderId e confirmar o status do pagamento. Um pagamento aguardando confirmação não significa sucesso no pagamento.

01. Corpo da solicitação

JSON Payload
amount
Obrigatório
Decimal

Valor do produto original ou ordem comercial na moeda especificada por currency. Envie uma string para evitar perda de precisão de ponto flutuante. O pagador deverá pagar o payment.amount devolvido em vez deste valor.

Mínimo básico: 1.00. Também é necessário atender ao mínimo configurado para a rede e a moeda escolhidas.Limite de precisão: até 6 casas decimaisRisco de segurança: Proíbe estritamente a passagem de valores calculados no frontend. Sempre recupere valores do seu banco de dados back-end.
externalOrderId
Obrigatório
String

Seu pedido comercial ID, usado para associar o pedido BoltUtil. As consultas usam externalOrderId; a resposta de criação retorna merchantExternalId e Webhooks retorna externalOrderId.

Deve ser globalmente exclusivo por comercianteCompatível: letras, números, sublinhados (_), hífens (-)Limite de comprimento: 6 - 64 caracteresUm ID duplicado retorna um erro em vez do pedido existente.
network
Obrigatório
String

Escolha uma rede de pagamento usando um dos valores maiúsculos abaixo. Por exemplo, use BASE para Base ou ERC20 para Ethereum.

Valor de exemplo

"network": "BASE"
Valores permitidos: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEMostrar a mesma rede na finalização da compra.
currency
Obrigatório
String

Escolha a moeda de pagamento. Passe apenas USDT ou USDC; especifique a rede separadamente em network.

Valor de exemplo

"currency": "USDC"
Valores permitidos: USDT, USDC⚠️ TRC20 suporta apenas USDT. Outros pares requerem uma rota habilitada e uma carteira de recebimento válida.
orderDesc
String

Resumo opcional do produto ou negócio para registros de pedidos. O checkout atual não exibe este campo.

Formato sugerido: Recarga - [Conta de usuário]Comprimento máximo: 255 caracteres
notifyUrl
URL

Receptor Webhook para este pedido. Se omitido, será usado o endereço padrão habilitado no painel do comerciante.

Deve ser HTTPSDeve ser acessível publicamenteImutável: Este URL não pode ser modificado depois que o pedido for criado.Antes de criar um pedido, configure e habilite o Webhook e o segredo de assinatura em seu painel. Este parâmetro não substitui essa configuração.Comprimento máximo: 255 caracteres
returnUrl
URL

Após a conclusão do pagamento ou o usuário optar por retornar, a finalização da compra redireciona o navegador para este URL. É apenas um destino de navegação e não comprova o sucesso do pagamento.

Verifique o pagamento por meio do Webhook assinado ou de uma consulta de status do pedidoSe omitido, o padrão é https://boltutil.com.Comprimento máximo: 255 caracteres
expiredMinutes
Long

O número de minutos que um pedido permanece pagável após a criação. O plano gratuito é fixado em 30 minutos; Os membros Pro podem escolher de 15 a 60 minutos.

Intervalo configurável: 15 a 60 minutosPadrão: 30 minutosSomente membros Pro podem personalizar este valor; o plano gratuito é fixado em 30 minutosContas gratuitas ignoram valores personalizados dentro do intervalo válido e usam 30 minutos. Use time.expireTimestamp como a validade real.
metadata
Map

JSON data definido pelo comerciante. BoltUtil não o modifica e o retorna inalterado na resposta de criação do pedido, na resposta de status do pedido e no Webhook.

Formato: objeto JSON padrãoDevolvido inalterado e nunca usado para correspondência de pagamentoNo máximo 10 chaves de nível superior

02. Detalhes da resposta

application/json
orderToken
BoltUtil identificador de pedido para abertura de checkout. As consultas do comerciante API usam externalOrderId.
merchantExternalId
Corresponde ao externalOrderId na solicitação.
status
PENDING após criação bem-sucedida. Consulte a documentação de status do pedido para pagamentos posteriores e estados de retorno de chamada.
Consultar o status do pedido →
checkoutUrl
O link de pagamento exclusivo para finalização da compra.
returnUrl
Endereço de devolução do checkout. O padrão é https://boltutil.com se omitido.
metadata
O objeto de passagem personalizado data.

data.payment { ... }

address
Carteira de recebimento do comerciante usada por este pedido. Vários pedidos podem compartilhar este endereço; nenhum novo endereço é gerado por pedido.
amount
Valor exato a pagar, retornado como uma string. Exiba-o por extenso, sem arredondamentos ou truncamentos.
rawAmount
Quantidade na menor unidade de token, retornada como uma string inteira: payment.amount × 10^payment.decimal. Para decimal = 6, um token equivale a 1.000.000 das menores unidades.
currency
Símbolo da moeda.
network
Identificador de rede.
qrData
String de endereço para gerar um código QR de pagamento. Não inclui valor, moeda ou rede. Exiba payment.amount, currency e network separadamente.
decimal
Precisão do token nesta rede, usada para converter rawAmount. Não é a precisão que distingue os valores dos pedidos.

data.time { ... }

expireTimestamp
Em data.time: expiração do pedido em Unix milissegundo timestamp.
serverTimestamp
Em data.time: hora do servidor quando a resposta foi gerada, como um milissegundo Unix timestamp.

Erros comuns

Estes são casos comuns. Use o status real do HTTP e o código/mensagem de resposta para diagnosticar falhas. Uma resposta de erro não é um resultado de pagamento.

  • 401: Verifique a chave API, a assinatura do corpo bruto e o milissegundo atual timestamp (dentro de 5 minutos do relógio do servidor).
  • 400: externalOrderId já existe. Consulte o pedido original em vez de criar um pedido comercial duplicado.
  • 400: Verifique os parâmetros necessários, rede/ativo disponível, carteira de recebimento e configuração Webhook habilitada.
  • 429: Limite de requisições ou cota diária gratuita de criação de pedidos atingido. Confira o código de erro e message.
create / cURL
# Run against your account only when ready; this sends an API request.
: "${BOLTUTIL_API_KEY:?Set your complete API Key}"
: "${BOLTUTIL_WEBHOOK_SECRET:?Set your Webhook secret}"
timestamp=$(python3 -c 'import time; print(int(time.time()*1000))')
body='{"amount":"25.00","currency":"USDT","network":"TRC20","externalOrderId":"INV-20260209-99281"}'
signature=$(printf '%s.%s' "$timestamp" "$body" | openssl dgst -sha256 -hmac "$BOLTUTIL_WEBHOOK_SECRET" | awk '{print $NF}')

curl --request POST "https://api.boltutil.com/api/v1/order/create" \
  --header 'Content-Type: application/json' \
  --header "X-Bolt-Key: $BOLTUTIL_API_KEY" \
  --header "X-Bolt-Timestamp: $timestamp" \
  --header "X-Bolt-Signature: $signature" \
  --data-binary "$body"

Endereços, hashes de transações e pedidos são exemplos. Substitua-os pelo seu próprio teste data.

Base URL

PROD
https://api.boltutil.com