Order lifecycle

Every order moves through the same statuses, whichever flow created it.

flowchart LR
    A[AwaitingCheckout] -->|customer completes checkout| C[Confirmed]
    A -->|decision declined| D[Declined]
    A -->|2 hours pass| E[Expired]
    A -->|you cancel| X[Cancelled]
    C -->|fulfil part| PF[PartiallyFulfilled]
    C -->|fulfil all| FF[FullyFulfilled]
    PF -->|fulfil the rest| FF
    C -->|you cancel| V[Voided]
    PF -->|refund| PR[PartiallyReversed]
    FF -->|refund| PR
    PR -->|refund the rest| R[FullyReversed]
    FF -->|refund all paid| R
    PF -->|refund all paid| R
    FF -->|customer pays every instalment| S[Settled]

Order reads, order lists and checkout-link responses return statuses as names (for example "Confirmed"). The capture, fulfil, refund and cancel responses return status as a number; see Status numbers. The server SDKs always give you the name.

Statuses

An action that isn't allowed in the order's current status returns 400 INVALID_STATUS, and the message names the current status.

Act on an order

These calls need the orders:write scope and take the Qasimha order id (installmentId from session creation, or id from a checkout link). Send an Idempotency-Key on each one so a retry can't refund or fulfil twice.

Capture

An order that completes today's hosted checkout is already Confirmed, so you don't need to capture it. Capture applies only to New and Approved orders from the earlier checkout; on a confirmed order it returns 400 INVALID_STATUS. No body is needed.

Response data: { "id": "...", "status": 5, "confirmedAt": "2026-10-20T09:30:00Z" } (5 is Confirmed).

Fulfil

Record a shipment when you ship. You can fulfil in several parts.

{ "shippedAmount": 600.00, "shippingCompany": "Aramex", "trackingNumber": "ARX123", "trackingUrl": "https://track.example/ARX123" }

Rules:

• Outstanding = totalAmount − fulfilledAmount.
• shippedAmount must be greater than 0 and not more than the outstanding amount. 0, a negative amount, or more than outstanding returns 400 INVALID_SHIPPED_AMOUNT. Don't send 0 to mean "nothing shipped yet"; just don't call fulfil.
• Amounts are rounded to two decimals before the check.
• When fulfilledAmount reaches totalAmount, the order is FullyFulfilled; before that it is PartiallyFulfilled.
• You can't fulfil after a refund has been recorded.

Response data: { "id": "...", "status": 7, "fulfilledAmount": 600.00 } (7 is PartiallyFulfilled, 6 is FullyFulfilled).

Refund

Refund a fulfilled order, fully or in parts.

{ "amount": 300.00, "reason": "Customer return" }

Rules:

• Only PartiallyFulfilled, FullyFulfilled and PartiallyReversed orders can be refunded. Fulfil the order first. To cancel a confirmed order that hasn't shipped, use cancel instead.
• The most you can refund is what the customer has actually paid so far, minus refunds already made. Read it from refundableAmount on the order. The unpaid balance is never refunded; it is cancelled. (For an order without an instalment schedule, the limit is the fulfilled amount minus refunds.)
• When total refunds reach what the customer has paid, the order becomes FullyReversed and every unpaid instalment is cancelled, so the customer owes nothing more. Below that, the order is PartiallyReversed and the remaining instalments stay due.
• 0 or a negative amount returns 400 INVALID_AMOUNT. More than refundableAmount returns 400 AMOUNT_EXCEEDED, and the message states the available amount.
• Settled orders (fully repaid) can't be refunded through the API. Contact [email protected].

Example: a 1200.00 order on 4 instalments where the customer has paid the first 300.00 has refundableAmount 300.00. Refunding 300.00 makes it FullyReversed and cancels the other three instalments.

Response data: { "id": "...", "status": 9, "refundedAmount": 100.00 }, where refundedAmount is the running total (9 is PartiallyReversed, 8 is FullyReversed).

Cancel

No body is needed. What cancel does depends on the status:

• AwaitingCheckout: the open checkout is withdrawn and the order becomes Cancelled. The customer can no longer complete it. (POST /api/v1/merchant/checkout-links/{id}/cancel does the same for link and QR orders.)
• Confirmed: the whole order is voided and becomes Voided. Every unpaid instalment is cancelled, and voidedAmount records what was released. There is no partial void.
• Any other status: 400 INVALID_STATUS. Once anything is fulfilled, use refund.

Response data: { "id": "...", "status": 10 } (10 is Voided, 13 is Cancelled).

Examples

BASE=https://api-uat.qasimha.com/api/v1/merchant/orders
ORDER=9a2e6c4b-1111-4c2d-8a1f-000000000001

# Fulfil part of the order
curl -X POST $BASE/$ORDER/fulfill -H "X-Api-Key: $QASIMHA_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{ "shippedAmount": 600.00, "shippingCompany": "Aramex", "trackingNumber": "ARX123" }'

# Fulfil the rest
curl -X POST $BASE/$ORDER/fulfill -H "X-Api-Key: $QASIMHA_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{}'

# Refund part of what the customer paid
curl -X POST $BASE/$ORDER/refund -H "X-Api-Key: $QASIMHA_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{ "amount": 100.00, "reason": "Damaged cable returned" }'

# Cancel a confirmed order that hasn't shipped
curl -X POST $BASE/$ORDER/cancel -H "X-Api-Key: $QASIMHA_API_KEY" -H "Idempotency-Key: $(uuidgen)"

await qasimha.orders.fulfill(orderId, { shippedAmount: 600.00, shippingCompany: 'Aramex', trackingNumber: 'ARX123' });
await qasimha.orders.fulfill(orderId, {});                       // the rest

const order = await qasimha.orders.get(orderId);
if ((order.refundableAmount ?? 0) >= 100.00) {
  await qasimha.orders.refund(orderId, { amount: 100.00, reason: 'Damaged cable returned' });
}

await qasimha.orders.cancel(otherOrderId);                       // Confirmed → Voided, AwaitingCheckout → Cancelled

Status numbers

The action responses above return status as one of these numbers. Map it to the name, or read the order again.

Read an order

These calls need the orders:read scope (orders:write also works). An order that belongs to another merchant returns 404 NOT_FOUND.

List filters

search matches your order reference, or the customer's name, email or phone. status takes any status name above (case-insensitive) or one of these groups:

Any other value returns 400 INVALID_STATUS. A page below 1 or a negative pageSize returns 400 VALIDATION_ERROR.

Order detail

The order detail includes items, the instalment schedule (installments), the customer (id, name, email, phone), fulfillments, refunds (reversals), voids, and the full statusHistory (fromStatus, toStatus, trigger, createdAt). It also has paymentUrl, checkoutExpiresAt, confirmedAt, fulfilledAt, voidedAt, reversedAt, settledAt, contractNumber and ejarContractNumber.

Each instalment has sequence, dueDate, amount, principal, profit, paidAmount, paidAt and a status: Scheduled, Paid, Late, Reversed (cancelled by a void or full refund) or Waived.

Amount fields

In list rows (GET /merchant/orders), capturedAmount is the fulfilled amount and refundedAmount the refunded amount. Read the order detail for the payment figures.

Settlements

GET /api/v1/merchant/settlements lists settlement batches due to you, net of fees, newest first, with page and pageSize. GET /api/v1/merchant/settlements/overview shows the headline figures, including the notPaidYet balance. The net amount is total minus refunds and voids, less the MDR fee and 15% VAT on that fee. Both calls need the settlements:read scope.

Troubleshooting

Related