01
Authenticate
Send exactly one X-API-Key header. Keys are organization, scope, status, and environment bound.
Developers
Integrate scoped X-API-Key authentication, idempotent settlement commands, signed webhooks, bounded pagination, and evidence exports against the same v1 API used by YembiPay clients.
Quick start
Use a key issued to one organization and environment. Tenant authority comes from that credential; do not treat an org_id parameter as authorization.
Keep API keys server-side.
Never ship partner keys in public browser JavaScript, mobile bundles, URLs, analytics, or logs.
curl --request GET \
--url https://sandbox.yembipay.com/v1/caribbean/settlements?limit=20 \
--header 'Accept: application/json' \
--header 'X-API-Key: yp_sandbox_your_key'import os
import requests
response = requests.get(
"https://sandbox.yembipay.com/v1/caribbean/settlements",
headers={"X-API-Key": os.environ["YEMBIPAY_API_KEY"]},
params={"limit": 20, "offset": 0},
timeout=10,
)
response.raise_for_status()
settlements = response.json()const url = new URL(
"/v1/caribbean/settlements",
"https://sandbox.yembipay.com",
);
url.search = new URLSearchParams({ limit: "20", offset: "0" });
const response = await fetch(url, {
headers: { "X-API-Key": process.env.YEMBIPAY_API_KEY },
signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error("YembiPay " + response.status);Request lifecycle
Routes inject schema and auth dependencies. Services own business rules and tenant checks. Multi-table financial changes use explicit database transactions and durable dispatch boundaries.
01
Send exactly one X-API-Key header. Keys are organization, scope, status, and environment bound.
02
Each route declares the least capability it accepts. Full keys inherit supported lower capabilities.
03
Pydantic and service rules bound strings, money, identifiers, URLs, state transitions, and ownership.
04
Durable records precede external dispatch; final state follows verified external evidence.
Idempotency
For settlement creation, generate one high-entropy key, persist it with the business intent, and reuse it only for retries of the byte-equivalent command.
A new command needs a new key.
Reusing an idempotency key for different amount, recipient, or corridor data must fail.
X-API-Key: yp_live_••••••••
Idempotency-Key: 72cbbef3-1d52-4fb9-a1ce-a9b2a4d2c1f8
Content-Type: application/json
X-Request-ID: client-trace-01842Webhooks
Webhook subscription secrets appear once at creation. Read and list operations never return them. Delivery events include a signature and a bounded retry lifecycle.
Localhost, raw IP, private, link-local, and metadata targets are rejected outside explicit local tests.
Compute and compare HMAC over the exact request bytes before parsing or dispatching business work.
Persist the event ID before acknowledging so retries cannot duplicate downstream effects.
Integration assets
Download the current generated API description and collection, inspect SDK repositories, and check system status before blaming a client retry.