Skip to main content

Payment Status Query

The Payment Status Query API lets you manually check the status of a payment transaction. It acts as a confirmation mechanism when your system hasn't received a webhook notification about a status change — due to network issues, temporary downtime, or third-party service failures.

The response mirrors the structure of a payment webhook payload. For payment transactions in pending, attempted, failed, or expired states, Ottu queries the payment gateway for the latest status. For paid or authorized states, the current status is returned immediately without re-confirming with the gateway.

When multiple payment methods were attempted using different gateways, all gateways supporting status checks are queried — ensuring you receive the most up-to-date status.

Boost Your Integration

Ottu offers SDKs and tools to speed up your integration. See Getting Started for all available options.

When to Use​

  • Webhook not received — network issues, temporary downtime, or third-party failures prevented delivery.
  • Manual verification — a customer reports the payment was completed but your system shows pending or failed.
  • Reconciliation — periodic checks to ensure your records match the gateway's state.
  • Fallback for automatic inquiry — when Ottu's built-in automatic inquiry hasn't resolved the status yet.
warning

If you've configured webhook notifications, rely on those as the primary mechanism. Use the Payment Status Query API only when webhooks haven't arrived or you need manual confirmation.

Setup​

  • Payment gateway — at least one gateway that supports status checks must be configured. See Payment Methods for available gateways and their capabilities.
  • Webhook familiarity — the Payment Status Query API response matches the payment webhook payload. Understand the response format before integrating.

Gateway Inquiry Timing​

Each payment gateway has a different session expiration time. Schedule your PSQ calls after the gateway's inquiry window closes — calling too early means the gateway may not have finalized the status yet.

3min
Enet
6min
Amazon Pay
8min
AlRajhi BankBenefitBenefitPayCheckout.comDeemaFSSFawryKNETMyFatoorahN-GeniusOmanNetSTC PayTamara
10min
HesabeNBO
11min
MPGS
12min
ABA PayWay
15min
PayU India
16min
SmartPaySohar InternationalTabby
20min
QPayTap Payments
28min
BeyonMoney
30min
Skip CashTaly
31min
HyperPayPayOn
60min
Doku
⚠️
Add 2-3 minutes margin to these values when scheduling your PSQ call. If you integrate with multiple gateways, use the longest time + margin as your standard. Calling too early means the gateway may not have finalized the status yet.

No inquiry support — handled by Ottu automatically

BamboraCCAvenuePayPalUPG

Guide​

Workflow​

  1. Merchant sends an inquiry request with session_id or order_no.
  2. Ottu checks the payment transaction state:
    • If pending, attempted, failed, or expired → Ottu queries the payment gateway for the latest status.
    • If paid or authorized → Ottu returns the current status immediately (no gateway call needed).
  3. Response mirrors the webhook payload — same structure, same fields.

Automatic Inquiry​

Ottu includes a built-in automatic inquiry feature that runs without any merchant action. It's enabled by default for every payment gateway.

How it works:

  1. Scheduled inquiry job — for every gateway that supports inquiry, Ottu schedules an automatic check after the gateway's session expiration time. The timing varies per gateway.
  2. Retries — the job queries the gateway 3 times to ensure accurate reconciliation. If a successful response is received during any call, the remaining retries are skipped.
  3. Webhook delivery — once the automatic inquiry resolves the status, Ottu sends a webhook notification to the merchant.

Aggregator handling (e.g., MyFatoorah):

Some aggregator integrations may return a pending status even after the customer is redirected back. This happens when the underlying gateway hasn't provided a definitive response yet. In these cases:

  • Ottu does not send a webhook for the pending status.
  • Instead, Ottu schedules additional inquiry jobs to monitor the status.
  • Once a definitive state is reached (paid or failed), Ottu sends the webhook notification.

This ensures merchants only receive webhooks with final, actionable payment statuses.

Step-by-Step​

1. Send an inquiry request​

Provide at least one identifier — session_id or order_no:

curl -X POST "https://sandbox.ottu.net/b/pbl/v2/inquiry/" \
  -H "Authorization: Api-Key your_private_api_key" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "your_session_id"}'

2. Handle the response​

The response matches the webhook payload structure. Check the state field for the current payment transaction status:

  • paid / authorized / cod → payment succeeded
  • pending / attempted → payment still in progress
  • failed / expired / canceled → payment did not complete

3. Optionally trigger a webhook​

Include "notify_webhook_url": true in the request to have Ottu send a webhook notification with the inquiry result to your configured webhook_url:

{
  "session_id": "your_session_id",
  "notify_webhook_url": true
}

You can also specify an alternate webhook_url to receive the result at a different endpoint.

Throttling Rules​

The Payment Status Query API implements throttling to prevent system abuse. Rules are per payment transaction:

  1. Initial grace period (10 minutes) — requests within 10 minutes of payment transaction creation are throttled.
  2. First request — after the grace period, the first request is allowed. Subsequent requests for the same payment transaction within the next 30 minutes are throttled.
  3. Second request — after the first 30-minute throttle period, a second request is allowed. Further requests within another 30 minutes are throttled.
  4. Subsequent requests — if requests for the same payment transaction exceed 3 in a single day, further requests are denied.
info

Additionally, the endpoint allows a maximum of 30 requests per minute across all payment transactions (global rate limit).

API Reference​

Check Status-Inquiry​

Check Status-Inquiry

POST 
/b/pbl/v2/inquiry/

Check the status of a payment transaction. For pending, attempted, failed, or expired states, Ottu queries the payment gateway for the latest status. For paid or authorized states, returns the current status immediately.

Requires at least one identifier: session_id or order_no.

Request​

Responses​

Last updated on

Best Practices​

Stay within request limits​

Respect the throttling rules. Schedule inquiry calls based on gateway timing, not on arbitrary intervals.

Understand the webhook response​

The Payment Status Query API response mirrors the payment webhook payload. Familiarize yourself with the response structure before integrating.

Use the correct identifier​

Provide session_id (preferred — always present) or order_no. At least one is required.

Consider the payment transaction state​

paid and authorized payment transactions return status immediately. For other states, Ottu queries the gateway — factor in the gateway's session expiration time when scheduling your inquiry.

FAQ​

What's Next?​

  • Payment Events — Webhook notifications triggered by payment state changes
  • Payment States — Complete state machine reference
  • Operations — Refund, capture, void, cancel payment transactions
  • Checkout API — Create payment transactions to inquire about
Last updated on