Documentación para desarrolladores

Crear un pedido de pago con stablecoins

Crea órdenes USDT / USDC desde tu servidor con solicitudes API firmadas. Revisa campos, red, importe completo, URL de pago, vencimiento y configuración del Webhook.

POST /api/v1/order/create

Autenticación requerida

Incluye X-Bolt-Key, X-Bolt-Timestamp y X-Bolt-Signature. Utilice un timestamp actual de milisegundos y firme el timestamp junto con el cuerpo exacto de la solicitud sin formato.

USDTUSDC

Importe exacto coincidente

¿Por qué el importe devuelto por la API puede ser ligeramente mayor?

Plan de lanzamiento

3 dígitos fijos

Profesional de negocios

2-6 configurables

El sistema redondea hacia arriba según la precisión de identificación configurada. Si otro pedido pendiente de la misma red, moneda y cartera ya usa ese importe, añade una pequeña diferencia para distinguir el nuevo pedido. El importe exigible nunca es menor que el original. Las cuentas gratuitas usan 3 decimales; los miembros Pro pueden elegir entre 2 y 6. Usa payment.amount de la respuesta.

Flujo coincidente

Crear pedido

1

amount

Su backend envía el monto de la liquidación y BoltUtil devuelve el monto pagadero en cadena.

Mostrar pago

2

payment.amount

Muestra el monto exacto devuelto, la red y la dirección de recepción al pagador.

Verificar el pago en cadena

3

Webhook

El monitor busca coincidencias por red, dirección, token, monto y estado del pedido antes de notificarle.

Notas de integración

1

Muestre payment.amount de la respuesta de creación de pedido, no el monto de la solicitud ni el precio original del producto.

2

No redondee, trunque ni elimine el desplazamiento decimal pequeño al mostrar las instrucciones de pago.

3

Cambiar la precisión de compensación solo afecta a las órdenes recién creadas, no a las órdenes pendientes existentes.

4

Verifique la firma Webhook y elimine las notificaciones antes de cumplir con externalOrderId y confirmar el estado de pago. Un pago pendiente de confirmación no es un pago exitoso.

01. Cuerpo de la solicitud

JSON Payload
amount
Obligatorio
Decimal

Cantidad del producto original o del pedido comercial en la moneda especificada por currency. Envíe una cadena para evitar la pérdida de precisión del punto flotante. El pagador debe pagar el payment.amount devuelto en lugar de este valor.

Mínimo básico: 1.00. También debe cumplirse el mínimo configurado para la red y moneda seleccionadas.Límite de precisión: hasta 6 decimalesRiesgo de seguridad: está estrictamente prohibido pasar cantidades calculadas en la interfaz. Recupere siempre valores de su base de datos backend.
externalOrderId
Obligatorio
String

Su pedido comercial ID, utilizado para asociar el pedido BoltUtil. Las consultas utilizan externalOrderId; la respuesta de creación devuelve merchantExternalId y Webhooks devuelve externalOrderId.

Debe ser único globalmente por comercianteAdmitido: letras, números, guiones bajos (_), guiones (-)Límite de longitud: 6 - 64 caracteresUn ID duplicado devuelve un error en lugar del orden existente.
network
Obligatorio
String

Elija una red de pago utilizando uno de los valores en mayúsculas que aparecen a continuación. Por ejemplo, utilice BASE para Base o ERC20 para Ethereum.

Valor de ejemplo

"network": "BASE"
Valores permitidos: TRC20, ERC20, BEP20, POLYGON, SOLANA, BASEMostrar la misma red al finalizar la compra.
currency
Obligatorio
String

Elija la moneda de pago. Pase solo USDT o USDC; especifique la red por separado en network.

Valor de ejemplo

"currency": "USDC"
Valores permitidos: USDT, USDC⚠️ TRC20 solo admite USDT. Otros pares requieren una ruta habilitada y una billetera receptora válida.
orderDesc
String

Resumen de producto o negocio opcional para registros de pedidos. La compra actual no muestra este campo.

Formato sugerido: Recarga - [Cuenta de usuario]Longitud máxima: 255 caracteres
notifyUrl
URL

Receptor Webhook para este pedido. Si se omite, se utiliza la dirección predeterminada habilitada en el panel de su comerciante.

Debe ser HTTPSDebe ser de acceso públicoInmutable: este URL no se puede modificar una vez creado el pedido.Antes de crear un pedido, configure y habilite el Webhook y el secreto de firma en su panel. Este parámetro no reemplaza esa configuración.Longitud máxima: 255 caracteres
returnUrl
URL

Una vez que se completa el pago o el usuario decide regresar, el proceso de pago redirige el navegador a este URL. Es solo un destino de navegación y no demuestra el éxito del pago.

Verificar el pago a través del Webhook firmado o una consulta de estado del pedidoSi se omite, el valor predeterminado es https://boltutil.com.Longitud máxima: 255 caracteres
expiredMinutes
Long

La cantidad de minutos que un pedido permanece pagadero después de su creación. El plan gratuito se fija en 30 minutos; Los miembros Pro pueden elegir entre 15 y 60 minutos.

Rango configurable: 15-60 minutosPredeterminado: 30 minutosSolo los miembros Pro pueden personalizar este valor; el plan gratuito se fija en 30 minutosLas cuentas gratuitas ignoran los valores personalizados dentro del rango válido y usan 30 minutos. Utilice time.expireTimestamp como vencimiento real.
metadata
Map

JSON data definido por el comerciante. BoltUtil no lo modifica y lo devuelve sin cambios en la respuesta de creación de pedido, en la respuesta de estado del pedido y en Webhook.

Formato: objeto estándar JSONDevuelto sin cambios y nunca utilizado para igualar pagosComo máximo 10 claves de nivel superior

02. Detalles de la respuesta

application/json
orderToken
BoltUtil identificador de pedido para abrir el pago. Las consultas del comerciante API utilizan externalOrderId.
merchantExternalId
Corresponde al externalOrderId en la solicitud.
status
PENDING después de una creación exitosa. Consulte la documentación del estado del pedido para conocer los estados de pago y devolución de llamada posteriores.
Consultar el estado del pedido →
checkoutUrl
El enlace de pago exclusivo.
returnUrl
Dirección de devolución de pago. El valor predeterminado es https://boltutil.com si se omite.
metadata
El objeto de paso personalizado data.

data.payment { ... }

address
Monedero receptor del comerciante utilizado para este pedido. Es posible que varios pedidos compartan esta dirección; no se genera ninguna dirección nueva por pedido.
amount
Cantidad exacta a pagar, devuelta como una cadena. Muéstrelo completo sin redondearlo ni truncarlo.
rawAmount
Cantidad en la unidad de token más pequeña, devuelta como una cadena entera: payment.amount × 10^payment.decimal. Para decimal = 6, un token equivale a 1.000.000 de unidades más pequeñas.
currency
Símbolo de moneda.
network
Identificador de red.
qrData
Cadena de dirección para generar un código QR de pago. No incluye importe, moneda ni red. Muestra payment.amount, currency y network por separado.
decimal
Precisión del token en esta red, usada para convertir rawAmount. No es la precisión para distinguir importes de pedidos.

data.time { ... }

expireTimestamp
En data.time: el vencimiento del pedido es un milisegundo Unix timestamp.
serverTimestamp
En data.time: hora del servidor cuando se generó la respuesta, como milisegundos Unix timestamp.

Errores comunes

Estos son casos comunes. Utilice el estado actual de HTTP y el código/mensaje de respuesta para diagnosticar fallas. Una respuesta de error no es un resultado de pago.

  • 401: verifique la clave API, la firma del cuerpo sin formato y el milisegundo actual timestamp (dentro de los 5 minutos del reloj del servidor).
  • 400: externalOrderId ya existe. Consulta el pedido original en lugar de crear un pedido comercial duplicado.
  • 400: verifique los parámetros requeridos, la red/activo disponible, la billetera receptora y la configuración Webhook habilitada.
  • 429: Se alcanzó el límite de solicitudes o la cuota diaria gratuita de creación de pedidos. Revisa el código de error y 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"

Direcciones, hashes de transacciones y pedidos son ejemplos. Reemplácelos con su propia prueba data.

Base URL

PROD
https://api.boltutil.com