Developers
API referenceBusiness sign in

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

Payment modes
ModeWho paysWhen the parcel is ready
PAY_ON_PICKUPThe receiver, at collection (Relay)Straight away
BUSINESS_INVOICEYour Business, on its invoice (approved credit needed)Straight away
BUSINESS_WALLETYour Business wallet (needs the wallet.spend scope); an insufficient balance refuses the bookingStraight away
PREPAIDYour Business, approved by a team member per parcelAfter 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

  1. 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"]
  2. 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.

  3. Learn the result on your server

    Consume the signed payment.confirmed webhook, or poll GET /payment-intents/{intentId}.

Payment intent statuses
Intent statusMeaning
REQUIRES_APPROVALWaiting for a team member
PENDINGA Mobile Money prompt is in progress. Not paid.
RECONCILIATION_REQUIREDThe provider result is uncertain and Qoene is checking it. Not paid. Do not create another payment.
PAIDSettled. The parcel becomes ready.
CANCELLEDNo longer payable (for example the parcel was cancelled)
SIMULATEDTEST 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.