01
Authenticate
Send exactly one X-API-Key header. Keys are organization, scope, status, and environment bound.
Developer Truth & Proof
Build against what YembiPay can prove.
Explore the reviewed partner contract, exact capability states, deterministic failure scenarios, and evidence boundaries before requesting production access.
Developer journey
Discover, test, diagnose, then prove readiness.
Each surface answers what is available, where it runs, what evidence exists, and which dependency still blocks the next state.
No live corridor is represented here.
Local sandbox, gated, and unavailable are product states. Adapter code, API reachability, or an unanchored certificate does not make a payout rail live.
Quick start
Make one local, owned, authenticated read.
The examples target a developer-run API at 127.0.0.1. Use a key issued to one organization and environment; a hosted sandbox is not claimed here.
Keep API keys server-side.
Never ship partner keys in public browser JavaScript, mobile bundles, URLs, analytics, or logs.
curl --request GET \
--url http://127.0.0.1:8000/v1/caribbean/settlements?limit=20 \
--header 'Accept: application/json' \
--header "X-API-Key: $YEMBIPAY_API_KEY"import os
import requests
response = requests.get(
"http://127.0.0.1:8000/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",
"http://127.0.0.1:8000",
);
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
One command, one owner, one bounded result.
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.
02
Authorize
Each route declares the least capability it accepts. Full keys inherit supported lower capabilities.
03
Validate
Pydantic and service rules bound strings, money, identifiers, URLs, state transitions, and ownership.
04
Commit and observe
Durable records precede external dispatch; final state follows verified external evidence.
Idempotency
Retry the command, not the side effect.
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: $YEMBIPAY_API_KEY
Idempotency-Key: 72cbbef3-1d52-4fb9-a1ce-a9b2a4d2c1f8
Content-Type: application/json
X-Request-ID: client-trace-01842Webhooks
Verify before processing; acknowledge after durable intake.
Webhook subscription secrets appear once at creation. Read and list operations never return them. Delivery events include a signature and a bounded retry lifecycle.
HTTPS only
Localhost, raw IP, private, link-local, and metadata targets are rejected outside explicit local tests.
Signature first
Compute and compare HMAC over the exact request bytes before parsing or dispatching business work.
Durable dedupe
Persist the event ID before acknowledging so retries cannot duplicate downstream effects.
Integration assets
Curated contracts and maintained examples.
Download the reviewed partner description and collection, review SDK publication posture, and check system reachability before diagnosing a client retry.
- Partner OpenAPI JSONAdministrative and internal operations are excluded.
- Partner Postman collectionReviewed contract examples; remote value movement remains gated.
- SDK packagesPython and Node sources are locally tested; public source and signed package publication remain gated.Gated
- System statusAPI reachability only; not corridor or provider readiness.
