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.

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 BasicAuthbasicAuth

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

application/json

objectoptional

application/json

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /b/pbl/v2/inquiry/ HTTP/1.1
Host: 
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 101

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

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

{
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text"
  },
  "capture_delivery_address": true,
  "capture_delivery_location": true,
  "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": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "gateway_response": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "is_sandbox": true,
  "message": "text",
  "token": {
    "brand": "text",
    "auto_debit_enabled": "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",
    "token": "text"
  },
  "order_no": "text",
  "paid_amount": 1,
  "reference_number": "text",
  "refunded_amount": 1,
  "remaining_amount": 1,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 1,
  "state": "text",
  "transaction_log_id": 1,
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1,
  "initiator": {
    "id": 1,
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "[e-mail]",
    "phone": "text"
  }
}

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.