Test

Check Status-Inquiry

post

The Check Status-Inquiry endpoint is part of our Payment Gateway API. It's designed for checking the status of a specific payment transaction. This endpoint is particularly useful when notifications about a transaction status change haven't been received. It acts as a manual check for confirming the payment status, mirroring the structure of a payment webhook notification.

The Inquiry operation can only be triggered for payment transactions in the pending, attempted, failed, or expired states. If the transaction state is already paid or authorized, the response is returned immediately without re-confirming it with third-party Payment Gateways (PGs). However, if the system isn't up to date and the transaction state is still in one of the mentioned states, Ottu will trigger an API call to the PG to update the transaction state. If multiple payment options were attempted using different PGs, all PGs supporting payment status checks will be called, ensuring the merchant receives the most updated status of the payment.

This endpoint uses a throttling mechanism to prevent potential system abuse. Throttling rules are as follows:

Initial Grace Period (10 minutes): If the Inquiry endpoint is called within 10 minutes from when the payment transaction is created, the request will be throttled.
First Request: Once the initial grace period has passed, the first request is allowed. Subsequent requests for the same transaction within the next 30 minutes will be throttled.
Second Request: After the end of the first throttle period, a second request is permitted. Further requests for the same transaction within another 30 minutes from the second request are throttled.
Subsequent Requests: If the number of requests for the same transaction exceeds three within the overall time frame, any further requests are denied.

Note: The above rules are applied per transaction. Additionally, the endpoint allows a maximum of 30 requests per minute across all transactions.

It's mandatory to provide at least one of the identifiers (session_id or order_no).

Authorizations

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Example: {"value":"Api-Key 3qlYBXmi.9LlNUa1B7JurCR49tsqcmg785V0k46cV\n","summary":"Example API Key"}

Body

This serializer is used to validate the lookup fields for the inquiry operation.

order_nostring · min: 1 · max: 128Optional

This is an optional identifier used to specify the payment transaction upon which the operation should be performed. You can use either the order_no or session_id field; at least one of these two identifiers must be provided to select the payment transaction that should be actioned.

session_idstring · min: 1 · max: 128Optional

Similar to order_no, session_id is an optional identifier used to specify the payment transaction for the operation. You must provide either order_no or session_id in order to select the appropriate payment transaction.

Responses

200Success

application/json

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

415Error

application/json

post

POST /b/pbl/v2/inquiry/ HTTP/1.1
Host: ksa.ottu.dev
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "order_no": "text",
  "session_id": "text"
}

{
  "pg_params": "text",
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2025-06-27",
    "expiry_date": "2025-06-27",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "recurring",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    },
    "extra_params": {
      "payment_processing_day": 1
    }
  },
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text",
    "exchange_rate": "text"
  },
  "capture_delivery_address": true,
  "capture_delivery_location": true,
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "currency_code": "text",
  "customer_address_city": "text",
  "customer_address_country": "text",
  "customer_address_line1": "text",
  "customer_address_line2": "text",
  "customer_address_postal_code": "text",
  "customer_address_state": "text",
  "customer_email": "text",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "extra": null,
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "gateway_response": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "initiator": {
    "id": 1,
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "name@gmail.com",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": "text",
  "paid_amount": 1,
  "payment_type": "one_off",
  "reference_number": "text",
  "refunded_amount": 1,
  "remaining_amount": 1,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 1,
  "signature": "text",
  "state": "text",
  "token": {
    "brand": "text",
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": "text",
    "number": "text",
    "pg_code": "text",
    "pg": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": 1,
  "timestamp_utc": "2025-06-27T07:14:36.945Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Operations

post

The Payment Operations API provides an interface to manage your payment transactions beyond their initial creation. It allows for several operations including refund, capture, void, and others, directly syncing with the Payment Gateway (PG) for certain actions to ensure consistency across systems.

Two key identifiers, order_no and session_id, can be used interchangeably to specify the payment transaction that the operation should be applied to.

For operations such as refund and capture, you can optionally define the amount to be actioned. If not provided, the API will attempt to perform the operation on the full amount, or the remaining amount if previous operations were conducted. However, note that for void, the operation always applies to the full amount, ignoring the amount value if provided.

This API also allows you to perform certain operations solely at the Ottu system level, providing increased control over your payment transactions.

For every operation, the API provides a clear response containing information about the executed operation, a user-friendly message (detail), and the operation's result (success indicates a successful operation).

Authorizations

Header parameters

AuthorizationstringRequired

Private API key to be provided in the format Api-Key <key>.

Example: {"value":"Api-Key 3qlYBXmi.9LlNUa1B7JurCR49tsqcmg785V0k46cV\n","summary":"Example API Key"}

Tracking-KeystringOptional

The Tracking-Key is a unique identifier provided by the merchant for each operation request.

It is crucial for ensuring the distinctiveness of each operation.

When initiating an operation, this key is stored alongside other transaction details in the database.

It serves as a reference for future status queries.

Enabling the retrieval of the latest status information for a specific operation.

Ensure that each Tracking-Key is distinct to prevent ambiguities in operation tracking and status updates.

Default: Tracking-Key: your_operation_tracking_key

Body

Fetch the payment txn based on the order no or session id also, if the payment txn is not in the accepted state for the input operation, raise an error

order_nostring · min: 1 · max: 128Optional

session_idstring · min: 1 · max: 128Optional

operationstring · enumRequired

delete - delete
cancel - cancel
expire - expire
refund - refund
capture - capture
void - void

Possible values:

amountstring · decimalOptional

This field is optional and used to specify the amount you want to action for refund and capture operations. If not specified, Ottu will attempt to perform the operation on the full amount, or the remaining amount if previous operations have been performed. Keep in mind that void operations always concern the full amount; the amount field is not considered in this case. The amount field can be sent for all operations, but it will only be taken into account for refund and capture operations.

Pattern: ^-?\d{0,13}(?:\.\d{0,3})?$

Responses

200Success

application/json

Responseone of

400Error

application/json

401Error

application/json

403Error

application/json

405Error

application/json

post

POST /b/pbl/v2/operation/ HTTP/1.1
Host: ksa.ottu.dev
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "session_id": "<add `session_id` here>",
  "operation": "expire"
}

{
  "detail": "text",
  "operation": "refund",
  "result": "success"
}

Retrieve a list of payment methods based on filter values.

post

This endpoint allows you to retrieve the available payment methods for a specific plugin, operation and customer. You can specify the desired filter field to get a list of payment methods that are supported and accessible.

Authorizations

Body

pluginstring · min: 1 · max: 50Required

Payment methods will be curated based on their compatibility with the specified plugin.

customer_idstring · min: 1 · max: 64Optional

If provided, customer_payment_methods will be filtered to show only those payment methods that have been successfully used with a paid payment attempts by this customer in the past.

operationall ofOptional

When specified, the available payment methods will be refined based on their compatibility with the indicated operation.

purchase - purchase
authorize - authorize

string · enumOptional

purchase - purchase
authorize - authorize

Possible values:

tokenizablebooleanOptional

If defined, payment methods will be filtered based on supporting tokenization and auto-debit action.

typeall ofOptional

When specified, the available payment methods will be refined based on their type determining if type is sandbox or production.

sandbox - sandbox
production - production

string · enumOptional

sandbox - sandbox
production - production

Possible values:

Responses

200Success

application/json

400Error

application/json

403Error

application/json

post

POST /b/pbl/v2/payment-methods/ HTTP/1.1
Host: ksa.ottu.dev
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "plugin": "text",
  "currencies": [],
  "customer_id": "text",
  "operation": "purchase",
  "tokenizable": true,
  "pg_names": [],
  "type": "sandbox"
}

{
  "customer_payment_methods": [],
  "payment_methods": [
    {
      "code": "text",
      "name": "text",
      "pg": "text",
      "is_sandbox": true,
      "logo": "https://example.com",
      "wallets": [],
      "default_currency": "KWD",
      "accepted_currencies": [],
      "operation": "text",
      "operations": [],
      "is_tokenizable": true
    }
  ]
}

PreviousPlugin Video Trials