# 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.&#x20;

`The Payment Status Inquiry API` effectively acts as a manual status confirmation mechanism, reflecting the structure of a [payment webhook notification](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway) (PGs).&#x20;

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.

## [Quick Start](#quick-start)

Click the "Test it" button below to interact with the Payment Status-Inquiry API and experience its functionality firsthand.

<table data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><a href="quick-start/test-payment-status-inquiry">Test it</a></td></tr></tbody></table>

## [Automatic Inquiry](#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](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway#available-operations).
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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-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](#setup)

#### [Prerequisites](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway).
2. **Webhook:** The Payment Webhook response, as this is the response format which `Payment Status Inquiry API` returns. More details can be found [here](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-notification).

#### [Recommendations for Using Ottu’s Inquiry API](#recommendations-for-using-ottus-inquiry-api)

If you’ve set up [Webhook Payment Notifications](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-notification) 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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway#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](#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](https://github.com/ottuco/ottu-py?tab=readme-ov-file#ottu-py)
* **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](https://github.com/ottuco/ottu-py?tab=readme-ov-file#django-integration)

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](#authentication)

This API endpoint uses both [API-Key](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/authentication#private-key-api-key) and [Basic Authentication](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/authentication#basic-authentication). No special permissions are required for Basic Authentication.

## [How it Works](#how-it-works)

* #### Payment Status Inquiry for `pending`, `attempted`, `failed`, or `expired` states See [Payment Transaction State](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-tracking/payment-transactions-states).

<br>

<figure><img src="https://content.gitbook.com/content/Tq4lCgHh9X4VXINxI3L9/blobs/7KZ8u3pF01LpOvrBH78s/ideas%20-%20Inquiry%20API%20(%60pending%60,%20%60attempted%60,%20%60failed%60,%20or%20%60expired%60)%20(5).png" alt="" width="375"><figcaption></figcaption></figure>

<br>

**Video Demonstration**

In this tutorial, we will demonstrate how to use the Inquiry API to check the status of a payment transaction that has expired.

{% embed url="<https://drive.google.com/file/d/1ZlCncYPhfkIlwXGy1po9JgSiIQdVF5nF/view?usp=sharing>" %}

* #### Payment Status Inquiry for `paid` or `authorized` states

<figure><img src="https://content.gitbook.com/content/Tq4lCgHh9X4VXINxI3L9/blobs/bb2bR5XGPtvW6ud3pFwF/ideas%20-%20Inquiry%20API%20for%20%60paid%60%20or%20%60authorized%60%20(1).png" alt="" width="375"><figcaption></figcaption></figure>

### [Limitations](#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.

{% hint style="info" %}
These rules are per transaction. Additionally, the endpoint allows a maximum of 30 requests per minute across all transactions
{% endhint %}

To request a status inquiry, you must provide at least one of the following identifiers: \
[session\_id](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#session_id-string-mandatory) or [order\_no](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#order_no-string-optional). For a more detailed technical understanding and the implementation specifics of these operations, please refer to the below Open API block.

## Check Status-Inquiry

> 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\`).

```json
{"openapi":"3.1.1","info":{"title":"Ottu API","version":"1.0.0"},"servers":[{"url":"https://sandbox.ottu.net"}],"security":[{"SSO_BasicAuth":[]},{"basicAuth":[]},{"SSO_JWT_Auth":[]}],"components":{"securitySchemes":{"SSO_BasicAuth":{"type":"http","scheme":"basic"},"basicAuth":{"type":"http","scheme":"basic"},"SSO_JWT_Auth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Inquiry":{"type":"object","description":"This serializer is used to validate the lookup fields for the inquiry operation.","properties":{"order_no":{"type":"string","description":"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.","maxLength":128},"session_id":{"type":"string","description":"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.","maxLength":128},"notify_webhook_url":{"type":"boolean","default":false,"description":"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."},"webhook_url":{"type":"string","format":"uri","description":"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. ","maxLength":200}}},"SchemaWebhook":{"type":"object","properties":{"pg_params":{"allOf":[{"$ref":"#/components/schemas/PGParams"}],"readOnly":true,"description":"The `pg_params` field contains the details received \nfrom the payment gateway callback these details are \nprovided to us by the gateway after a user has completed \na payment transaction additionally, `pg_params` \ncan include information obtained from an inquiry \nrequest made to the payment gateway status check API. \n"},"agreement":{"allOf":[{"$ref":"#/components/schemas/Agreement"}],"readOnly":true,"description":"An established contractual arrangement with the payer, which authorizes you to securely store and subsequently utilize their payment information for specific purposes. This could encompass arrangements like recurring payments for services such as mobile subscriptions, installment-based payments for purchases, arrangements for ad-hoc charges like account top-ups, or for standard industry practices like penalty charges for missed appointments. \n\nNote: If your intention is solely to store payment details for transactions initiated by the payer in the future, then this parameter group should not be used."},"amount":{"type":"string","readOnly":true,"description":"Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges."},"amount_details":{"allOf":[{"$ref":"#/components/schemas/AmountDetails"}],"readOnly":true,"description":"A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee."},"capture_delivery_address":{"type":"boolean","description":"By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active."},"capture_delivery_location":{"type":"boolean","title":"Capture delivery coordinates","description":"By enabling this, you will ask for user's delivery location on a map. "},"card_acceptance_criteria":{"allOf":[{"$ref":"#/components/schemas/CardAcceptanceCriteria"}],"readOnly":true,"description":"This field allows you to define specific rules and conditions that a card must meet to be eligible for payment. These stipulations apply regardless of whether a customer chooses to pay using a saved card or opts to add a new card for the transaction. By leveraging the `card_acceptance_criteria`, you gain the power to fine-tune your payment processing strategy, tailoring acceptance rules to align with your business needs, security standards, and risk management policies.\n\n**Example**: If you run an exclusive service that caters predominantly to premium customers, you might set criteria that only allow transactions from high-tier credit cards like VISA Platinum. This ensures that payments align with the exclusivity and branding of your services. Remember to configure these criteria thoughtfully. Striking the right balance between security, risk mitigation, and user experience is paramount.\n\n**Note**: The `card_acceptance_criteria` field is applicable only for direct payments and not for hosted session payments."},"currency_code":{"type":"string","description":"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.","maxLength":3,"minLength":3},"customer_address_city":{"type":"string","description":"The city of the customer's billing address. This field may be used to send the billing address to the payment gateway.","maxLength":40},"customer_address_country":{"type":"string","description":"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.","maxLength":2,"minLength":2},"customer_address_line1":{"type":"string","title":"Customer address line 1","description":"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_line2":{"type":"string","title":"Customer address line 2","description":"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_birthdate":{"type":["string","null"],"format":"date","description":"The customer's date of birth in ISO format (YYYY-MM-DD)."},"customer_address_postal_code":{"type":"string","description":"The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway.","maxLength":12},"customer_address_state":{"type":"string","description":"The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway.","maxLength":40},"customer_email":{"type":"string","description":"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.","maxLength":128},"customer_first_name":{"type":"string","description":"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.","maxLength":64},"customer_id":{"type":"string","description":"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.","maxLength":64},"customer_last_name":{"type":"string","description":"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.","maxLength":64},"customer_phone":{"type":"string","description":"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.","maxLength":32},"extra":{"description":"The extra information for the payment details, which the merchant has sent it in key value form."},"fee":{"type":"string","description":"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.","readOnly":true},"gateway_account":{"type":"string","readOnly":true,"description":"This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions."},"gateway_name":{"type":"string","readOnly":true,"description":"The name of the payment gateway service being utilized."},"gateway_response":{"type":"object","additionalProperties":{},"description":"This field stores the processed response received from the payment gateway and forwarded to Ottu.","readOnly":true},"initiator":{"allOf":[{"$ref":"#/components/schemas/InitiatorUser"}],"description":"The user who initiated the creation of this payment transaction, if available. This field is optional and may be used to track who created the payment transaction. Note that if the payment transaction was using API Key auth initiator_id can be set to any value that corresponds to an existing ACTIVE user in the system"},"is_sandbox":{"type":"boolean","title":"Is Sandbox?","description":"Indicates whether the operation was performed in a test environment or not."},"message":{"type":"string","readOnly":true,"description":"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_no":{"type":["string","null"],"description":"The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.","maxLength":128},"paid_amount":{"oneOf":[{"type":"number","format":"double"},{"type":"string"}],"description":"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.","readOnly":true},"payment_type":{"enum":["one_off","auto_debit","save_card"],"type":"string","description":"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. \n\nChoose `save_card` if you want to perform a card tokenization operation.\n\nNOTE: If `auto_debit` is selected: \n1. `agreement` and `customer_id` parameters will also be mandatory. \n2. Only PG codes supporting tokenization can be selected. \nAs 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.\n\nNOTE: If `save_card` is selected: \n1. The amount must be zero for the save card operation. \n2. The selected MID(pg_code) must support tokenization to enable the save card operation. \n3. Please note that the save card operation is considered successful without any funds being charged.\n4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.\n5. 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.\n\n* `one_off` - One Off\n* `auto_debit` - Auto Debit\n* `save_card` - Save Card"},"reference_number":{"type":"string","readOnly":true},"refunded_amount":{"type":"number","format":"double","description":"The total refunded amount for the payment transaction."},"remaining_amount":{"type":"number","format":"double","description":"The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement.","readOnly":true},"result":{"enum":["pending","success","failed","canceled","error","cod"],"type":"string","description":"Indicates the outcome of the operation. `success` denotes a successful operation.","readOnly":true},"session_id":{"type":"string","description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","maxLength":128},"settled_amount":{"type":"number","format":"double","description":"The amount that has been paid or authorized in its original currency, excluding any fees.","readOnly":true},"signature":{"type":"string","readOnly":true,"description":"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."},"state":{"type":"string","readOnly":true},"token":{"allOf":[{"$ref":"#/components/schemas/Card"}],"description":"Please note that if card is created via checkout save_card payment type\n\nIt means card is created via successful operation without any funds charged.\n\nFor more details check Checkout API `payment_type` field documentation details"},"transaction_log_id":{"type":["integer","null"],"maximum":2147483647,"minimum":0,"description":"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_utc":{"type":"string","format":"date-time","readOnly":true,"description":"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."},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/ChildPayment"},"description":"A list of dictionaries is generated, each containing a concise summary of each child payment transaction that has been created."},"voided_amount":{"type":"number","format":"double","description":"The total voided amount for the payment transaction."}},"required":["agreement","amount","amount_details","card_acceptance_criteria","currency_code","customer_address_country","fee","gateway_account","gateway_name","gateway_response","message","paid_amount","pg_params","reference_number","remaining_amount","result","settled_amount","signature","state","timestamp_utc"]},"PGParams":{"type":"object","description":"Serializer for PaymentTransaction with dynamically generated fields.","properties":{"auth_code":{},"card_type":{},"card_holder":{},"cardholder_email":{},"card_expiry_month":{},"card_expiry_year":{},"full_card_expiry":{},"card_number":{},"card_issuer":{},"ref":{},"result":{},"track_id":{},"post_date":{},"transaction_id":{},"payment_id":{},"pg_message":{},"receipt_no":{},"transaction_no":{},"decision":{},"card_expiry":{},"card_details":{},"dcc_payer_amount":{},"dcc_payer_currency":{},"dcc_payer_exchange_rate":{},"rrn":{}}},"Agreement":{"type":"object","description":"Serializer to hold the recurring data information.\nThis is required for being able to create recurring payments and the PGs\nrequire this information.","properties":{"id":{"type":"string","description":"A unique identifier for the agreement established with the payer. This ID links to the specific terms and conditions the payer has authorized for processing their stored card details. Use cases include: \n1. Recurring Payments: Periodic debits, e.g., gym memberships. \n2. Installment Payments: Multiple charges for a single purchase over time. \n3. Unscheduled: Future payments as required, e.g., account top-ups. \n4. Industry Practice: Standard business practices related to an original payment, e.g., hotel charges after checkout.","maxLength":128},"amount_variability":{"enum":["fixed","variable"],"type":"string","description":"Indicates if all payments within the agreement use the same amount or if the amount differs between the payments.\n\n* `fixed` - Fixed\n* `variable` - Variable"},"start_date":{"type":"string","format":"date","description":"Date on which the agreement with the payer to process payments starts."},"expiry_date":{"type":"string","format":"date","description":"Date on which your agreement with the payer to process payments expires."},"max_amount_per_cycle":{"type":"string","format":"decimal","description":"The maximum amount for a single payment in the series as agreed with the payer."},"cycle_interval_days":{"type":"integer","maximum":366,"minimum":1,"description":"The minimum number of days between payments agreed with the payer."},"total_cycles":{"type":"integer","maximum":999,"minimum":1,"description":"The number of merchant-initiated payments within the recurring payment agreement."},"frequency":{"enum":["irregular","daily","weekly","semi_monthly","monthly","quarterly","semi_annually","yearly","other"],"type":"string","description":"The frequency of the payments within the series as agreed with the payer.\n\n* `irregular` - Irregular\n* `daily` - Daily\n* `weekly` - Weekly\n* `semi_monthly` - Semi Monthly\n* `monthly` - Monthly\n* `quarterly` - Quarterly\n* `semi_annually` - Semi Annually\n* `yearly` - Yearly\n* `other` - Other"},"type":{"enum":["event_based","installment","recurring","unscheduled","other"],"type":"string","default":"recurring","description":"The type of commercial agreement that the payer has with the merchant.\n\n *Note*: For `unscheduled` agreements, the allowed values should be configured as follows: \n\n `id` - Accepts any value. \n\n `frequency`. \n\n `type`.\n\n This configuration ensures that only specific values are permitted for each field when the `type` is `Unscheduled`.\n\n *Note*: For `recurring` agreements, the following fields are mandatory as follows: \n\n `amount_variability` \n\n `cycle_interval_days` \n\n `expiry_date` \n\n ` `requency` \n\n `id` \n\n  `total_cycles` \n\n This configuration ensures that the required values are mandatory for each field when the `type` is `Recurring`.\n\n* `event_based` - Event Based\n* `installment` - Installment\n* `recurring` - Recurring\n* `unscheduled` - Unscheduled\n* `other` - Other"},"seller":{"allOf":[{"$ref":"#/components/schemas/AgreementSeller"}],"description":"Details about the retailer, if the agreement is for installment payments."}}},"AgreementSeller":{"type":"object","properties":{"name":{"type":"string","description":"The retailer's trading name.","maxLength":128},"short_name":{"type":"string","description":"Abbreviation of the retailer's trading name, suitable for payer's statement display.","maxLength":64},"category_code":{"type":"string","description":"A 4-digit code classifying the retailer's business by the type of goods or services it offers.","maxLength":64}}},"AmountDetails":{"type":"object","properties":{"currency_code":{"type":"string","readOnly":true},"amount":{"type":"string","description":"Represents the total amount of the payment transaction, which includes the cost of the purchased items or services but excludes any additional fees or charges","maxLength":120},"total":{"type":"string","readOnly":true,"description":"Denotes the comprehensive total of the payment transaction, incorporating both the principal amount and any associated fees."},"fee":{"type":"string","readOnly":true,"description":"The `Fee` indicates the sum disbursed by the customer in their chosen currency for the payment. Note, this currency could vary from the currency used for the transaction."},"exchange_rate":{"type":"string","description":"The conversion rate used for currency conversion during payment. This value reflects the rate locally calculated."}},"required":["currency_code","fee","total"]},"CardAcceptanceCriteria":{"type":"object","properties":{"min_expiry_time":{"type":"integer","maximum":365,"minimum":1,"description":"Specifies the minimum required validity period, in days, for a card to be eligible for payment. If set to 30 days, for example, cards set to expire within the next month would be declined. This ensures short-lived cards nearing their expiration date are filtered out, reducing chances of payment failures. When implementing, balance your operational needs with customer convenience. Setting it too stringent might increase payment declines, while a lenient approach could risk future payment failures.\n\nAdditionally, it defaults to 30 days when the `payment_type` is `auto_debit`. If any other payment type is selected, no default value is set."}}},"InitiatorUser":{"type":"object","properties":{"id":{"type":"integer","readOnly":true},"first_name":{"type":"string","maxLength":32},"last_name":{"type":"string","maxLength":32},"username":{"type":"string","description":"Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.","pattern":"^[\\w.@+-]+$","maxLength":150},"email":{"type":"string","format":"email","title":"Email address","maxLength":254},"phone":{"type":"string","title":"Phone number","maxLength":128}},"required":["email","id","username"]},"Card":{"type":"object","description":"Represents token details, only if the user pays with a tokenized card, Ottu will include the token details in the response.","properties":{"brand":{"type":["string","null"],"description":"The card brand (e.g., Visa, Mastercard) associated with the card. Display this information for customer reference.","maxLength":32},"customer_id":{"type":"string","description":"The unique identifier for the customer who owns the card","maxLength":36},"cvv_required":{"type":"boolean","description":"Specifies if the card requires the submission of a CVV for transactions. A card without CVV requirement can be used for auto-debit or recurring payments."},"expiry_month":{"type":"string","description":"The card's expiration month. Provide this information for transaction processing and validation.","maxLength":2},"expiry_year":{"type":"string","description":"The card's expiration year. Provide this information for transaction processing and validation.","maxLength":2},"is_expired":{"type":"boolean","description":"A boolean field indicating whether the card has expired. Use this information to determine if the card is valid for transactions and to notify the customer if necessary."},"is_preferred":{"type":"boolean","readOnly":true,"description":" Indicates if the card is the customer's preferred payment option. Order cards with this attribute set to true at the top of the list for easy access."},"name_on_card":{"type":["string","null"],"description":"The cardholder's name as it appears on the card. Display this information for customer verification.","maxLength":64},"number":{"type":["string","null"],"description":"The masked card number to be displayed, ensuring customer privacy and security while providing essential information.","maxLength":19},"pg_code":{"type":"string","description":"The `pg_code` associated with the card's creation."},"pg_name":{"enum":["knet","cybersource","csuc","checkoutcom","migs","dapi","deema","doku","burgan","paypal","mpgs","kpay","enet","omannet","benefit","benefit_pay","blank","cbk","fss","myfatoorah","ngenius","ifg","ccavenues","payu_india","cod","amazon_pay","ottu_pg","bookeey","upg","bambora","hyperpay","qpay","smart_pay","sohar","nbo","tabby","tamara","hesabe","rajhi","stc_pay","stcbahrain","urpay","beyon_money","upayments","tap","fawry","fiserv","payon","paymob","moyasar","abapayway","skipcash","taly"],"type":"string","description":"The payment `gateway` associated with the user's card.\n\n* `knet` - Knet\n* `cybersource` - CyberSource\n* `csuc` - Cybersource Unified Checkout\n* `checkoutcom` - checkout.com\n* `migs` - MiGS\n* `dapi` - Dapi\n* `deema` - Deema\n* `doku` - Doku\n* `burgan` - Burgan\n* `paypal` - PayPal\n* `mpgs` - MPGS\n* `kpay` - KPay\n* `enet` - Enet\n* `omannet` - OmanNet\n* `benefit` - Benefit\n* `benefit_pay` - BenefitPay\n* `blank` - Blank\n* `cbk` - CBK\n* `fss` - FSS\n* `myfatoorah` - MyFatoorah\n* `ngenius` - N-Genius\n* `ifg` - IATA Financial Gateway\n* `ccavenues` - Ccavenues\n* `payu_india` - PayU India\n* `cod` - Cash\n* `amazon_pay` - Amazon Pay\n* `ottu_pg` - Ottu PG\n* `bookeey` - Bookeey\n* `upg` - UPG\n* `bambora` - Bambora\n* `hyperpay` - HyperPay\n* `qpay` - Qpay\n* `smart_pay` - SmartPay\n* `sohar` - SoharInternational\n* `nbo` - NBO\n* `tabby` - Tabby\n* `tamara` - Tamara\n* `hesabe` - Hesabe\n* `rajhi` - Alrajhi Bank\n* `stc_pay` - STC Pay\n* `stcbahrain` - STC Bahrain\n* `urpay` - URPay\n* `beyon_money` - BeyonMoney\n* `upayments` - UPayments\n* `tap` - Tap Payments\n* `fawry` - Fawry\n* `fiserv` - Fiserv\n* `payon` - PayOn\n* `paymob` - PayMob\n* `moyasar` - Moyasar\n* `abapayway` - ABA PayWay\n* `skipcash` - Skip Cash\n* `taly` - Taly"},"token":{"type":"string","description":"The unique token associated with the card, required for tokenized card payments. Use this value to securely process transactions.","maxLength":50},"agreements":{"description":"List of agreements associated with this card."}},"required":["agreements","brand","customer_id","cvv_required","expiry_month","expiry_year","is_expired","is_preferred","name_on_card","number","pg_code","pg_name","token"]},"ChildPayment":{"type":"object","properties":{"amount":{"type":"string","readOnly":true},"currency_code":{"type":"string","description":"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.","maxLength":3,"minLength":3},"order_no":{"type":["string","null"],"description":"The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.","maxLength":128},"session_id":{"type":"string","description":"A unique identifier for each payment transaction, used to maintain the session state during the payment process.","maxLength":128},"state":{"enum":["paid","refunded","refund_queued","refund_rejected","voided"],"type":"string","description":"The current state of the payment transaction, it helps to understand the progress of the payment.\n\n* `paid` - paid\n* `refunded` - refunded\n* `refund_queued` - refund_queued\n* `refund_rejected` - refund_rejected\n* `voided` - voided"}},"required":["amount","currency_code"]},"InquiryErrors":{"oneOf":[{"$ref":"#/components/schemas/FieldErrors"},{"$ref":"#/components/schemas/InquiryFailure"}]},"FieldErrors":{"type":"object","properties":{"field_name":{"type":"array","items":{"type":"string","default":"This field is required."}}}},"InquiryFailure":{"type":"object","properties":{"detail":{"type":"string","description":"Provides a message associated with the operation, suitable for displaying to the end user."},"result":{"enum":["failed"],"type":"string","description":"* `failed` - Failed"}},"required":["detail","result"]},"GenericErrorMessage":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}}},"paths":{"/b/pbl/v2/inquiry/":{"post":{"operationId":"inquiry","description":"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. \n\nThe 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. \n\nThis endpoint uses a throttling mechanism to prevent potential system abuse. Throttling rules are as follows:\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\n4. **Subsequent Requests:** If the number of requests for the same transaction exceeds three within the overall time frame, any further requests are denied.\n\nNote: The above rules are applied per transaction. Additionally, the endpoint allows a maximum of 30 requests per minute across all transactions.\n\nIt's mandatory to provide at least one of the identifiers (`session_id` or `order_no`).","summary":"Check Status-Inquiry","parameters":[{"in":"header","name":"Authorization","schema":{"type":"string","default":"Api-Key vSUmxsXx.V81oYvOWFMcIywaOu57Utx6VSCmG11lo"},"description":"Private API key to be provided in the format `Api-Key <key>`.","required":true}],"tags":["Payment Operations"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inquiry"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Inquiry"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Inquiry"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaWebhook"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryErrors"}}},"description":""},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""},"415":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericErrorMessage"}}},"description":""}}}}}}
```

## [Guide](#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](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-notification).
* **Use the Correct Identifier:** Provide either the [session\_id](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#session_id-string-mandatory) or [order\_no](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#order_no-string-optional) 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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway). Please refer to the [Operation Available](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway#available-operations) table to explore the processes supported by each Payment Gateway.

## [FAQ](#faq)

#### :digit\_one: [**What are the prerequisites to using the Payment Status Inquiry API?**](#what-are-the-prerequisites-to-using-the-payment-status-inquiry-api)

You should have at least one [Payment Gateway](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway) that supports status checks, and you should be familiar with the [Payment Webhook response](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/developer/webhooks/payment-notification). Refer to [available operation](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway#available-operations) table to explore the PGs support status checks.

#### :digit\_two: [**What types of authentication does the Payment Status Inquiry API support?**](#what-types-of-authentication-does-the-payment-status-inquiry-api-support)

The API endpoint supports both [API-Key](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/authentication#private-key-api-key) and [Basic Authentication](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/authentication#basic-authentication).

#### :digit\_three: [**Which payment transaction states can I inquire using the Payment Status Inquiry API?**](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-tracking/payment-transactions-states).

#### :digit\_four: [**How does Ottu handle inquiries for transactions with outdated states?**](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway) to update the transaction state.

#### :digit\_five: [**What if multiple payment options were attempted using different Payment Gateways?**](#what-if-multiple-payment-options-were-attempted-using-different-payment-gateways)

If multiple payment options were `attempted` using different [Payment Gateways](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/user-guide/payment-gateway), all Gateways that support payment status checks will be called, ensuring that you receive the most updated status for the payment.

#### :digit\_six: [**Are there any limitations or throttling rules for the Payment Status Inquiry API?**](#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](#limitations) section for detailed information.

#### :digit\_seven: [**What information do I need to provide to request a status inquiry?**](#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](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#session_id-string-mandatory) or [order\_no](https://sandbox-doc.gitbook.io/ottu-team-sandbox-doc/checkout-api#order_no-string-optional) for the transaction.

From [authentication](#authentication) to [best practices](#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](#faq) is available. The team appreciates the trust placed in their payment management solutions and looks forward to supporting seamless and efficient transactions.
