Core Principles
Mini App Payment Capabilities (JSAPI)
The Rebell platform exposes payment-related capabilities to Mini Apps through client-side APIs (JSAPI). These capabilities allow a Mini App to:Initiate Payment
Start a payment flow from the UI
Open Payment UI
Display the Rebell payment confirmation screen
Resume Payment
Continue an existing payment flow
What JSAPI Payment Capabilities Do NOT Do
- Do Not Create Payments
- Do Not Return Final Results
Payments must be created server-side via OpenAPI
Supported Payment Invocation Models
Mini Apps support multiple payment invocation models. The correct model depends on where the payment is created and how the Mini App triggers the payment UI.Model A: Backend-Created Payment, Mini App–Triggered (Recommended)
This is the most common and recommended model. Characteristics:- Backend remains fully in control of payment creation
- Mini App only triggers the user-facing confirmation
- Clear separation of responsibilities
- Best alignment with security and compliance requirements
- Service flows
- Bookings
- Digital goods
- Any user-initiated payment inside a Mini App
Model B: Mini App–Triggered, Backend-Completed (Advanced)
In this model, the Mini App initiates the intent to pay, but the backend completes or resumes the payment asynchronously. Flow overview:1
Trigger Intent
Mini App triggers a payment intent
2
Backend Creates/Resumes
Merchant backend creates or resumes a payment
3
Invoke UI
Mini App invokes the payment UI using a backend-provided reference
4
Standard Flow
Payment completes through standard Rebell flows
5
Webhook Confirmation
Merchant backend receives webhook
- Used to resume existing or external payment flows
- Requires careful backend coordination
- Higher complexity than Model A
End-to-End Payment Flow (Mini App Perspective)
From a Mini App perspective, a complete payment flow looks like this: Key points:- The Mini App never decides the payment outcome
- The backend confirms success or failure
- The UI reflects backend-confirmed state only
Implementation Guide
Step 1: Create Payment on Backend
When user initiates payment in Mini App:Step 2: Invoke Payment UI (JSAPI)
JSAPI Result Codes
| Code | Meaning | Action |
|---|---|---|
9000 | Payment appears successful | Poll backend for confirmation |
6001 | User cancelled | Allow retry |
6002 | Network error | Retry or poll status |
4000 | Order paid or closed | Check backend status |
| Other | Unknown | Poll backend status |
Step 3: Handle Webhook (Backend)
Step 4: Poll for Status (Mini App)
User Authorization & Identity in Payment Flows
Mini Apps operate within a user session provided by the Rebell SuperApp, but they must not assume unrestricted access to user information. Before accessing certain user data or performing sensitive actions, a Mini App must:1
Request Authorization
Explicitly request user authorization via JSAPI
2
Inform User
Clearly inform the user about the requested scope
3
Respect Consent
Respect user consent decisions
| Property | Description |
|---|---|
| Consent-based | User must explicitly approve |
| Scoped | Limited to requested permissions |
| Revocable | User can revoke access |
| No credentials exposed | No sensitive identifiers shared |
- Associate the payment with the correct user
- Personalize the user experience
- Fulfill regulatory or compliance requirements
Mini Apps must always treat user identity information as contextual, not as a source of truth. The merchant backend remains responsible for validating and persisting user-related data.
UX and Error Handling Guidelines
Mini App payment UX must be explicit and transparent.Recommended Practices
Before Payment
Before Payment
- Clearly present payment details before initiation
- Show amount, description, and merchant name
- Provide clear “Pay” call-to-action
During Payment
During Payment
- Inform users when they are entering a payment step
- Display loading/pending states while awaiting confirmation
- Don’t close payment UI prematurely
After Payment
After Payment
- Handle user cancellation gracefully
- Map technical failures to user-friendly messages
- Show confirmation only after backend confirms
Common UI States
- Initiating
- Waiting
- Success
- Failed
Show loading indicator while preparing payment
Error Message Mapping
| Technical Error | User Message |
|---|---|
| Network timeout | ”Connection issue. Please try again.” |
| User cancelled | ”Payment cancelled. You can try again when ready.” |
| Insufficient funds | ”Payment could not be completed. Please check your balance.” |
| Invalid payment | ”Something went wrong. Please try again.” |
| Backend error | ”We’re having trouble. Please try again later.” |
Security Rules
When implementing payments inside Mini Apps:Security Checklist
Client-Side Security
Client-Side Security
- No secrets in Mini App code
- No direct Rebell API calls
- Payment status from backend only
- Session-based authentication
Backend Security
Backend Security
- Webhook signature verification
- Session validation before payment
- Idempotent payment creation
- Order ownership validation
UX Security
UX Security
- Clear payment amount display
- No misleading success messages
- Proper error handling
- Cancellation support
Testing Payments
Sandbox Testing Checklist
Happy Path
Happy Path
- Payment created successfully
- Payment UI opens correctly
- User can complete payment
- Webhook received
- UI shows confirmed success
Cancellation
Cancellation
- User cancels payment
- Mini App handles gracefully
- Can retry payment
- No duplicate payments created
Errors
Errors
- Network timeout handling
- Backend error handling
- Invalid session handling
- Expired payment handling
Edge Cases
Edge Cases
- Double-tap prevention
- App backgrounding during payment
- Webhook delay handling
- Concurrent payment attempts
Relationship with Payment Integration Chapter
This section explains how Mini Apps trigger and embed payments. For full details on:- Payment creation
- Payment lifecycle
- Error handling
- Inquiry API
- Webhooks