Idempotency

The reference field

B4bit Pay does not expose a standard Idempotency-Key header, but it offers a functional equivalent: the reference field on POST /orders/.

• Type: string.
• Length: 1-256 characters.
• Scope: you choose the format and uniqueness.

Recommendations

1. Use your internal order ID as reference. For example, if your e-commerce generates orders like ORD-2026-04-17-000123, pass it as is.
2. Guarantee uniqueness: if you retry POST /orders/ after a timeout, you should not create a duplicate order in your system. Control retries with a local table and a single reference per attempt.
3. Persist the returned identifier alongside your reference for bidirectional lookups.
4. Recommended format: UUID v4 or {type}-{date}-{id}-{random} (for example ORD-20260417-000123-ab34).

Caution

If you create two orders with the same reference, both are processed (B4bit Pay does not deduplicate automatically). Idempotency is the merchant’s responsibility.

Reconciliation

When you receive a webhook, use it to locate your internal order by reference:

// pseudocódigo
async function handleWebhook(body) {
  const order = await db.orders.findOne({ b4bit_identifier: body.identifier });
  if (!order) {
    // no debería pasar si persistió `reference` + `identifier` al crear.
    logger.warn('Webhook de orden desconocida', { identifier: body.identifier });
    return;
  }
  await db.orders.updateStatus(order.id, body.status, body);
}

What NOT to use as reference

• Customer email (not unique per order).
• The amount (not unique per order).
• A timestamp in seconds with no other factor (collisions are easy under load).