Guides
Payment status
How the delivery itself is paid for, and how your server learns that a prepaid parcel is paid. Payment is always confirmed server side: no buyer is ever sent to a payment provider's page.
Payment modes
| Mode | Who pays | When the parcel is ready |
|---|---|---|
PAY_ON_PICKUP | The receiver, at collection (Relay) | Straight away |
BUSINESS_INVOICE | Your Business, on its invoice (approved credit needed) | Straight away |
BUSINESS_WALLET | Your Business wallet (needs the wallet.spend scope); an insufficient balance refuses the booking | Straight away |
PREPAID | Your Business, approved by a team member per parcel | After payment is confirmed |
Your own checkout still collects the buyer's payment for the goods and shipping in your shop's own way. These modes are about how Qoene is paid for the delivery.
Prepaid parcels
Create a payment request
For a LIVE prepaid booking, create a payment intent with an empty body. It is an approval request, never a charge: the API key cannot give a phone number, a provider or a charge instruction.
const { intent } = await qoene.paymentIntents.create(shipment.public_id, { idempotencyKey: `order-${order.id}:pay` }); // intent.approval_url: send it to an authorized member of YOUR Business team, never to the buyer.curl -X POST https://api.qoenedelivery.com/v1/shipments/QD-SHP-…/payment-intents \ -H "Authorization: Bearer $QOENE_API_KEY" \ -H "Idempotency-Key: order-1001:pay" \ -H "Content-Type: application/json" --data '{}'$intent = json_decode((string) $client->post("shipments/{$shipmentId}/payment-intents", [ 'headers' => ['Idempotency-Key' => "order-{$orderId}:pay"], 'json' => new \stdClass(), ])->getBody(), true)['data']['intent'];intent = requests.post(f"https://api.qoenedelivery.com/v1/shipments/{shipment_id}/payment-intents", headers={**headers, "Idempotency-Key": f"order-{order_id}:pay"}, json={}, timeout=30).json()["data"]["intent"]A team member approves it
They open the
approval_url, sign in with their own Qoene account, review the amount, enter their Mobile Money number and confirm. Qoene sends the Mobile Money prompt to that phone (Hubtel; Paystack only after a definite Hubtel failure) and confirms the result with the provider on the server.Learn the result on your server
Consume the signed
payment.confirmedwebhook, or pollGET /payment-intents/{intentId}.
| Intent status | Meaning |
|---|---|
REQUIRES_APPROVAL | Waiting for a team member |
PENDING | A Mobile Money prompt is in progress. Not paid. |
RECONCILIATION_REQUIRED | The provider result is uncertain and Qoene is checking it. Not paid. Do not create another payment. |
PAID | Settled. The parcel becomes ready. |
CANCELLED | No longer payable (for example the parcel was cancelled) |
SIMULATED | TEST key: a QD-TPI-… simulation, no money moves |
If approval_url is null in production, the approval page is not configured yet; contact the Delivery team before relying on prepaid API bookings.