Merchant Integration API · v1.0.0

Integrá tu POS con

Dos contratos de API y una guía paso a paso. Tu POS recibe órdenes vía webhook firmado con HMAC, las confirma por REST y avanza el estado hasta la entrega.

0

Contratos API

0

Lenguajes soportados

0

Bits HMAC-SHA

Tres recursos, una integración

La integración con BipBip se compone de dos contratos de API complementarios y una guía paso a paso para unirlos.

Diseñado para integraciones confiables

Firma HMAC-SHA256

Cada webhook se firma con HMAC-SHA256 sobre {timestamp}.{rawBody}. Rechazá requests mayores a 5 minutos para bloquear replays.

Entrega at-least-once

Cada intento lleva el mismo X-Bipbip-Delivery-Id. Deduplica con ese UUID y tolerá reintentos sin crear órdenes duplicadas.

Idempotency-Key obligatoria

Mandá un UUID único por intento lógico en cada mutación REST. 24h de caché, reintentos seguros sin efectos dobles.

Samples en 4 lenguajes

Node.js, Python, C# y PHP. Todos usan solo librería estándar — sin dependencias externas. Copy-paste y andá.

Máquina de estados clara

Pending → Accepted → Preparing → Ready → HandedOver. Rejected y Cancelled son terminales. Sin ambigüedades.

Versionado en el path

Todo corre bajo /v1/. Cuando llegue v2 podrás correrlas en paralelo mientras migrás — sin breaking changes sorpresivos.

Seguridad

Verificá cada webhook con HMAC

BipBip firma cada request con HMAC-SHA256 sobre {timestamp}.{rawBody}. Capturá los bytes crudos, validá el timestamp (máx. 300s de skew) y compará en tiempo constante.

  • Solo librería estándar — sin dependencias externas
  • timingSafeEqual / compare_digest / hash_equals
  • Capturá el raw body antes de JSON.parse
Ver la guía completa de HMAC
// HMAC-SHA256 verification — Node.js (built-in crypto)
const crypto = require('crypto');

function verifyBipBipSignature(secret, timestamp, rawBody, signature) {
  // Reject requests older than 5 minutes (replay protection)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false;

  // Sign the RAW body — never JSON.parse + re-serialize
  const message = `${timestamp}.${rawBody}`;
  const computed = crypto
    .createHmac('sha256', secret)
    .update(message, 'utf8')
    .digest('hex');
  const expected = `sha256=${computed}`;

  // Timing-safe comparison (never use === on signatures)
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signature, 'utf8');
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Los 4 pasos para estar en vivo

De "tengo mis credenciales" a "recibí y confirmé mi primera orden" sin intervención del equipo BipBip.

1

Implementá el webhook

Exponé POST /v1/order/{remoteId} en tu POS. Capturá el raw body antes de parsear el JSON.

2

Verificá la firma HMAC

Recomputá HMAC-SHA256 sobre {timestamp}.{rawBody} y comparalo en tiempo constante.

3

Respondé con remoteOrderId

Devolvé HTTP 200 con { "remoteOrderId": "..." }. Sin ese campo BipBip reintenta.

4

Aceptá por REST API

Llamá POST /api/v1/Orders/{orderKey}/accept con X-Bipbip-Api-Key e Idempotency-Key.

BipBip app icon

Antes de arrancar

BipBip te entrega estos elementos durante el onboarding

  • HMAC Secret (una por cuenta)
  • API Key (X-Bipbip-Api-Key)
  • remoteId (uno por tienda)
  • Base URL registrada (pública)

¿Listo para integrar tu POS con BipBip?

Coordiná con el equipo para recibir tus credenciales y arrancá el piloto en producción.