Merchant Integration API · v1.0.0

Integrate your POS with

Two API contracts and a step-by-step guide. Your POS receives orders via HMAC-signed webhooks, confirms them via REST, and advances the status until delivery.

0

API contracts

0

Languages supported

0

HMAC-SHA bits

Three resources, one integration

Integrating with BipBip is made up of two complementary API contracts and a step-by-step guide that ties them together.

Designed for reliable integrations

HMAC-SHA256 signature

Every webhook is signed with HMAC-SHA256 over {timestamp}.{rawBody}. Reject requests older than 5 minutes to block replays.

At-least-once delivery

Every attempt carries the same X-Bipbip-Delivery-Id. Dedupe on that UUID and tolerate retries without creating duplicate orders.

Idempotency-Key required

Send a unique UUID per logical attempt on every REST mutation. 24h cache, safe retries without side effects.

Samples in 4 languages

Node.js, Python, C# and PHP. All use stdlib only — no external dependencies. Copy-paste and go.

Clear state machine

Pending → Accepted → Preparing → Ready → HandedOver. Rejected and Cancelled are terminal. No ambiguity.

Path-based versioning

Everything runs under /v1/. When v2 lands you can run both in parallel while you migrate — no surprise breaking changes.

Security

Verify every webhook with HMAC

BipBip signs every request with HMAC-SHA256 over {timestamp}.{rawBody}. Capture the raw bytes, validate the timestamp (max. 300s skew) and compare in constant time.

  • Standard library only — no external dependencies
  • timingSafeEqual / compare_digest / hash_equals
  • Capture the raw body before JSON.parse
Read the full HMAC guide
// 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);
}

The 4 steps to go live

From "I have my credentials" to "I received and confirmed my first order" without help from the BipBip team.

1

Implement the webhook

Expose POST /v1/order/{remoteId} on your POS. Capture the raw body before parsing the JSON.

2

Verify the HMAC signature

Recompute HMAC-SHA256 over {timestamp}.{rawBody} and compare in constant time.

3

Respond with remoteOrderId

Return HTTP 200 with { "remoteOrderId": "..." }. Without that field BipBip will retry.

4

Accept via REST API

Call POST /api/v1/Orders/{orderKey}/accept with X-Bipbip-Api-Key and Idempotency-Key.

BipBip app icon

Before you start

BipBip hands you these during onboarding

  • HMAC Secret (one per account)
  • API Key (X-Bipbip-Api-Key)
  • remoteId (one per store)
  • Registered base URL (public)

Ready to integrate your POS with BipBip?

Coordinate with the team to get your credentials and kick off the pilot in production.