Skip to main content

Deliveries, wallet funding and the sandbox

Reeds Engineering
Reeds Engineering
Developer platform

How the delivery and money endpoints behave in v1, in Test and Live mode.

Deliveries​

  • POST /deliveries books from a quote (quote_id): 201 with status scheduled, the tracking code and the wallet debited at once. A quote books one delivery: using it again is 409 QUOTE_ALREADY_USED with error.delivery_id, and an expired quote (or one whose address you deleted) is 409 QUOTE_EXPIRED.
  • If the wallet doesn't cover it you get 402 INSUFFICIENT_BALANCE (402 CREDIT_LIMIT_REACHED for an invoice account): nothing is created and the quote stays unused. Fund the wallet and retry with the same Idempotency-Key.
  • Leave out quote_id to create a draft from two saved addresses in any status. A draft never gets a 402: it waits with CONFIRM_PICKUP_ADDRESS, CONFIRM_DROPOFF_ADDRESS, AWAITING_PRICE, BOOK or FUND_WALLET. With auto_book: true it books itself once it is priced and the price is within max_total; above max_total it waits with BOOK. max_total never limits POST /deliveries/{id}/book.
  • pickup_instructions and dropoff_instructions (up to 500 characters) are for that delivery only; the rider sees them before the address's own notes. PATCH /deliveries/{id} changes them, reference and metadata (null clears a field): the pickup instructions until the parcel is collected, the drop-off instructions until it is delivered, and never on a cancelled delivery (409 ACTION_NOT_ALLOWED). Sending an address or the package is 422.
  • POST /deliveries/{id}/book (402 when short, 409 ACTION_NOT_ALLOWED when not priced or already booked, 503 while live booking is paused), POST /deliveries/{id}/ready (409 on a delivered or cancelled delivery) and POST /deliveries/{id}/cancel (reason becomes cancellation.note; 409 CANCEL_NOT_ALLOWED once the rider has set off) answer.
  • A delivery booked as it is created sends delivery.created (already scheduled) then delivery.booked. A fresh draft's events is empty: the timeline lists statuses the delivery moved to.

Idempotency​

Requests that fail with 401, 402, 403, 409 or 429 release the Idempotency-Key, so retry with it once the cause is fixed. 400, 404 and 422 answers are saved and replayed with Idempotent-Replayed: true, like a success. A key you also used on the dashboard is 422 IDEMPOTENCY_KEY_REUSED.

Money​

  • POST /wallet/fund returns { amount, currency, payment_url, reference }. Your credentials act for the account: any live credentials can start a top-up, and Paystack sends the receipt to the account Owner. A test token, or an invoice account, gets 409 ACTION_NOT_ALLOWED.
  • POST /sandbox/wallet/fund credits the test wallet at once and books drafts waiting on FUND_WALLET. An Idempotency-Key is optional there: a retry with the same key never credits twice. Invoice accounts get 409.
  • POST /sandbox/deliveries/{id}/advance moves a sandbox delivery and fires the real webhooks. Both sandbox endpoints answer 403 TEST_MODE_ONLY to live credentials.

Nothing is removed or renamed. Clients that ignore unknown fields need no change.