PROCESSING states and ensuring order synchronization when webhook delivery is delayed or temporarily unavailable.
When to Use Inquiry
- Use Inquiry When
- Do NOT Use Inquiry
Appropriate use cases:
- Rebell returns
PROCESSINGfor 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
paymentId3
Start Polling (if needed)
If the initial response is
PROCESSING, merchant begins polling Inquiry4
Poll at Intervals
Merchant calls Inquiry every 5 seconds, for up to 1 minute
5
Receive Status
Inquiry returns one of:
SUCCESS, FAIL, or PROCESSING6
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
The payment identifier returned by Rebell (
paymentId, or acquirementId for QR Order / Link Pay)Provide at least one of the two. If both are provided,
paymentId takes priority and paymentRequestId is ignored.Response Parameters
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
Timeout Handling
If Inquiry returnsPROCESSING for too long:
Polling Implementation
Here’s a recommended polling implementation:Polling Logic
Error Scenarios & Recovery
ORDER_NOT_EXIST
ORDER_NOT_EXIST
Cause: Inquiry called with an invalid or unknown
paymentId / paymentRequestId, or the payment was never accepted (then treat it as failed)Recovery:- Check mapping between
paymentRequestIdandpaymentId - Ensure correct environment (sandbox vs production)
- Verify the payment was actually created
PARAM_ILLEGAL
PARAM_ILLEGAL
Cause: Request body invalidRecovery:
- Ensure correct JSON serialization
- Validate presence of
paymentId - Check for malformed request body
ACCESS_DENIED
ACCESS_DENIED
Cause: Credentials do not match payment’s merchantRecovery:
- Verify
Client-Idused in signing - Ensure key rotation did not switch to wrong key
- Confirm the payment belongs to your merchant account
REQUEST_TRAFFIC_EXCEED_LIMIT
REQUEST_TRAFFIC_EXCEED_LIMIT
Cause: Inquiry called too frequentlyRecovery:
- Poll at most once every 5 seconds
- Stop after 1 minute (about 12 attempts) per transaction
- Implement exponential backoff if needed
Security Considerations
UX Recommendations
- POS / Merchant App
- Web Checkout
For point-of-sale and merchant applications:
- Display “Waiting for confirmation…” for
PROCESSING - Auto-refresh UI on
SUCCESSorFAIL - Do not block cashiers with long waits (max 1 minute of polling)
- 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