One API, six markets, cash included

A cash order in Luanda for 3 450 Kz, with change for 5 000 Kz. The landmark is the address: street text is optional metadata in every home market.

curl https://api.palopgo.com/v1/orders \  -H "Authorization: Bearer sk_sandbox_8f2c…" \  -H "Idempotency-Key: cmd_4f1a9e" \  -H "Content-Type: application/json" \  -d '{    "market": "ao-lad",    "merchant_id": "m-ao-001",    "currency": "AOA",    "amount_minor": 345000,    "fulfilment": "delivery",    "place": {      "bairro": "Maianga",      "landmark": "Condomínio Jardim de Rosas, portão 3",      "phone": "+244923456789"    },    "payment_method": "cash",    "cash": { "change_for_minor": 500000 }  }'

Amounts are integers in the market's minor unit. XOF has no minor unit at all, and Cabo Verde writes its decimal separator as the cifrão.

A cross-market order (a diaspora payer in Lisboa, a delivery in Luanda) carries both amounts, the payer's currency first, with the rate and the date it was taken.

One event per accepted command. The customer-facing phase travels next to the machine state, so you never have to re-implement the matrix.

{  "id": "evt_01JBV8",  "type": "order.state_changed",  "created_at": "2026-10-07T12:41:10+01:00",  "aggregate": { "type": "order", "id": "ord-2026-ao-2211", "version": 7 },  "data": {    "state": "IN_FULFILMENT",    "phase": "ARRIVING",    "courier": { "first_name": "Nelson", "vehicle": "moto" }  }}

Signature

X-PalopGO-Signature: t=…,v1=…

Ordering

Monotonic aggregate_version per order

Retries

1, 5, 25, 120, 360 minutes, then daily for 3 days

Replay

From the deliveries log

The rails are market-scoped. Offering a rail a market does not have answers 422 rather than silently falling back.

Sandbox keys return the seeded stores of all six markets, and the sandbox advances orders through the real machine with only the legal transitions offered.