Skip to main content

Operations

The Operations API lets you perform subsequent actions on existing payment transactions — refund a completed payment, cancel an unpaid link, capture an authorized amount, or void an authorization. Ottu provides a unified API: you send the same payload structure regardless of the payment gateway, and Ottu handles the gateway-specific communication.

Ottu supports six operations. Three are internal (handled within Ottu's system): cancel, expire, and delete. Three are external (synchronized with the payment gateway): refund, capture, and void. When an external operation succeeds, Ottu creates a child transaction linked to the original, recording the new state, amount, and gateway response.

warning

Operations via the Operations API do not work with foreign currencies. If the customer paid using currency exchange (e.g., MID is KWD but customer paid in USD), external operations will fail. The payment currency must match the MID currency.

Boost Your Integration

Ottu offers SDKs and tools to speed up your integration. See Getting Started for all available options.

When to Use​

  • Refunding a completed payment — return funds to the customer after a paid or captured transaction.
  • Capturing an authorized payment — settle funds for transactions in the authorized state (full or partial).
  • Voiding an authorization — cancel an authorized transaction before capture, so the customer is not charged.
  • Cancelling an unpaid payment link — stop a payment that's created, pending, cod, or attempted.
  • Expiring stale sessions — automatically invalidate incomplete payment transactions.
  • Deleting transactions — remove obsolete or test transactions (soft delete for paid, hard delete for others).

Setup​

Before performing any operation, you need an existing payment transaction with a session_id or order_no:

  1. Via the Checkout API — create a payment transaction programmatically.
  2. Via the Ottu Dashboard — create a transaction manually.

Store the session_id securely — it's required for all operation requests. Prefer session_id over order_no as it's always present in the response.

Guide​

Workflow​

  1. Merchant sends an operation request with session_id, operation type, and optional amount.
  2. For internal operations (cancel, expire, delete) — Ottu updates the transaction state directly.
  3. For external operations (refund, capture, void) — Ottu communicates with the payment gateway.
  4. On success — a child transaction is created, linked to the original, recording the result.

Step-by-Step​

All operations use the same endpoint: POST /b/pbl/v2/operation/

  1. Send the operation request with the operation type, session_id, and optional amount:

    {
      "operation": "refund",
      "session_id": "2a956e4c9294c2c0e9253c21b1a592ceb4018c68",
      "amount": "20.00"
    }

  2. Use the Tracking-Key header (recommended for external operations) to prevent duplicate operations and retrieve status:

    Tracking-Key: "unique-tracking-id"

    If you send a subsequent request with the same Tracking-Key and session_id, Ottu returns the latest status of the original operation instead of creating a new one. The key is stored in the child transaction data on success.

  3. Handle the response — on success, the response includes the child transaction details (amount, state, gateway response). On failure, an error message indicates why the operation was rejected.

tip

Use the extra object field for additional gateway-specific parameters. For example, the Instant Fund Gratification (IFG) feature for instant refunds is configured via extra.

Use Cases​

Internal Operations​

Cancel — Halts a payment in progress. Applicable to transactions in created, pending, cod, or attempted state. The merchant stops a payment that hasn't reached completion.

Expire — Invalidates an incomplete payment transaction. Targets created, pending, or attempted states. Transitions the transaction to expired, from which it cannot be resumed.

Delete — Removes transactions no longer needed:

  • paid, authorized, or cod/cash → soft delete (removed from reports, recoverable from Deleted Transactions)
  • All other states → hard delete (permanent removal)

External Operations​

Capture — Settles authorized funds. Only applicable to authorized transactions. Supports full or partial capture (cannot exceed the authorized amount). Creates a child transaction on success.

Refund — Returns funds to the customer. Applicable to paid or captured transactions. For authorized transactions, a capture must be completed first. Supports full or partial refund. Ottu offers an approval feature for refunds, enabling a checker role to approve or reject requests.

Void — Cancels an authorization before capture. Only applicable to authorized transactions. The customer is not charged.

info

Not all payment gateways support all external operations. If a gateway doesn't support an operation, Ottu rejects the API call with an error message. See supported operations by gateway.

API Reference​

Select the operation to see its example payload and the full interactive API schema:

Example Request
{
  "operation": "refund",
  "session_id": "your_session_id",
  "amount": "20.00"
}

Operations​

Operations

POST 
/b/pbl/v2/operation/

Perform operations on existing payment transactions. Supports refund, capture, void, cancel, expire, and delete.

Use session_id or order_no to identify the target transaction. For refund and capture, specify amount (defaults to full/remaining amount). For void, always applies to the full amount.

Include Tracking-Key header on external operations to prevent duplicates and retrieve status.

Request​

Responses​

Last updated on

FAQ​

What's Next?​

  • Webhooks — Receive notifications when operations complete
  • Checkout API — Create payment sessions to operate on
  • Payment States — Understand how operations change transaction states
Last updated on