Skip to main content
This guide provides a complete integration path for developers who want a production-ready implementation without navigating all sections in depth.

​
Prerequisites

Before starting your integration, ensure you have:

Merchant Onboarding

Complete KYB/AML verification and contractual approval

Sandbox Access

Access to test environment for integration and testing

Credentials

Client-Id, RSA key pair (private key stored securely), and keyVersion

Technical Setup

HTTPS-enabled backend and ability to expose webhook endpoint

​
Choose Your Payment Flow

Select the payment flow that best matches your use case:
Use CaseRecommended FlowDescription
In-store POS with scannerRetail PayMerchant scans user’s dynamic QR code
Printed or on-screen QRQR Order PayUser scans merchant’s QR code
Mobile app checkoutLink PayApp-to-app payment redirection
Web checkout (desktop)QR Order Pay or Link PayBased on user device
You may implement more than one flow using the same credentials.

​
Integration Overview

All Rebell payment integrations follow the same seven core steps:
1

Implement Request Signing

Set up RSA-SHA256 authentication for secure API communication
2

Create Payment

Call the appropriate payment API based on your chosen flow
3

Handle Immediate Response

Process SUCCESS, PROCESSING, or FAIL status from initial API call
4

Implement Webhook Endpoint

Receive asynchronous payment notifications from Rebell
5

Handle Final Payment Result

Update order status based on webhook notifications
6

Implement Inquiry API

Use as fallback when webhooks are delayed or for active confirmation
7

Production Deployment

Switch credentials and endpoints from sandbox to production

​
Step-by-Step Implementation

​
Step 1: Implement Authentication & Signing

# Generate private key
openssl genrsa -out private_key.pem 2048

# Extract public key
openssl rsa -in private_key.pem -pubout -out public_key.pem
Upload your public key through the Rebell merchant portal to receive your keyVersion identifier.
Store your private key in a Hardware Security Module (HSM) or cloud KMS. Never embed keys in mobile apps or frontend code.
Sign every request with these components:
  • HTTP method
  • Request path
  • Client-Id
  • Request-Time (ISO 8601 UTC)
  • Request body (JSON)
See Authentication & Environments for detailed implementation.
Validate your signing implementation using sandbox APIs before proceeding with payment integration.

​
Step 2: Create a Payment

Choose the appropriate endpoint based on your payment flow: 
POST /v1/payments/retailPay
Required for all flows:
  • Generate a unique paymentRequestId (used for idempotency)
  • Store mapping between paymentRequestId and your internal order ID
  • Log requests and responses (excluding sensitive data)

​
Step 3: Handle Immediate Response

Evaluate the result object returned by the API:
Payment is final
  • Payment is authorized and complete
  • You can immediately print receipt and deliver goods
  • No need to wait for webhook (though you’ll still receive one)
Do not assume the initial API response is the final payment state. Always implement webhooks.

​
Step 4: Implement Webhooks (Required)

Webhooks are the source of truth for final payment results. Implementation requirements:
  • Expose an HTTPS POST endpoint
  • Verify RSA signature on every webhook
  • Make handler idempotent (handle duplicate notifications)
  • Update order state only once per payment
  • Return 200 OK to acknowledge receipt
Example Webhook Handler
app.post('/webhooks/rebell', async (req, res) => {
  // 1. Verify signature
  const isValid = verifyWebhookSignature(req.headers, req.body);
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Extract payment info
  const { paymentId, paymentRequestId, result } = req.body;

  // 3. Update order (idempotent)
  await updateOrderStatus(paymentRequestId, result.resultStatus);

  // 4. Acknowledge receipt
  res.status(200).send('OK');
});

​
Step 5: Use Inquiry API (Fallback)

Use the Inquiry API only when:
  • Initial response is PROCESSING
  • Webhook is delayed
  • POS requires active confirmation
Polling rules:
  • Poll every 3-5 seconds
  • Stop after receiving SUCCESS or FAIL
  • Do not exceed retry limits (max 30 seconds)
Inquiry API
POST /v1/payments/inquiryPayment

​
Step 6: Map Errors Correctly

Error handling checklist:
  • Always check resultStatus first
  • Handle user errors appropriately (rejection, insufficient balance)
  • Do not retry business failures
  • Retry safely only on network or 5xx errors
  • Never reuse a paymentRequestId
See Error Handling & Result Codes for complete error reference.

​
Minimal End-to-End Example

Here’s a complete QR Order Pay flow:
1

Create Order

Merchant backend creates order in your system
2

Call API

Call POST /v1/payments/createQrOrder with signed request
3

Display QR

Render the returned QR code to user
4

User Pays

User scans QR and confirms payment in Rebell SuperApp
5

Receive Webhook

Rebell sends webhook notification with final result
6

Complete Order

Merchant backend marks order as PAID and fulfills
This same structure applies to all payment flows (Retail Pay, QR Order Pay, Link Pay).

​
Testing Checklist

​
Sandbox Testing

Before requesting production access, verify:
  • All APIs tested in sandbox
  • Signing logic validated
  • Webhooks received and signature verified
  • Inquiry API logic tested
  • Idempotency verified (duplicate requests handled correctly)
Test these failure cases:
  • User rejection
  • Insufficient balance
  • Expired QR code
  • Invalid payment code
  • Network timeout
  • Signature validation failure
  • PROCESSING status handling
  • Delayed webhooks
  • Duplicate webhook notifications
  • Concurrent payment requests

​
Go-Live Checklist

Before switching to production:

Credentials

  • Production credentials configured
  • Production public key uploaded
  • Sandbox keys removed from production config

Infrastructure

  • Webhook endpoint switched to production URL
  • HTTPS properly configured
  • Load balancing tested

Monitoring

  • Logging enabled
  • Alerting configured for:
    • Webhook failures
    • Signature errors
    • High PROCESSING rate

Operations

  • Internal runbook prepared
  • Support team trained
  • Rollback plan documented

​
Common Integration Mistakes

Avoid these common pitfalls:
Critical Mistakes:
  • ❌ Treating API response as final payment result
  • ❌ Ignoring or not implementing webhooks
  • ❌ Reusing paymentRequestId for different transactions
  • ❌ Polling Inquiry API too frequently (< 3 seconds)
  • ❌ Exposing private keys to frontend code
  • ❌ Mixing sandbox and production credentials
Best Practices:
  • ✅ Always wait for webhook confirmation
  • ✅ Implement proper signature verification
  • ✅ Use unique paymentRequestId per transaction
  • ✅ Store private keys in HSM/KMS
  • ✅ Test all error scenarios in sandbox
  • ✅ Monitor webhook delivery rates

​
Next Steps

Authentication & Environments

Learn detailed RSA signing and environment configuration

Payment Flows

Explore specific payment methods (Retail Pay, QR Order Pay, Link Pay)

Webhooks

Implement webhook handling and signature verification

Error Handling

Complete reference for error codes and recovery logic

​
Additional Resources

  • Detailed API specs → See individual payment flow sections
  • Advanced authentication → See Authentication Deep Dive
  • UI/UX guidance → See Product Guides
  • Mini App integrations → See Mini App Development