Integration Guides

Capture Modes

Understanding authorization and capture flows

NjiaPay supports two capture modes for processing payments: immediate capture and delayed capture (authorization + capture). This guide explains when and how to use each mode.

Capture Mode Overview

Mode	Description	Use Cases
`immediate`	Authorization and capture happen together	Most e-commerce, standard checkouts
`prefer_delay`	Authorization first, capture later	Hotels, rentals, pre-orders, variable amounts

Immediate Capture (Default)

How it works:

Customer authorizes payment
Funds are immediately captured
Payment completes in one step

When to use:

Standard e-commerce purchases
Digital goods/services
Immediate fulfillment
Subscriptions

{
  "capture_mode": "immediate",  // or omit (default)
  "amount": 10000,
  "currency": "ZAR",
  ...
}

Delayed Capture (Authorization + Capture)

How it works:

Customer authorizes payment (funds reserved)
Payment status: authorized
You decide whether to capture or cancel
Capture: Funds transferred, status becomes success
Cancel: Authorization released, status becomes canceled

When to use:

Hotel reservations (charge at checkout)
Car rentals (adjust for damages)
Pre-orders (charge when shipped)
Variable final amounts

{
  "capture_mode": "prefer_delay",
  "amount": 10000,
  "currency": "ZAR",
  ...
}

"prefer_delay" means: use delayed capture if the payment method supports it, otherwise fall back to immediate capture. For example, cards support it, but some digital wallets don't.

Capture Workflow

sequenceDiagram
    participant Customer
    participant YourServer as Your Server
    participant NjiaPay as NjiaPay API

    Customer->>NjiaPay: Authorizes payment
    NjiaPay-->>YourServer: Webhook: status=authorized
    YourServer->>YourServer: Verify can fulfill order
    alt Can fulfill
        YourServer->>NjiaPay: POST /api/v2/intents/{id}/capture
        NjiaPay-->>YourServer: Webhook: status=success
        YourServer->>Customer: Ship product
    else Cannot fulfill
        YourServer->>NjiaPay: POST /api/v2/intents/{id}/cancel-authorization
        NjiaPay-->>YourServer: Webhook: status=canceled
        YourServer->>Customer: Notify cancellation
    end

Capturing Authorized Payment

When ready to capture:

Terminal

GET /api/v2/intents/{intent_id}/capture
Authorization: Bearer YOUR_API_KEY

Response:

{
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success"
}

Canceling Authorization

To release the authorization:

Terminal

GET /api/v2/intents/{intent_id}/cancel-authorization
Authorization: Bearer YOUR_API_KEY

Response:

{
  "intent_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "canceled"
}

Authorization Time Limits

Authorizations expire after a PSP-specific time period:

Cards: Typically 7 days
Other methods: Varies by provider

Always capture before the authorization expires, or you'll need to request a new payment from the customer.

Best Practices

✅ DO

Use delayed capture for variable amounts
Capture before authorization expires
Cancel unused authorizations promptly
Handle both authorized and success webhook events
Document your capture workflow

❌ DON'T

Use delayed capture for immediate-fulfillment products
Let authorizations expire unnecessarily
Capture different amounts without customer consent
Forget to handle authorization expiry

Capture API

Capture endpoint reference

Cancel Authorization API

Cancel endpoint reference

Status Lifecycle

Understand authorized status

Refunds

Process full and partial refunds

Testing

Test your integration with MockPSP in the sandbox environment