BINK API

One API for global money movement — payments, payouts, refunds, cards, customers, invoices, and the webhooks that keep your system in sync.

What the API does

The BINK REST API is the surface behind Hosted Checkout, Payment Links, card issuing, and settlement. Every resource below is backed by a real, currently-mounted route in the production service — nothing on this page describes a planned or aspirational capability.

Getting started

1. Read Authentication — it explains which of your credentials actually authorizes which calls, since that differs by resource today (see the note below).
2. Read Environments for how sandbox and production are separated.
3. Send the request in Make your first request below.
4. Wire up Webhooks so you don't have to poll.

Authentication

BINK has two separate authentication mechanisms in production today, and they do not cover the same endpoints. Mixing them up is the single most common integration mistake, so this is stated plainly rather than smoothed over:

Environments

Sandbox and production share the same base URL and the same endpoints. For the developer probe (the one place API keys work today), the key prefix — sk_test_/pk_test_ vs sk_live_/pk_live_ — decides the mode. See Environments for the full picture, including the Egypt/Global account split, which is independent of sandbox/production.

Base URL

Every route in this reference is served under one prefix, applied globally to the API:

https://binkpay.net/api/v1

That's the public, browser-facing address — Next.js rewrites it to the backend service. If you call the backend directly instead of through the proxy, the same routes are reachable at the Railway-hosted origin. A path in this reference like POST /merchant/payments means POST https://binkpay.net/api/v1/merchant/payments in full; the resource pages omit the /api/v1 prefix for brevity everywhere it appears.

Versioning

The /api/v1 path prefix is the only versioning scheme currently in the codebase — there is no dated or SemVer release train, and no per-request version header. If that changes, it will be documented here rather than assumed.

Idempotency

Pass an Idempotency-Key header on POST /merchant/payments to make retries safe — a retried request with the same key returns the original response instead of creating a duplicate. Full details, including key scoping, are on Rate Limits & Idempotency.

Errors

Every error response — validation failure, auth rejection, or server fault — shares one envelope, including a requestId to reference when contacting support. See Errors for the full status-code table.

{
  "ok": false,
  "statusCode": 400,
  "message": "amountMinor must be a positive integer string",
  "requestId": "req_9f3a2b1c",
  "timestamp": "2026-07-08T15:04:12.331Z"
}

Rate limits

Requests are throttled per authenticated user at 600 requests per minute by default, with tighter limits on sensitive endpoints such as login. A throttled request returns 429 with a Retry-After header. See Rate Limits & Idempotency.

Webhooks

Configure an endpoint to receive real-time events instead of polling. Every delivery is signed with HMAC-SHA256 over {timestamp}.{raw body}, sent as X-Binkpay-Signature: t=…,v1=…. See Webhooks for the full event catalog and retry policy.

API resources

Make your first request

The one endpoint on this reference that genuinely accepts an API key today is the developer probe — it confirms the key works and reports which company and environment it belongs to. It requires the analytics:read scope.

curl https://binkpay.net/api/v1/developer/ping \
  -H "Authorization: Bearer sk_test_51H..."

A successful call returns your company ID, whether the key is live or test, and the scopes granted to it:

{
  "ok": true,
  "companyId": "co_4b7e21",
  "livemode": false,
  "scopes": ["analytics:read", "payments:read"]
}