Skip to content
Projects & Experiments

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.

CodingBowl··11 min read
Photo by Sophie Dupau on Unsplash
EcommerceFastAPIHitPayMobile AppReact NativeTypeScript

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

Part Article
Part 1 Part 1 - React Native with TypeScript and React Native Paper: Start MugMori
Part 2 Part 2 - Build a Cute Cup Product Catalog with React Native Paper
Part 3 Part 3 - Add Product Details, Favorites, and a Cart to React Native
Part 4 Part 4 - Build a Consumer Checkout Flow with React Native Paper
Part 5 Part 5 - Connect a React Native Cup Shop to a FastAPI Backend
Part 6 Part 6 - Integrate Stripe Payments with React Native and FastAPI
Part 7 Part 7 - Integrate HitPay Payments with React Native and FastAPI
Part 8 Part 8 - Business Models, Merchant Payments, and Stripe or HitPay Integration
Part 9 Part 9 - Understanding Ecommerce Transaction Fees and Profit Margins
Part 10 Part 10 - Merchant Account Setup for B2C and B2B Payments

Next: Part 8 - Business Models, Merchant Payments, and Stripe or HitPay Integration