Skip to main content
The Inquiry Payment API allows your backend to retrieve the current status of a payment previously created using Retail Pay, QR Order Pay, or Link Pay. This API is essential for handling PROCESSING states and ensuring order synchronization when webhook delivery is delayed or temporarily unavailable.
Important LimitationInquiry MUST NOT be used as a substitute for webhooks. Webhooks remain the source of truth; Inquiry is a supplementary polling mechanism.

When to Use Inquiry

Appropriate use cases:
  • Rebell returns PROCESSING for Retail Pay or QR Order
  • User initiated a Link Pay flow but the webhook has not yet arrived
  • Merchant needs to confirm payment status after network interruptions
  • Merchant receives ambiguous or delayed responses
  • Merchant needs status checks during POS timeout handling

Inquiry Flow Overview

1

Create Payment

Merchant creates a payment using Retail Pay, QR Order, or Link Pay
2

Receive Payment ID

Rebell returns a paymentId
3

Start Polling (if needed)

If the initial response is PROCESSING, merchant begins polling Inquiry
4

Poll at Intervals

Merchant calls Inquiry every 3-5 seconds, up to a defined timeout window
5

Receive Status

Inquiry returns one of: SUCCESS, FAIL, or PROCESSING
6

Webhook Delivery

Webhook eventually delivers the final status
7

Update Order

Merchant system updates the order state

Sequence Diagram

API Specification

Endpoint

Request Headers

Include standard authentication headers:

Request Body

paymentId
string
required
The payment identifier returned during initial payment creation
paymentRequestId
string
Merchant’s internal order ID (recommended for validation)
Example Request:

Response Parameters

result
object
required
API call result details
paymentStatus
string
required
The current status of the payment: SUCCESS, FAIL, or PROCESSING
paymentId
string
The payment identifier
paymentAmount
object
Payment amount details (present on SUCCESS)
paymentTime
string
ISO 8601 timestamp of when payment was completed (present on SUCCESS)
failureReason
string
Reason for payment failure (present on FAIL)
Response Examples:

Payment Status Values

Only SUCCESS or FAIL represent final states. PROCESSING means polling should continue until timeout or webhook arrival.

Handling Inquiry Responses

When Inquiry Returns SUCCESS

Payment completed - take action immediately
  • Immediately mark order as PAID
  • Stop polling
  • Do not retry the same payment
  • Wait for webhook to confirm integrity (but not required to proceed)

When Inquiry Returns FAIL

When Inquiry Returns PROCESSING

Payment pending - continue pollingMerchant SHOULD:
  • Continue polling every 3-5 seconds
  • Stop after a maximum of 30-45 seconds
  • Display pending UI to user
  • Wait for webhook if user is still active

Timeout Handling

If Inquiry returns PROCESSING for too long:

Polling Implementation

Here’s a recommended polling implementation:
Polling Logic

Error Scenarios & Recovery

Cause: Inquiry called with invalid or unknown paymentIdRecovery:
  • Check mapping between paymentRequestId and paymentId
  • Ensure correct environment (sandbox vs production)
  • Verify the payment was actually created
Cause: Request body invalidRecovery:
  • Ensure correct JSON serialization
  • Validate presence of paymentId
  • Check for malformed request body
Cause: Credentials do not match payment’s merchantRecovery:
  • Verify Client-Id used in signing
  • Ensure key rotation did not switch to wrong key
  • Confirm the payment belongs to your merchant account
Cause: Inquiry called too frequentlyRecovery:
  • Limit polling interval to minimum 3 seconds
  • Never exceed 10-15 attempts per transaction
  • Implement exponential backoff if needed

Security Considerations

Security Best Practices:
  • ✅ Inquiry does not replace secure webhooks
  • ✅ Use request signing for every Inquiry call
  • ✅ Validate that paymentId belongs to your merchant
  • ✅ Verify paymentRequestId matches expected order
  • ✅ Set strict rate limits on Inquiry endpoints on merchant backend
  • ✅ Log all PROCESSINGSUCCESS / FAIL transitions
  • ✅ Never expose Inquiry endpoints directly to frontend

UX Recommendations

For point-of-sale and merchant applications:
  • Display “Waiting for confirmation…” for PROCESSING
  • Auto-refresh UI on SUCCESS or FAIL
  • Do not block cashiers with long waits (max 30-45 seconds)
  • If timeout occurs, show: “We are verifying your payment. Please wait or try again.”
  • Provide manual “Check Status” button for retries

Complete Integration Example

Full Example

Testing Checklist

Test these scenarios in sandbox before going live:

Next Steps

Webhooks

Implement webhook handlers as the primary notification method

Error Handling

Complete error codes reference and recovery strategies

Retail Pay

Merchant-initiated payments where you scan user QR

Link Pay

App-to-app or browser redirect payment flow