Part 7 - Integrate HitPay Payments with React Native and FastAPI
Learn how a React Native app can use a FastAPI or Django backend to create HitPay payment requests and process webhooks safely.
Integrate HitPay Payments with React Native and FastAPI
HitPay is a payment service provider that exposes an HTTP API and webhook flow. That makes it usable with Django, FastAPI, or another backend framework. It is not a React Native-only service and it does not require a special Django or FastAPI plugin.
This article shows the correct boundary for MugMori. It is educational only: it does not add HitPay credentials, payment models, or live payment code to this repository.
The integration boundary
Use this flow:
React Native app
|
v
Django or FastAPI backend
|
v
HitPay payment request API
|
v
HitPay hosted checkout
|
v
HitPay webhook -> backend
The mobile app asks the backend to create a payment request. The backend calculates the trusted amount, keeps the HitPay API key private, and returns only the checkout URL or a safe payment reference to the app.
Does HitPay support Django and FastAPI?
Yes. Both frameworks can:
- Make HTTPS requests to HitPay's API.
- Create payment requests on the server.
- Return a hosted checkout URL to a web or mobile client.
- Receive webhook POST requests.
- Verify webhook authenticity using HitPay's current webhook-signature guidance.
- Store payment status and provider references.
Django is a good fit when the payment belongs to an existing Django-owned workflow, such as course purchases, admin-managed orders, or a Django catalog. FastAPI is a good fit for MugMori's future mobile API. The security boundary is the same in either framework.
Singapore payment methods with HitPay
HitPay’s available methods depend on the merchant account, country, product, channel, and activation status. This table shows both supported methods and methods that are not part of the standard Singapore list.
| Payment method | Singapore HitPay status | Notes |
|---|---|---|
| Visa | Available | Domestic and international card payment. |
| Mastercard | Available | Domestic and international card payment. |
| American Express | Available | Card payment where enabled. |
| PayNow | Available | Online QR or bank-app payment. |
| DBS PayLah! | Available through PayNow | PayLah! can scan a PayNow QR; it is not a separate HitPay API method. |
| GrabPay | Available | Singapore wallet checkout. |
| ShopeePay | Available | Wallet checkout where enabled for the merchant account. |
| Apple Pay | Available | Wallet payment using an eligible card and device. |
| Google Pay | Available | Wallet payment using an eligible card and device. |
| Atome | Conditional | BNPL method subject to merchant and transaction eligibility. |
| Grab PayLater | Conditional | BNPL method subject to merchant and transaction eligibility. |
| ShopeePay Later | Conditional | BNPL method subject to merchant and transaction eligibility. |
| WeChat Pay | Conditional | Regional or cross-border method when enabled. |
| UPI | Conditional | Regional or cross-border method when enabled. |
| PayPal | Not listed as a standard HitPay Singapore method | Do not promise PayPal checkout through the standard HitPay Singapore integration. |
The checkout response remains the source of truth for what the customer can select. Process HitPay webhooks idempotently and do not treat a redirect or mobile success screen as proof that an order is paid.
Create a HitPay payment request
The exact available payment methods, currencies, API fields, and endpoint behavior depend on the HitPay account and country. Check the current HitPay API documentation before implementation. The following illustrates the server-side shape without exposing credentials:
import os
import httpx
HITPAY_API_URL = 'https://api.hit-pay.com/v1/payment-requests'
async def create_hitpay_request(order):
payload = {
'amount': str(order.total_amount),
'currency': order.currency,
'reference_number': order.reference,
'name': order.customer_name,
'email': order.customer_email,
'purpose': 'MugMori cup order',
'redirect_url': 'https://mugmori.example/checkout/complete',
'webhook': 'https://api.mugmori.example/payments/hitpay/webhook',
}
headers = {
'X-BUSINESS-API-KEY': os.environ['HITPAY_API_KEY'],
'X-Requested-With': 'XMLHttpRequest',
}
async with httpx.AsyncClient(timeout=15) as client:
response = await client.post(HITPAY_API_URL, data=payload, headers=headers)
response.raise_for_status()
return response.json()
The backend must calculate order.total_amount from trusted product and promotion data. Never accept a final amount from React Native without rechecking it.
Open hosted checkout from React Native
After the backend creates the payment request, it can return the provider's checkout URL. The app can open that URL using the platform browser or an approved in-app browser flow.
const response = await api.post('/payments/hitpay', cartPayload);
await Linking.openURL(response.checkout_url);
The app should show a pending order state while the customer completes payment. Returning from the browser is not proof that payment succeeded.
Process the webhook
The webhook endpoint should read the raw request body, validate the provider signature according to the current HitPay documentation, and process each provider event idempotently. Store the provider payment-request identifier and webhook event identifier so a retry cannot mark an order paid twice.
@router.post('/payments/hitpay/webhook')
async def hitpay_webhook(request: Request):
raw_body = await request.body()
signature = request.headers.get('HitPay-Signature', '')
verify_hitpay_signature(raw_body, signature)
event = parse_hitpay_event(raw_body)
process_event_once(event)
return {'received': True}
Do not mark an order as paid based only on the redirect URL or a client-side success message. The server-side webhook and provider status are the source of truth.
Django and FastAPI examples
In Django, the payment-request operation can live in a service module called by a view, while a webhook view performs signature verification and updates the order. In FastAPI, the same operations can be split between a dependency, an API router, and an async service function.
Do not duplicate the payment workflow in both frameworks. Choose one owner for orders, payment state, refunds, and webhook processing. If Django owns the data, FastAPI can call a shared service boundary or Django-owned database logic according to an accepted architecture decision.
Test and production checklist
Use HitPay sandbox or test configuration where available. Test successful payments, declined payments, abandoned checkout, duplicate webhooks, invalid signatures, expired requests, currency mismatches, and unavailable payment methods. Keep API keys in environment secrets, never in React Native bundles, source control, or blog content.
HitPay supports Django and FastAPI because the integration is based on HTTP and webhooks. The framework choice should follow ownership: Django for Django-owned commerce, FastAPI for the future MugMori mobile API.
MugMori series
Next: Part 8 - Business Models, Merchant Payments, and Stripe or HitPay Integration