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 3-5 seconds, up to a defined timeout window
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 during initial payment creation
Merchant’s internal order ID (recommended for validation)
Response Parameters
API call result details
The current status of the payment:
SUCCESS, FAIL, or PROCESSINGThe payment identifier
Payment amount details (present on SUCCESS)
ISO 8601 timestamp of when payment was completed (present on SUCCESS)
Reason for payment failure (present on FAIL)
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
PAYMENT_NOT_FOUND
PAYMENT_NOT_FOUND
Cause: Inquiry called with invalid or unknown
paymentIdRecovery:- 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:
- Limit polling interval to minimum 3 seconds
- Never exceed 10-15 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 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