Payment Status-Inquiry

The Payment Status Inquiry API endpoint is a part of Ottu's Check Status API designed to check the status of a specific payment transaction. This is especially useful when your system may not have received notifications about changes to a transaction's status.

The Payment Status Inquiry API effectively acts as a manual status confirmation mechanism, reflecting the structure of a payment webhook notification. The endpoint can be triggered for payment transactions in the following states: pending, attempted, failed, or expired. If the transaction state is already paid or authorized, the status is returned immediately without needing to re-confirm with third-party Payment Gateways (PGs).

However, if the transaction state is not up-to-date and is still listed in one of the aforementioned states, Ottu will trigger an API call to the PG to update the transaction state. In cases where multiple payment options were attempted using different PGs, all PGs that support payment status checks will be called, ensuring that you receive the most updated status for the payment.

Automatic Inquiry

The payment process can be intricate, and numerous unforeseen events might disrupt the smooth flow of a transaction. Ottu’s Automatic Inquiry feature is designed to mitigate such issues and ensure that merchants receive accurate payment statuses. This feature is enabled by default for every payment gateway and one that’s non-negotiable.

How It Works

1. Scheduled Inquiry Job: For every Payment Gateway (PG) that supports the inquiry feature, Ottu schedules an automatic inquiry job. This job is set to trigger after a predetermined period, which is defined based on the session expiration time of each specific PG. The exact timing for each PG can be found here.

2. Purpose: The objective behind this automatic inquiry job is to account for scenarios where a payer might abruptly close their browser tab, face internet connectivity issues, or in instances where the PG fails to notify Ottu (or Ottu misses the notification due to temporary downtime). The job ensures that Ottu reconciles with the PG and updates the payment status accordingly.

3. Execution: This job calls the PG’s inquiry API three times to guarantee accurate reconciliation. However, if a successful response (indicating a payment success) is received during any of these calls, the subsequent calls are halted.

4. Exceptions: Certain aggregator integrations, such as MyFatoorah, may encounter scenarios where the payment status remains pending even after redirection to Ottu. This issue typically arises from the absence of a definitive response from the actual payment gateway (PG). To address this, Ottu does not trigger a webhook notification to the merchant for the pending status. Instead, Ottu proactively schedules an additional inquiry job to clarify the payment status. Ottu will continue monitoring the payment status without sending webhook notifications to the merchant. Once the inquiry job reaches a definitive end state—either paid or failed, Ottu will then send a webhook notification to the merchant. This approach ensures that merchants receive accurate and final payment statuses, enhancing the reliability of the transaction process.

Setup

Prerequisites

For this API to work efficiently, here are a few things you need to be familiar with:

1. Payment Gateway: At least one Payment Gateway that supports status checks should be available. You can find more about Payment Gateways here.

2. Webhook: The Payment Webhook response, as this is the response format which Payment Status Inquiry API returns. More details can be found here.

Recommendations for Using Ottu’s Inquiry API

If you’ve set up Webhook Payment Notifications with Ottu, it’s best to rely on the responses from these notifications after Ottu’s automatic inquiry. Only consider integrating the inquiry API if you haven’t enabled webhook notifications.

• Timing is Crucial: Scheduling your inquiry calls with precision is essential. Otherwise, you might miss the most recent transaction status.

• Example with MPGS: The PG MPGS typically requires an inquiry after approximately 11 minutes. If you initiate your inquiry call prematurely, say around the 8-minute mark, you might miss out on the most recent status. It’s advisable to add a margin of 2-3 minutes, making your inquiry after about 13-14 minutes for MPGS.

• Differing PG Times: With PGs like KNET, the inquiry is scheduled for 8 minutes post-payment initiation. When you integrate with multiple PGs through Ottu, it’s beneficial to identify the PG with the longest inquiry time, add a 2-3 minute margin to it, and use this extended timeframe as a standard for all inquiries.

In essence, the Automatic Inquiry feature is Ottu’s commitment to providing consistent and updated payment statuses, ensuring you never miss a payment update. Always remember to time your inquiries wisely and stay in sync with Ottu’s schedule for the best results.

Boost Your Integration

Enhance your integration with the Payment Status Inquiry API using Ottu official SDK packages, specifically designed for payment status management. This SDK streamlines the process of querying and managing payment statuses, ensuring efficient and simplified interactions.

Available Package:

• Python SDK: Provides an object-oriented approach to querying payment statuses, allowing you to check the status of transactions with ease. This SDK abstracts the complexities of API calls, focusing on efficiency and user-friendliness. Learn more

• Django SDK: Facilitates the integration of payment methods into Django projects by providing Django-specific tools and utilities that streamline payment processing. Find out more

Although these packages provide significant advantages in speed and convenience, it is crucial to understand the foundational concepts and structures detailed in the documentation. This knowledge ensures that you can integrate and utilize the packages effectively, maintaining robustness and sustainability in their application.

Authentication

This API endpoint uses both API-Key and Basic Authentication. No special permissions are required for Basic Authentication.

How it Works

1. Payment Status Inquiry for pending, attempted, failed, or expired states See Payment Transaction State.

   
2. Payment Status Inquiry for paid or authorized states

Limitations

The Payment Status Inquiry API implements a throttling mechanism to prevent potential system abuse. Here are the rules:

1. Initial Grace Period (10 minutes): If the Inquiry API is called within 10 minutes from when the payment transaction is created, the request will be throttled.

2. First Request: After the initial grace period, the first request is permitted. Any subsequent requests for the same transaction within the next 30 minutes will be throttled.

3. Second Request After the first 30-minute throttle period, a second request is allowed. Further requests for the same transaction within another 30 minutes will be throttled.

4. Subsequent Requests: If the number of requests for the same transaction exceeds three within a single day, any further requests will be denied.

These rules are per transaction. Additionally, the endpoint allows a maximum of 30 requests per minute across all transactions

To request a status inquiry, you must provide at least one of the following identifiers: session_id or order_no. For a more detailed technical understanding and the implementation specifics of these operations, please refer to the Open API schema in the API Schema Reference.

API Schema References

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:

1. 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.

2. 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.

3. 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.

4. 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

SSO_BasicAuthbasicAuthSSO_JWT_Auth

AuthorizationstringRequired

Header parameters

AuthorizationstringRequired

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

Default: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

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

order_nostring · 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 · 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.

notify_webhook_urlbooleanOptional

A boolean value indicating whether or not to notify the webhook_url about the status of the payment. When set to true, the system will send a notification to the webhook_url specified during the creation of the payment via the Checkout API. This is particularly useful for merchants who have an acknowledgement mechanism in place and want to trigger it to confirm the payment/order on their system.

Default: false

webhook_urlstring · uri · max: 200Optional

URL where the payment result will be sent via a POST request after the customer has completed the payment session. The payment result will be included in the request body.

Responses

200Success

application/json

amountstringRead-onlyRequired

Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges.

capture_delivery_addressbooleanOptional

By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active.

capture_delivery_locationbooleanOptional

By enabling this, you will ask for user's delivery location on a map.

currency_codestring · min: 3 · max: 3Required

The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.

customer_address_citystring · max: 40Optional

The city of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_countrystring · min: 2 · max: 2Required

The country of the customer's billing address, formatted as a two-letter ISO country code (e.g., 'US' for United States, 'CA' for Canada). This field may be used to send the billing address to the payment gateway.

customer_address_line1stringOptional

The first line of the customer's billing street address. This field may be used to send the billing address to the payment gateway.

customer_address_line2stringOptional

The second line of the customer's billing street address, if available. This field may be used to provide additional address information, such as an apartment or suite number.

customer_birthdatestring · nullableOptional

The customer's date of birth in ISO format (YYYY-MM-DD).

customer_address_postal_codestring · max: 12Optional

The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_statestring · max: 40Optional

The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_emailstring · max: 128Optional

The email address of the customer that is used to send payment notifications and receipts, and can be used for fraud prevention. This field is mandatory and is always sent to the payment gateway. It may also be included in the invoice, receipt, email, and displayed on the payment page.

customer_first_namestring · max: 64Optional

The first name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_idstring · max: 64Optional

The customer ID is a unique identifier for the customer within the merchant's system. It is also used as a merchant identifier for the customer and plays a critical role in tokenization. All the customer's cards will be associated with this ID.

customer_last_namestring · max: 64Optional

The last name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_phonestring · max: 32Optional

Customer phone number associated with the payment. This might be sent to the payment gateway and depending on the gateway, it may trigger a click to pay process on the payment page. The phone number will also be included in the invoice, receipt, email, and displayed on the payment page.

extraanyOptional

The extra information for the payment details, which the merchant has sent it in key value form.

feestringRead-onlyRequired

The fee denotes the sum the customer pays in their chosen payment currency. This may vary from the transaction's designated currency. The fee is computed once to maintain precision and uniformity throughout the payment procedure.

gateway_accountstringRead-onlyRequired

This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions.

gateway_namestringRead-onlyRequired

The name of the payment gateway service being utilized.

is_sandboxbooleanOptional

Indicates whether the operation was performed in a test environment or not.

messagestringRead-onlyRequired

This represents the message, either transmitted by the Payment Gateway (PG) or established by Ottu, that provides a detailed illustration of the payment's current status.

order_nostring · max: 128 · nullableOptional

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

paid_amountone ofRead-onlyRequired

The paid amount encompasses fees or captured amounts from authorized transactions. This total is derived from the specified 'amount' field, converting foreign currencies to the default as necessary. This might result in minor variations due to fluctuations in exchange rates.

number · doubleOptional

or

stringOptional

payment_typestring · enumOptional

Type of payment. Choose one_off for payments that occur only once without future commitments. Choose auto_debit for payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

1. agreement and customer_id parameters will also be mandatory.
2. Only PG codes supporting tokenization can be selected. As a side effect, the card used for the payment will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.
5. When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.

• one_off - One Off
• auto_debit - Auto Debit
• save_card - Save Card

Possible values:

reference_numberstringRead-onlyRequired

refunded_amountnumber · doubleOptional

The total refunded amount for the payment transaction.

remaining_amountnumber · doubleRead-onlyRequired

The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement.

resultstring · enumRead-onlyRequired

Indicates the outcome of the operation. success denotes a successful operation.

Possible values:

session_idstring · max: 128Optional

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_amountnumber · doubleRead-onlyRequired

The amount that has been paid or authorized in its original currency, excluding any fees.

signaturestringRead-onlyRequired

Signature Field: A cryptographic hash used to guarantee data integrity and authenticity during client-server exchanges. This hash ensures that the API payload has not been tampered with, and can only be verified by authorized parties.

statestringRead-onlyRequired

transaction_log_idinteger · max: 2147483647 · nullableOptional

Identifies the transaction log associated with the payment transaction. A transaction log is created for each record that is dispatched during a bulk dispatch process.

timestamp_utcstring · date-timeRead-onlyRequired

This field represents the timestamp at which ottu processed the transaction.While this often corresponds to the payment time,it's important to note that it might not always be the case.Payments can be acknowledged at a later time,so this timestamp might not align precisely with the actual payment time.

voided_amountnumber · doubleOptional

The total voided amount for the payment transaction.

400Error

application/json

401Error

application/json

403Error

application/json

404Error

application/json

415Error

application/json

post

/b/pbl/v2/inquiry/

HTTPcURLJavaScriptPython

POST /b/pbl/v2/inquiry/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "order_no": "text",
  "session_id": "text",
  "notify_webhook_url": false,
  "webhook_url": "https://example.com"
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "pg_params": {
    "auth_code": null,
    "card_type": null,
    "card_holder": null,
    "cardholder_email": null,
    "card_expiry_month": null,
    "card_expiry_year": null,
    "full_card_expiry": null,
    "card_number": null,
    "card_issuer": null,
    "ref": null,
    "result": null,
    "track_id": null,
    "post_date": null,
    "transaction_id": null,
    "payment_id": null,
    "pg_message": null,
    "receipt_no": null,
    "transaction_no": null,
    "decision": null,
    "card_expiry": null,
    "card_details": null,
    "dcc_payer_amount": null,
    "dcc_payer_currency": null,
    "dcc_payer_exchange_rate": null,
    "rrn": null
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-04",
    "expiry_date": "2026-03-04",
    "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"
    }
  },
  "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_birthdate": null,
  "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": "[email protected]",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": null,
  "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": null,
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": null,
    "number": null,
    "pg_code": "text",
    "pg_name": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": null,
  "timestamp_utc": "2026-03-04T17:47:33.876Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": null,
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Guide

This guide is your go-to resource for effectively using the Status Inquiry API in your online payment management system. It's all about timing and integration, ensuring you never miss the latest transaction updates. Whether you're new to the system or looking to fine-tune your payment processes, this guide has you covered.

Webhook Payment Notifications: If you've configured Webhook Payment Notifications with Ottu, it is advisable to rely on the responses from these notifications following Ottu's automatic inquiry process. Only consider integrating the inquiry API if you have not enabled webhook notifications.

Timing is Crucial: Timing plays a crucial role in using the Status Inquiry API effectively. It's essential to schedule your inquiry calls with precision to ensure you receive the most recent transaction status. Failure to do so may result in missing important updates.

Example with MPGS: For example, the Payment Gateway (PG) MPGS typically requires an inquiry approximately 11 minutes after payment initiation. Initiating your inquiry call prematurely, around the 8-minute mark, may lead to missing the most recent status. To avoid this, we recommend adding a margin of 2-3 minutes, making your inquiry after about 13-14 minutes for MPGS.

Differing PG Times: Different Payment Gateways (PGs) may have varying inquiry times. For PGs like KNET, the inquiry is scheduled for 8 minutes post-payment initiation. When integrating with multiple PGs through Ottu, it's beneficial to identify the PG with the longest inquiry time, add a 2-3 minute margin to it, and use this extended timeframe as a standard for all inquiries.

In essence, the Automatic Inquiry feature is Ottu’s commitment to providing consistent and updated payment statuses, ensuring you never miss a payment update. Always remember to time your inquiries wisely and stay in sync with Ottu’s schedule for the best results.

Best Practices

• Stay within the Request Limits: Be mindful of our API’s built-in throttling mechanisms to ensure smooth operation.

• Understand the Webhook Response: Knowing how to interpret the Payment Webhook response is crucial for accurate results. Check Payment Notification.

• Use the Correct Identifier: Provide either the session_id or order_no when requesting a status inquiry.

• Consider the Transaction State: The states paid and authorized will return the status immediately, while others will trigger a status check with the Payment Gateway. Please refer to the Operation Available table to explore the processes supported by each Payment Gateway.

FAQ

1️ What are the prerequisites to using the Payment Status Inquiry API?

You should have at least one Payment Gateway that supports status checks, and you should be familiar with the Payment Webhook response. Refer to available operation table to explore the PGs support status checks.

2️ What types of authentication does the Payment Status Inquiry API support?

The API endpoint supports both API-Key and Basic Authentication.

3️ Which payment transaction states can I inquire using the Payment Status Inquiry API?

You can trigger the endpoint for payment transactions in the pending, attempted, failed, or expired states. If the transaction state is paid or authorized, the status is returned immediately. See Payment Transactions State.

4️ How does Ottu handle inquiries for transactions with outdated states?

If a transaction state is not up-to-date and is still listed as pending, attempted, failed, or expired, Ottu will trigger an API call to the Payment Gateway to update the transaction state.

5️ What if multiple payment options were attempted using different Payment Gateways?

If multiple payment options were attempted using different Payment Gateways, all Gateways that support payment status checks will be called, ensuring that you receive the most updated status for the payment.

6️ Are there any limitations or throttling rules for the Payment Status Inquiry API?

Yes, the Payment Status Inquiry API has a throttling mechanism. It includes an initial grace period, a limit on the number of requests within certain time intervals, and a limit on the total requests in a single day. Please refer to the Limitations section for detailed information.

7️ What information do I need to provide to request a status inquiry?

To request a status inquiry, you need to provide either the session_id or order_no for the transaction.

From authentication to best practices, this document has equipped users with the knowledge needed to maximize the potential of the Status Inquiry API in their online payment systems. Whether users are new to the platform or experienced, this tool can streamline payment processes and keep them informed about transaction statuses. If there are any questions or a need for further guidance, the FAQ section is available. The team appreciates the trust placed in their payment management solutions and looks forward to supporting seamless and efficient transactions.