Payment Status-Inquiry

Introduction

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.

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.

Installation

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.

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

Requesting a Status Inquiry

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

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

POST/b/pbl/v2/inquiry/

Authorization

SSO BasicAuthbasicAuth

Body

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

order_nostring

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

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_urlboolean

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_urlstring (uri)

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.

Response

200400401403404415

Body

application/json

amount*string

The amount of a transaction represents the specific monetary value of the payment transaction.

amount_details*all of

A comprehensive set of amount details includes: Currency Code, Amount, Total, Fee.

capture_delivery_addressboolean

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

capture_delivery_locationCapture delivery coordinates

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

currency_code*string

The currency in which the transaction is denominated. However, it does not guarantee that the payment must be made in this currency, as there can be currency conversions or exchanges resulting in a different currency being charged.

customer_address_citystring

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

customer_address_country*string

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_line1Customer address line 1

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_line2Customer address line 2

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_address_postal_codestring

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

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

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

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

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

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

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.

extraobject

A dictionary containing additional arguments to be passed through the transaction processing steps.

fee*string

The fee is the amount paid by the customer in the currency they made the payment. It may differ from the currency of the transaction. The fee is calculated only once to ensure accuracy and consistency in the payment process.

gateway_account*string

The payment gateway code, which is utilized to proceed the payment.

gateway_name*string

The payment gateway name.

gateway_response*object

The response from the payment gateway.

is_sandboxIs Sandbox?

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

message*string

Message sent by PG or set by Ottu to illustrate the status of the payment.

token*all of

order_nonullable string

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

paid_amount*one of

The paid amount includes fees or captured amounts for authorized transactions. It's calculated based on the provided amount field, converting foreign currency to default if needed, allowing for possible discrepancies due to exchange rate changes.

number (double)string

reference_number*string

An auto-generated internal identifier for this payment transaction. While this field may be used for tracking and reporting purposes, it is recommended to use the session_id field instead, as it provides the same functionality and more.

refunded_amount*number (double)

The total refunded amount for the payment transaction.

remaining_amount*number (double)

The remaining amount to be paid, in conjunction with the editable amount, represents the outstanding balance of a transaction that needs to be settled.

result*enum

• pending - Pending
• success - Success
• failed - Failed
• canceled - Canceled
• error - Error
• cod - Cash on Delivery

pendingsuccessfailedcancelederrorcod

session_idstring

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

settled_amount*number (double)

Paid or authorized amount in the original currency without fee

state*string

The current state of the payment transaction, it helps to understand the progress of the payment.

transaction_log_idnullable integer (int64)

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.

transactions*array of ChildPayment (object)

Transactions are associated instances created during specific operations on the parent payment transaction, like refunds.

voided_amount*number (double)

The total voided amount for the payment transaction.

initiator*all of

Transaction initiator details.

Request

JavaScriptCurl

const response = await fetch('/b/pbl/v2/inquiry/', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text"
  },
  "capture_delivery_address": false,
  "capture_delivery_location": false,
  "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",
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "is_sandbox": false,
  "message": "text",
  "token": {
    "brand": "text",
    "auto_debit_enabled": "text",
    "customer_id": "text",
    "cvv_required": false,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": false,
    "is_preferred": false,
    "name_on_card": "text",
    "number": "text",
    "pg_code": "text",
    "token": "text"
  },
  "order_no": "text",
  "paid_amount": 0,
  "reference_number": "text",
  "refunded_amount": 0,
  "remaining_amount": 0,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 0,
  "state": "text",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": "text",
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 0,
  "initiator": {
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "[e-mail]",
    "phone": "text"
  }
}

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 Payment Gateway Features Summary 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.

We hope you found this guide to the Payment Status Inquiry API useful. As you proceed with your implementation, remember the following key points:

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