Developers

A hardened API contract with no hidden dashboard authority.

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

Make one owned, authenticated read.

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.

List settlements
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'

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.

01

Authenticate

Send exactly one X-API-Key header. Keys are organization, scope, status, and environment bound.

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.

Idempotent command headers
X-API-Key: yp_live_••••••••
Idempotency-Key: 72cbbef3-1d52-4fb9-a1ce-a9b2a4d2c1f8
Content-Type: application/json
X-Request-ID: client-trace-01842

Webhooks

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

Machine-readable contracts and maintained examples.

Download the current generated API description and collection, inspect SDK repositories, and check system status before blaming a client retry.