Documentation développeur

Créer une commande de paiement en stablecoins

Créez des commandes USDT / USDC côté serveur avec des requêtes API signées. Vérifiez les champs, le réseau, le montant complet, le lien de paiement, l’expiration et le Webhook.

POST /api/v1/order/create

Authentification requise

Inclut X-Bolt-Key, X-Bolt-Timestamp et X-Bolt-Signature. Utilisez un timestamp actuel en millisecondes et signez le timestamp avec le corps brut exact de la requête.

USDTUSDC

Correspondance exacte du montant

Pourquoi le montant renvoyé par l’API peut-il être légèrement supérieur ?

Plan de lancement

3 chiffres fixes

Entreprise Pro

2-6 configurables

Le système arrondit le montant vers le haut selon la précision configurée. Si une commande en attente utilise déjà ce montant sur le même réseau, avec la même devise et le même portefeuille, un petit écart distingue la nouvelle commande. Le montant dû n’est jamais inférieur au montant initial. Les comptes gratuits utilisent 3 décimales ; les membres Pro peuvent choisir entre 2 et 6. Utilisez payment.amount de la réponse.

Flux correspondant

Créer une commande

1

amount

Votre backend envoie le montant du règlement et BoltUtil renvoie le montant payable en chaîne.

Afficher le paiement

2

payment.amount

Affichez le montant exact retourné, le réseau et l'adresse de réception au payeur.

Vérifier le paiement sur la blockchain

3

Webhook

Le moniteur effectue des comparaisons par réseau, adresse, jeton, montant et statut de la commande avant de vous en informer.

Notes d'intégration

1

Affichez payment.amount à partir de la réponse de création de commande, et non le montant de la demande ou le prix d'origine du produit.

2

Ne pas arrondir, tronquer ou supprimer le petit décalage décimal lors de l'affichage des instructions de paiement.

3

La modification de la précision du décalage n'affecte que les commandes nouvellement créées, pas les commandes en attente existantes.

4

Vérifiez la signature Webhook et dédoublonnez les notifications avant de remplir par externalOrderId et de confirmer le statut de paiement. Un paiement en attente de confirmation n'est pas un paiement réussi.

01. Corps de la demande

JSON Payload
amount
Obligatoire
Decimal

Montant initial du produit ou de la commande commerciale dans la devise spécifiée par currency. Envoyez une chaîne pour éviter la perte de précision en virgule flottante. Le payeur doit payer le payment.amount retourné plutôt que cette valeur.

Minimum de base : 1.00. Le minimum configuré pour le réseau et la devise choisis doit également être respecté.Limite de précision : jusqu'à 6 décimalesRisque de sécurité : Interdire strictement de transmettre les montants calculés sur le frontend. Récupérez toujours les valeurs de votre base de données backend.
externalOrderId
Obligatoire
String

Votre commande commerciale ID, utilisée pour associer la commande BoltUtil. Les requêtes utilisent externalOrderId ; la réponse de création renvoie merchantExternalId et Webhooks renvoie externalOrderId.

Doit être unique au monde par commerçantSupporté : lettres, chiffres, traits de soulignement (_), traits d'union (-)Longueur limite : 6 à 64 caractèresUn ID en double renvoie une erreur plutôt que la commande existante.
network
Obligatoire
String

Choisissez un réseau de paiement en utilisant l'une des valeurs majuscules ci-dessous. Par exemple, utilisez BASE pour Base ou ERC20 pour Ethereum.

Exemple de valeur

"network": "BASE"
Valeurs autorisées : TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEAfficher le même réseau lors du paiement.
currency
Obligatoire
String

Choisissez la devise de paiement. Transmettez uniquement USDT ou USDC ; spécifiez le réseau séparément dans network.

Exemple de valeur

"currency": "USDC"
Valeurs autorisées : USDT, USDC⚠️ TRC20 prend en charge uniquement USDT. D'autres paires nécessitent un itinéraire activé et un portefeuille de réception valide.
orderDesc
String

Résumé facultatif du produit ou de l'entreprise pour les enregistrements de commande. La caisse actuelle n'affiche pas ce champ.

Format suggéré : Recharge - [Compte utilisateur]Longueur maximale : 255 caractères
notifyUrl
URL

Récepteur Webhook pour cette commande. En cas d'omission, l'adresse par défaut activée dans votre tableau de bord marchand est utilisée.

Doit être HTTPSDoit être accessible au publicImmuable : Ce URL ne peut pas être modifié une fois la commande créée.Avant de créer une commande, configurez et activez le Webhook et le secret de signature dans votre tableau de bord. Ce paramètre ne remplace pas cette configuration.Longueur maximale : 255 caractères
returnUrl
URL

Une fois le paiement terminé ou que l'utilisateur choisit de revenir, le paiement redirige le navigateur vers ce URL. Il ne s'agit que d'une destination de navigation et ne prouve pas le succès du paiement.

Vérifiez le paiement via le Webhook signé ou une requête sur l'état de la commandeEn cas d'omission, la valeur par défaut est https://boltutil.com.Longueur maximale : 255 caractères
expiredMinutes
Long

Le nombre de minutes pendant lesquelles une commande reste payable après sa création. Le forfait gratuit est fixé à 30 minutes ; Les membres Pro peuvent choisir entre 15 et 60 minutes.

Plage configurable : 15 à 60 minutesPar défaut : 30 minutesSeuls les membres Pro peuvent personnaliser cette valeur ; le forfait gratuit est fixé à 30 minutesLes comptes gratuits ignorent les valeurs personnalisées comprises dans la plage valide et utilisent 30 minutes. Utilisez time.expireTimestamp comme date d'expiration réelle.
metadata
Map

JSON data défini par le marchand. BoltUtil ne le modifie pas et le renvoie inchangé dans la réponse de création de commande, la réponse de statut de commande et Webhook.

Format : objet standard JSONRenvoyé inchangé et jamais utilisé pour le rapprochement des paiementsAu maximum 10 clés de niveau supérieur

02. Détails de la réponse

application/json
orderToken
BoltUtil identifiant de commande pour l'ouverture de la caisse. Les requêtes du marchand API utilisent externalOrderId.
merchantExternalId
Correspond au externalOrderId dans la requête.
status
PENDING après une création réussie. Consultez la documentation sur l'état de la commande pour connaître les états de paiement et de rappel ultérieurs.
Consulter l’état d’une commande →
checkoutUrl
Le lien de paiement exclusif.
returnUrl
Adresse de retour de paiement. La valeur par défaut est https://boltutil.com en cas d'omission.
metadata
L'objet passthrough personnalisé data.

data.payment { ... }

address
Portefeuille de réception du commerçant utilisé par cette commande. Plusieurs commandes peuvent partager cette adresse ; aucune nouvelle adresse n'est générée par commande.
amount
Montant exact à payer, renvoyé sous forme de chaîne. Affichez-le dans son intégralité sans arrondir ni tronquer.
rawAmount
Montant dans la plus petite unité de jeton, renvoyé sous forme de chaîne entière : payment.amount × 10^payment.decimal. Pour decimal = 6, un jeton équivaut à 1 000 000 de plus petites unités.
currency
Symbole monétaire.
network
Identifiant du réseau.
qrData
Chaîne contenant l’adresse pour générer un code QR de paiement. Elle ne contient ni montant, ni devise, ni réseau. Affichez payment.amount, currency et network séparément.
decimal
Précision du token sur ce réseau, utilisée pour convertir rawAmount. Elle est distincte de la précision permettant de différencier les montants des commandes.

data.time { ... }

expireTimestamp
Dans data.time : expiration de la commande en milliseconde Unix timestamp.
serverTimestamp
Dans data.time : heure du serveur à laquelle la réponse a été générée, en milliseconde Unix timestamp.

Erreurs courantes

Ce sont des cas courants. Utilisez l'état actuel du HTTP et le code/message de réponse pour diagnostiquer les pannes. Une réponse d'erreur n'est pas un résultat de paiement.

  • 401 : Vérifiez la clé API, la signature du corps brut et la milliseconde actuelle du timestamp (dans les 5 minutes suivant l'horloge du serveur).
  • 400 : externalOrderId existe déjà. Recherchez la commande d'origine au lieu de créer une commande commerciale en double.
  • 400 : Vérifiez les paramètres requis, le réseau/actif disponible, le portefeuille de réception et la configuration Webhook activée.
  • 429 : limite de requêtes ou quota quotidien gratuit de création de commandes atteint. Vérifiez le code métier et 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"

Les adresses, les hachages de transactions et les commandes en sont des exemples. Remplacez-les par votre propre test data.

Base URL

PROD
https://api.boltutil.com