POST /orders/

Método: POST
URL: https://pos.b4bit.com/api/v1/orders/
Content-Type: application/json (recomendado) o multipart/form-data.
Autenticación: header X-Device-Id.

Campos

Obligatorio

Campo	Tipo	Descripción
`expected_output_amount`	number	Importe a cobrar, en la divisa `fiat`.

Opcionales principales

Campo	Tipo	Default	Descripción
`input_currency`	string	—	Símbolo de cripto (de `GET /currencies`). Si no se pasa, el cliente elige en la pasarela.
`fiat`	enum	`MXN`	MXN (default), USD, EUR, GBP, ARS, BRL, COP, CLP y 22 más.
`language`	string	`ES`	Idioma de la pasarela.
`notes`	string (≤512)	—	Descripción del producto/servicio.
`reference`	string (1-256)	—	Su ID interno. Clave para idempotencia — ver idempotencia.
`internal_data`	string (1-1024)	—	Metadata libre del merchant.

Redirecciones (Redirect Gateway)

Campo	Tipo	Descripción
`merchant_urlok`	URI	Redirección tras pago completado.
`merchant_urlko`	URI	Redirección tras pago no completado / expirado.
`merchant_url_standby`	URI	Redirección mientras se espera confirmación.

Datos personales del cliente (opcionales)

Ver kyc-fields para el detalle completo.

full_name, email_client, phone_number, nif.
home_address, address_number, address_additional, city, province, zip_code, country.

Ejemplos — JSON (recomendado)

curl -X POST \
-H "X-Device-Id: $B4BIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "expected_output_amount": 2500.00,
  "fiat": "MXN",
  "input_currency": "USDC_POLYGON_NXTB",
  "notes": "Pedido ORD-123",
  "reference": "ORD-123",
  "merchant_urlok": "https://tu-sitio.com/pago/ok",
  "merchant_urlko": "https://tu-sitio.com/pago/error"
}' \
https://pos.b4bit.com/api/v1/orders/

import { fetch } from 'undici';

const res = await fetch('https://pos.b4bit.com/api/v1/orders/', {
method: 'POST',
headers: {
  'X-Device-Id': process.env.B4BIT_API_KEY,
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  expected_output_amount: 2500.00,
  fiat: 'MXN',
  input_currency: 'USDC_POLYGON_NXTB',
  notes: 'Pedido ORD-123',
  reference: 'ORD-123',
  merchant_urlok: 'https://tu-sitio.com/pago/ok',
  merchant_urlko: 'https://tu-sitio.com/pago/error',
}),
});
const order = await res.json();

import os, requests

r = requests.post(
  'https://pos.b4bit.com/api/v1/orders/',
  headers={'X-Device-Id': os.environ['B4BIT_API_KEY']},
  json={
      'expected_output_amount': 2500.00,
      'fiat': 'MXN',
      'input_currency': 'USDC_POLYGON_NXTB',
      'notes': 'Pedido ORD-123',
      'reference': 'ORD-123',
      'merchant_urlok': 'https://tu-sitio.com/pago/ok',
      'merchant_urlko': 'https://tu-sitio.com/pago/error',
  },
)
order = r.json()

$body = json_encode([
  'expected_output_amount' => 2500.00,
  'fiat' => 'MXN',
  'input_currency' => 'USDC_POLYGON_NXTB',
  'notes' => 'Pedido ORD-123',
  'reference' => 'ORD-123',
  'merchant_urlok' => 'https://tu-sitio.com/pago/ok',
  'merchant_urlko' => 'https://tu-sitio.com/pago/error',
]);

$ch = curl_init('https://pos.b4bit.com/api/v1/orders/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-Device-Id: ' . getenv('B4BIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$order = json_decode(curl_exec($ch), true);

Ejemplos — multipart/form-data

Alternativa histórica. Útil si su stack no tiene buen soporte de JSON o si prefiere enviar campos como string uniformemente.

curl -X POST \
-H "X-Device-Id: $B4BIT_API_KEY" \
-F "expected_output_amount=2500.00" \
-F "fiat=MXN" \
-F "input_currency=USDC_POLYGON_NXTB" \
-F "notes=Pedido ORD-123" \
-F "reference=ORD-123" \
-F "merchant_urlok=https://tu-sitio.com/pago/ok" \
-F "merchant_urlko=https://tu-sitio.com/pago/error" \
https://pos.b4bit.com/api/v1/orders/

import { fetch, FormData } from 'undici';

const form = new FormData();
form.append('expected_output_amount', '2500.00');
form.append('fiat', 'MXN');
form.append('input_currency', 'USDC_POLYGON_NXTB');
form.append('notes', 'Pedido ORD-123');
form.append('reference', 'ORD-123');
form.append('merchant_urlok', 'https://tu-sitio.com/pago/ok');
form.append('merchant_urlko', 'https://tu-sitio.com/pago/error');

const res = await fetch('https://pos.b4bit.com/api/v1/orders/', {
method: 'POST',
headers: { 'X-Device-Id': process.env.B4BIT_API_KEY },
body: form,
});
const order = await res.json();

import os, requests

r = requests.post(
  'https://pos.b4bit.com/api/v1/orders/',
  headers={'X-Device-Id': os.environ['B4BIT_API_KEY']},
  data={
      'expected_output_amount': '100.00',
      'fiat': 'MXN',
      'input_currency': 'USDC_POLYGON_NXTB',
      'notes': 'Pedido ORD-123',
      'reference': 'ORD-123',
      'merchant_urlok': 'https://tu-sitio.com/pago/ok',
      'merchant_urlko': 'https://tu-sitio.com/pago/error',
  },
)
order = r.json()

Respuesta `200`

Con `input_currency`

{
  "identifier": "1040095a-737d-41a2-a2e1-d031d19ec8cd",
  "reference": "ORD-123",
  "payment_uri": "ethereum:0x...?amount=...",
  "web_url": "https://pay.b4bit.com/...",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0b1f6",
  "tag_memo": null,
  "input_currency": "USDC_POLYGON_NXTB",
  "expected_input_amount": 100.00,
  "rate": 1.0,
  "notes": "Pedido ORD-123",
  "fiat": "MXN",
  "language": "ES"
}

Sin `input_currency`

Solo devuelve los campos identifier, reference, web_url, notes, fiat, language. Los campos crypto-dependientes (payment_uri, address, tag_memo, expected_input_amount, rate) se generan cuando el cliente elige la moneda en la pasarela.

Errores

403 — Falta o inválida X-Device-Id.
404 — Currency inválida, monto por debajo del mínimo, URLs ausentes, o falta imagen DNI. Ver errores.
429 — Rate limit.
500 — Error interno.