Payments¶

• User payments: /api/orders/payments/
• Check payment status (refresh from provider): POST /api/orders/payments/{id}/check-status/
• Payment credentials (staff): /api/orders/payment-credentials/
• Staff manage payments: /api/orders/staff/payments/
• IntaSend test connection (staff): /api/orders/payments/intasend/test/
• Stripe webhook: POST /api/orders/payments/stripe/webhook/

JWT required.

• Non-staff: Can create and view their own order payments; only IntaSend and Stripe providers are allowed. Cash/other must be created via staff API.
• Staff: Can create and view all payments and credentials; any provider (IntaSend, Stripe, cash, other) is allowed.

GET /api/orders/payments/

Returns payments for the authenticated user's orders (staff: all). Soft-deleted payments are excluded.

Success (200):

[
  {
    "id": 500,
    "order": 123,
    "provider": "intasend",
    "status": "pending",
    "amount": "40.00",
    "currency": "KES",
    "checkout_url": "https://payment.intasend.com/checkout/...",
    "provider_payment_id": "",
    "provider_invoice_id": "08XPG72",
    "provider_state": "PENDING",
    "raw_provider_response": {},
    "created_at": "2026-01-19T10:05:00Z",
    "updated_at": "2026-01-19T10:05:00Z"
  }
]

GET /api/orders/payments/{id}/

Returns a single payment (owner or staff). Use this to read the stored status; it does not call the provider.

POST /api/orders/payments/{id}/check-status/

Returns the payment and a status_check object. The third-party API (IntaSend) is only called when the stored payment status is pending or processing. If the payment is already completed, failed, or cancelled, the API returns the stored status without calling IntaSend or Stripe.

• Pending/processing + IntaSend: Calls IntaSend, updates the payment record, and returns the latest status.
• Already completed/failed/cancelled: No provider call; returns current payment and status.
• Other providers: Returns current stored payment and status (no provider call).

Success (200):

{
  "payment": {
    "id": 500,
    "order": 123,
    "provider": "intasend",
    "status": "completed",
    "amount": "40.00",
    "currency": "KES",
    "checkout_url": "",
    "provider_payment_id": "...",
    "provider_invoice_id": "08XPG72",
    "provider_state": "COMPLETE",
    "raw_provider_response": { ... },
    "created_at": "...",
    "updated_at": "..."
  },
  "status_check": {
    "is_complete": true,
    "status": "completed",
    "provider_state": "COMPLETE",
    "success": true
  }
}

Use status_check.is_complete (or status_check.status === "completed") to know if the payment is complete. If the provider call failed, status_check.success is false and status_check.error may be set.

POST /api/orders/payments/

Required: order (id), provider, method. Amount defaults to order total converted to the requested (or default) currency. You must own the order (or be staff).

IntaSend — payment link

{
  "order": 123,
  "provider": "intasend",
  "method": "link"
}

Optional: phone_number, email (passed to checkout; otherwise from order shipping address). If the order already has a pending IntaSend payment with a checkout_url, that payment is returned (201) and no new payment or link is created.

IntaSend — STK push (M-Pesa)

{
  "order": 123,
  "provider": "intasend",
  "method": "stk",
  "phone_number": "0712345678",
  "email": "john@example.com"
}

• phone_number is required (or from order shipping address).
• Optional: email, narrative.
• The amount sent to M-Pesa is converted to KES using the app currency rates (products Currency table); the stored payment may use another currency for display/fully-paid calculation.

Stripe Checkout

{
  "order": 123,
  "provider": "stripe",
  "method": "checkout"
}

Optional: success_url, cancel_url (override settings).

Cash / Other (manual)

{
  "order": 123,
  "provider": "cash",
  "method": "manual"
}

Success (201): payment object including checkout_url for link/Stripe when applicable.

Common errors (400)

POST /api/orders/payment-credentials/

{
  "provider": "intasend",
  "environment": "sandbox",
  "api_key": "YOUR_PUBLISHABLE_KEY",
  "private_key": "YOUR_SECRET_KEY",
  "is_active": true
}

• IntaSend: api_key = publishable key, private_key = secret key. environment: sandbox or live.
• Stripe: api_key can be blank; set private_key to sk_test_... or sk_live_.... Only one active row per (provider, environment).

PATCH /api/orders/payment-credentials/{id}/

Example (rotate secret): {"private_key": "NEW_SECRET"}

GET /api/orders/staff/payments/

Query: ?include_deleted=true to include soft-deleted payments.

POST /api/orders/staff/payments/

Example (record cash as completed):

{
  "order": 123,
  "provider": "cash",
  "status": "completed",
  "amount": "40.00",
  "currency": "KES"
}

Returns 400 if order is already fully paid.

PATCH /api/orders/staff/payments/{id}/

Example: {"status": "completed", "provider_state": "PAID"}

DELETE /api/orders/staff/payments/{id}/

Soft-deletes the payment (is_deleted=true). Order is_fully_paid is recalculated.

GET /api/orders/payments/intasend/test/

Validates stored IntaSend credentials by calling the provider API. Staff only.

• 200: {"status": "ok", "message": "IntaSend service initialized successfully"}
• 400: Invalid/missing credentials (e.g. "No active IntaSend credentials found")
• 503: IntaSend SDK not installed