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.

    Tracking-Key is for operations, not charges

    Direct-charge endpoints (Native Payments — Apple Pay, Google Pay, auto-debit, wallet, cash) use a separate Idempotency-Key header instead. A replayed Tracking-Key returns the original operation's status, whereas a replayed Idempotency-Key on a charge is rejected with 409 Conflict before charging.

  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.

Refund to M-Wallet​

Instead of returning funds through the original payment gateway, you can refund a payment directly to the customer's wallet balance. The customer can then spend that credit at any future Ottu checkout in the same currency. See M-Wallet for the full feature overview.

When to use:

  • The customer's original card has expired or been reissued.
  • You want to issue store credit, loyalty, or goodwill credit without payment-gateway fees.
  • The original gateway doesn't support refunds for that transaction type.

Set destination: "wallet" on the refund operation request. The destination field defaults to "pg" when omitted, preserving the original refund behavior. See the API Reference below for the full request schema and interactive try-it-out.

Use Tracking-Key for idempotency

Wallet credits are immutable — a duplicate refund-to-wallet call creates a second uneditable credit entry (the gateway path fails on duplicates; the wallet path does not). Always include the Tracking-Key header so retries deduplicate. See the Guide above for the full idempotency contract.

Behavior:

  • A wallet account is created automatically if one doesn't exist for the (merchant, customer, currency) combination.
  • The credit is recorded as an immutable ledger entry — corrections require an opposing reversal entry.
  • The original payment session is linked to the credit entry for audit.
  • No PII is stored on the wallet service.
  • Disputes against the original payment after a refund-to-wallet can be resolved manually — contact [email protected] to raise a reversal.

Errors:

HTTPCodeWhen
400account_inactiveWallet account is suspended
400policy_violationRefund amount violates a wallet policy rule
409idempotency_conflictSame Idempotency-Key reused with different payload
422validation_errorSchema validation failed on the refund payload

For the full wallet integration, including the read APIs and SDK behavior, see M-Wallet. For the merchant dashboard workflow, see Refund to M-Wallet (business docs).

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.

Refunds can target the original payment gateway (default) or the customer's wallet by setting destination: "wallet". See Refund to Wallet and the Wallet integration page for full behavior.

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

curl --location 'https://sandbox.ottu.net/b/pbl/v2/operation/' \
--header 'Tracking-Key: Tracking-Key: your_operation_tracking_key' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--data '{
  "order_no": "string",
  "session_id": "string",
  "operation": "delete",
  "amount": "string",
  "extra": {},
  "destination": "pg"
}'

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