Implement auto-charge subscriptions with Stripe Custom Payment Methods and HitPay
Auto-charge subscriptions allow customers to authorize and tokenize a payment method once, with future invoices charged automatically via HitPay. This flow only works with tokenizable payment methods (Cards, ShopeePay, GrabPay).
This integration connects Stripe’s Subscription API with HitPay’s Recurring Billing API, allowing customers to set up automatic payments using local payment methods while keeping all subscription records in Stripe.
Create recurring billing sessions with embedded authorization — returns QR codes and direct app links instead of redirecting to a hosted checkout page.
HitPay Save Payment Method & Charge
How to charge a saved payment method via the HitPay API — the same charge endpoint used to bill both the first invoice and all future renewals.
Stripe Subscriptions API
Manage subscription lifecycle and invoice generation.
Third-Party Payment Processing
Stripe’s recommended pattern for processing subscription payments via external payment processors.
This integration touches six Stripe objects. Understanding each one makes it easier to follow the code and debug issues.
Customer
A Stripe Customer represents the subscriber. In this integration, the customer object is the bridge between Stripe and HitPay — it stores the HitPay recurring billing session ID in its metadata so every future invoice knows which HitPay token to charge.Key fields used:
Field
Purpose
metadata.hitpay_recurring_billing_id
HitPay recurring billing session ID — used to charge all invoices
metadata.hitpay_payment_method
The HitPay recurring method (e.g. shopee_recurring, grabpay_direct, card)
metadata.hitpay_cpm_type_id
Stripe CPM Type ID — used when creating a PaymentMethod for reporting
The customer is created (or retrieved by email) when the subscription is set up, and its metadata is populated after the HitPay recurring billing session is created.
Subscription
A Stripe Subscription manages the billing lifecycle — it defines the billing interval, generates invoices on each renewal, and tracks subscription status (active, past_due, canceled, etc.).In this integration, subscriptions are created with collection_method: 'charge_automatically' and payment_behavior: 'default_incomplete'. This tells Stripe to generate invoices for each billing cycle and fire the invoice.payment_attempt_required webhook — but not to attempt payment via Stripe’s own payment methods. Your webhook handler performs the actual charge via HitPay.Key fields used:
Field
Value / Purpose
collection_method
charge_automatically — generates invoices and fires the payment webhook
payment_behavior
default_incomplete — subscription stays incomplete until the first invoice is paid
latest_invoice
ID of the first invoice, retrieved immediately after subscription creation
status
Tracks whether the subscription is active, incomplete, or past due
Invoice
A Stripe Invoice represents one billing cycle. Stripe creates an invoice automatically for each period of a charge_automatically subscription.There are two types of invoices in this flow:
First invoice (billing_reason: 'subscription_create'): Created when the subscription is set up. Charged manually after the customer authorizes their payment method on HitPay. Your webhook handler skips this one to avoid double-charging.
Renewal invoices (billing_reason: 'subscription_cycle'): Generated automatically at each billing period. The invoice.payment_attempt_required webhook fires for these, and your handler charges them via HitPay.
After a successful HitPay charge, the invoice is marked paid using invoices.pay(invoiceId, { paid_out_of_band: true }) — this closes the invoice without Stripe attempting its own payment.Key fields used:
Field
Purpose
amount_due
Amount to charge (in the smallest currency unit, e.g. cents)
currency
Currency for the HitPay charge
customer
Customer ID — used to retrieve hitpay_recurring_billing_id from metadata
billing_reason
subscription_create vs subscription_cycle — used to skip the first invoice in the webhook
id
Stored in PaymentRecord.metadata for reconciliation
PaymentMethod (type: custom)
A Stripe PaymentMethod of type custom represents a Custom Payment Method — it is created on the fly for each HitPay charge, purely for reporting purposes.This object is required as input to paymentRecords.reportPayment(). It carries the CPM Type ID that tells Stripe which custom payment method was used (e.g. your ShopeePay or GrabPay CPM).
Note: This PaymentMethod is not saved to the customer or reused. A new one is created per charge solely to satisfy the reportPayment() API.
PaymentRecord
A Stripe PaymentRecord is how external charges are made visible in the Stripe Dashboard. After charging via HitPay, you call paymentRecords.reportPayment() to record the charge in Stripe — this gives your team unified reporting and reconciliation without HitPay payments being invisible inside Stripe.The PaymentRecord stores the HitPay payment ID in two places (for easy retrieval when processing refunds):
processor_details.custom.payment_reference — the HitPay payment ID
metadata.hitpay_payment_id — same value, accessible as plain metadata
Key fields used:
Field
Value / Purpose
amount_requested.value
Invoice amount_due (in smallest currency unit)
payment_method_details.payment_method
The custom PaymentMethod ID created above
processor_details.custom.payment_reference
HitPay payment_id returned by the charge API
customer_presence
off_session — charge was made without the customer present
outcome
guaranteed — HitPay confirmed the charge succeeded
metadata.invoice_id
Stripe invoice ID — links the record back to the billing cycle
invoice.payment_attempt_required (webhook event)
The invoice.payment_attempt_required event is fired by Stripe whenever a subscription invoice needs to be charged under collection_method: charge_automatically.This is the trigger for all renewal auto-charges. Your webhook handler receives this event, looks up the customer’s hitpay_recurring_billing_id, and calls HitPay to charge the invoice.Important: Stripe fires this event for the first invoice too (billing_reason: 'subscription_create'). Your handler must skip it — the first invoice is already charged manually after the customer completes HitPay authorization. Charging it again here would double-bill the customer.
Register each HitPay payment method as a Custom Payment Method (CPM) type in your Stripe Dashboard and map those CPM Type IDs to HitPay method identifiers in a config file.
1
Create Custom Payment Methods on Stripe Dashboard
Stripe DashboardCreate Custom Payment Method types in your Stripe Dashboard for each HitPay payment method you want to offer.
Create CPM in Stripe Dashboard
Follow Stripe’s guide to create Custom Payment Method types and get your CPM Type IDs.
Download Payment Icons
Download official HitPay payment method icons (PayNow, ShopeePay, GrabPay, FPX, and more) optimized for Stripe Custom Payment Methods.
2
Create Configuration File
Server-sideMap your Stripe CPM Type IDs to HitPay payment methods. Include the hitpayRecurringMethod for auto-charge support.
The chargeAutomatically flag indicates whether a payment method supports tokenization for recurring charges. QR-based methods like PayNow cannot be saved for future charges.
You’ll have different CPM Type IDs in sandbox and production — they are separate Stripe accounts. Consider using environment variables or an ids: { sandbox: string, production: string } structure so you can switch between environments without code changes.
When the customer submits the checkout form, two server calls happen in sequence:
Create a Stripe Subscription — creates an incomplete subscription and a pending invoice
Create a HitPay Recurring Billing session — tokenizes the payment method and returns authorization data (QR code or direct app link)
The authorization data from step 2 is then used in Step 3 to let the customer approve the payment method inline.
1
Configure Environment Variables
Server-sideSet up the required API keys and configuration for both Stripe and HitPay.
# StripeNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxSTRIPE_SECRET_KEY=sk_test_xxx# HitPayHITPAY_API_KEY=xxxHITPAY_SALT=xxxNEXT_PUBLIC_HITPAY_ENV=sandbox # or 'production'NEXT_PUBLIC_SITE_URL=https://your-domain.com# Stripe Webhook (for auto-charge renewals — see Step 4)STRIPE_WEBHOOK_SECRET=whsec_xxx
Never expose STRIPE_SECRET_KEY or HITPAY_API_KEY to the client. These are server-side only.
2
Client: Collect customer info and initiate setup
Client-sideCollect the customer’s email address and selected plan, then make two sequential server calls: first to create the Stripe subscription, then to start the HitPay authorization session.
// 1. Create Stripe subscription — returns subscription + invoice detailsconst subRes = await fetch('/api/create-subscription', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email, priceId, // Stripe Price ID for the selected plan cpmTypeId, // Stripe CPM Type ID for the selected payment method }),});const { subscriptionId, customerId, invoiceId, invoiceAmount, currency } = await subRes.json();// 2. Create HitPay recurring billing session — returns authorization embed dataconst hitpayRes = await fetch('/api/hitpay/recurring-billing/create', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ customerId, subscriptionId, invoiceId, amount: invoiceAmount, currency, customerEmail: email, paymentMethod: selectedRecurringMethod, // e.g. 'card', 'shopee_recurring', 'grabpay_direct' }),});const { directLinkUrl, directLinkAppUrl, qrCode } = await hitpayRes.json();// → Pass this data to Step 3 to render inline authorization
selectedRecurringMethod comes from the CPM config (hitpayRecurringMethod) for whichever payment method the customer chose. See the CUSTOM_PAYMENT_METHODS config in Step 1.
3
Server: Create Stripe Subscription
Server-sideCreate a Stripe subscription with charge_automatically collection method. The subscription starts as incomplete — it will become active once the first invoice is charged in Step 3.What this returns:subscriptionId, customerId, invoiceId, and the invoiceAmount needed to create the HitPay session.
Server-sideCall POST /v1/recurring-billing with generate_embed=true. This tokenizes the customer’s payment method and returns the authorization data needed for inline rendering. Store the recurring_billing_id on the Stripe customer — you’ll need it for all future charges.What this returns: A session.id (the recurring billing token), plus either qr_code_data (for card) or direct_link (for ShopeePay / GrabPay).
app/api/hitpay/recurring-billing/create/route.ts
// app/api/hitpay/recurring-billing/create/route.tsimport { NextResponse } from 'next/server';import { stripe } from '@/lib/stripe';const HITPAY_API_URL = process.env.NEXT_PUBLIC_HITPAY_ENV === 'production' ? 'https://api.hit-pay.com/v1' : 'https://api.sandbox.hit-pay.com/v1';export async function POST(request: Request) { const { customerId, subscriptionId, invoiceId, amount, currency, customerEmail, paymentMethod, // e.g., 'card', 'shopee_recurring' } = await request.json(); const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'; // POST /v1/recurring-billing — tokenize the customer's payment method. // generate_embed=true returns a QR code or direct app link for inline authorization // instead of redirecting the customer to HitPay's hosted checkout page. const params = new URLSearchParams({ customer_email: customerEmail, amount: amount.toFixed(2), currency, redirect_url: `${baseUrl}/subscribe/setup?subscription_id=${subscriptionId}&customer_id=${customerId}&invoice_id=${invoiceId}`, reference: subscriptionId, generate_embed: 'true', }); params.append('payment_methods[]', paymentMethod); const hitpayRes = await fetch(`${HITPAY_API_URL}/recurring-billing`, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'X-BUSINESS-API-KEY': process.env.HITPAY_API_KEY!, }, body: params.toString(), }); const session = await hitpayRes.json(); // Store recurring billing ID in customer metadata await stripe.customers.update(customerId, { metadata: { hitpay_recurring_billing_id: session.id, hitpay_payment_method: paymentMethod, }, }); // Extract embed fields for the frontend const directLinkUrl = session.direct_link?.direct_link_url ?? null; const directLinkAppUrl = session.direct_link?.direct_link_app_url ?? null; const qrCode = session.qr_code_data?.qr_code ?? null; return NextResponse.json({ recurringBillingId: session.id, // Embed data — use one of these to authorize inline (preferred) directLinkUrl, // ShopeePay / GrabPay: open in browser directLinkAppUrl, // ShopeePay only: open Shopee app directly (mobile) qrCode, // Card: render as QR code // Fallback: redirect to HitPay's hosted checkout (not ideal — sends customer away) hostedCheckoutUrl: session.url, status: session.status, });}
After creating the HitPay recurring billing session in Step 2, present the authorization UI to the customer.
Embedded (Recommended)
URL Redirect
Instead of redirecting the customer to HitPay’s hosted checkout page, the embedded approach returns authorization data directly in the API response — a QR code or a direct app link — which you render inline on your page. The customer never leaves your site.To enable this, pass generate_embed: true when calling POST /v1/recurring-billing:
active — customer has authorized the payment method (safe to charge)
canceled — authorization was canceled or expired
Once active, the polling component calls /api/subscription/charge-invoice automatically. See Charge the Saved Payment Method for HitPay charge API details.
This approach redirects the customer away from your site to HitPay’s hosted checkout page. It breaks the subscription setup flow and is not recommended. Use the Embedded approach if possible.
Use the hostedCheckoutUrl from the session response to redirect the customer. HitPay redirects them back to your redirect_url after authorization, where you then charge the first invoice.
Server-sideRetrieve the customer’s hitpay_recurring_billing_id from their Stripe metadata and call POST /v1/charge/recurring-billing/{id} to debit the saved payment method.
Treat both succeeded and pending as success. pending means the charge is processing asynchronously — store charge.payment_id in invoice metadata and let the webhook confirm it later.
2
Report Payment in Stripe
Server-sideRecord the HitPay charge in Stripe using stripe.paymentRecords.reportPayment(). This gives Stripe a record of the payment for reconciliation and unified reporting. Without this step, Stripe has no visibility into what was collected by HitPay.
Use outcome: 'guaranteed' for succeeded charges. If the charge returned pending, use outcome: 'failed' temporarily — update the PaymentRecord to guaranteed once the HitPay webhook confirms the charge.
3
Mark Invoice as Paid
Server-sideMark the Stripe invoice as paid with paid_out_of_band: true. This tells Stripe the payment was collected externally (via HitPay), transitions the invoice to paid, and activates the subscription.
Store the HitPay payment ID and Stripe payment record ID in invoice metadata as an idempotency guard — the webhook handler checks for these before charging future invoices to avoid double-charging.
Once the invoice is paid, Stripe transitions the subscription from incomplete → active. Future renewals are handled automatically by the webhook in Step 4.
Full implementation: app/api/subscription/charge-invoice/route.ts
On each billing cycle, Stripe fires invoice.payment_attempt_required when a new invoice is created. A webhook handler automatically charges the customer’s saved HitPay payment method and records the payment in Stripe — no customer action required.
1
Setup Stripe Webhook
Server-sideHandle the invoice.payment_attempt_required Stripe webhook event to automatically charge future invoices.Webhook setup:
Go to Stripe Dashboard → Developers → Webhooks → Add endpoint
Enter your endpoint URL: https://your-domain.com/api/stripe/webhook
Select the event: invoice.payment_attempt_required
Copy the Signing secret (whsec_xxx) and add it as STRIPE_WEBHOOK_SECRET
Which payment methods support auto-charge subscriptions?
Auto-charge requires tokenizable payment methods: Cards, ShopeePay, and GrabPay. PayNow is QR-based and cannot be tokenized — customers using PayNow must pay each invoice manually via the out-of-band flow.
Why is the recurring billing charge failing?
Verify the recurring billing session is active (not pending or canceled)
Check that the customer authorized the payment method
Ensure the amount and currency are correct
Why isn't the webhook triggering charges?
Verify webhook endpoint is configured in Stripe Dashboard