POST /orders/

• Method: POST
• URL: https://pos.b4bit.com/api/v1/orders/
• Content-Type: application/json (recommended) or multipart/form-data.
• Authentication: X-Device-Id header.

Tip

The endpoint accepts both formats. Use application/json unless you need to upload binaries (not applicable today, only scalar fields). JSON is more ergonomic: native types, less escaping, better support in modern HTTP clients.

Fields

Required

Field	Type	Description
expected_output_amount	number	Amount to charge, in the fiat currency.

Main optional fields

Field	Type	Default	Description
input_currency	string	—	Crypto symbol (from GET /currencies). If omitted, the customer picks on the gateway.
fiat	enum	MXN	MXN (default), USD, EUR, GBP, ARS, BRL, COP, CLP and 22 more.
language	string	ES	Gateway language.
notes	string (≤512)	—	Product/service description.
reference	string (1-256)	—	Your internal ID. Key for idempotency — see idempotency.
internal_data	string (1-1024)	—	Free-form merchant metadata.

Redirects (Redirect Gateway)

Field	Type	Description
merchant_urlok	URI	Redirect after payment completed.
merchant_urlko	URI	Redirect after payment not completed / expired.
merchant_url_standby	URI	Redirect while awaiting confirmation.

Customer personal data (optional)

See kyc-fields for the full detail.

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

Examples — JSON (recommended)

cURL

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/

Node (undici)

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();

Python

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()

PHP

$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);

Examples — multipart/form-data

Historic alternative. Useful if your stack has poor JSON support or if you prefer to send all fields as string uniformly.

cURL

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/

Node (undici)

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();

Python

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()

200 response

With 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"
}

Without input_currency

Only returns the fields identifier, reference, web_url, notes, fiat, language. Crypto-dependent fields (payment_uri, address, tag_memo, expected_input_amount, rate) are generated when the customer picks the currency on the gateway.

Errors

• 403 — Missing or invalid X-Device-Id.
• 404 — Invalid currency, amount below the minimum, missing URLs, or missing DNI image. See errors.
• 429 — Rate limit.
• 500 — Internal error.

Caution

XRP / XLM / ALGO — if your input_currency is one of these, the response includes tag_memo. Display it to the customer alongside the address. Without the TAG/MEMO, the funds are lost.

Tip

Idempotency — use your own order ID as reference. If you need to retry the POST (because of a timeout), use a control table to avoid creating two orders with the same reference. See idempotency.