Subscription payments,
made clear.

Start in the onboarding console

Onboarding creates the NetzonPay app, generates its API key, and creates monthly and annual plans for every pricing tier. Complete this before writing checkout code.

1. Open the correct onboarding environment

2. Enter the app identity

3. Build the pricing tiers

Every tier creates two active plans automatically: one Monthly plan and one Annual plan. For example, the Starter tier creates Starter Monthly and Starter Annual.

4. Launch and save the result

After a successful launch, copy all integration values before leaving the screen.

Optional: onboard programmatically

The onboarding console uses this API. It creates real app and plan records immediately in the selected environment.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/onboarding/apps \
  --header 'Content-Type: application/json' \
  --data '{
    "app_name": "Example SaaS",
    "slug": "example-saas",
    "description": "Subscription billing for Example SaaS",
    "callback_url": "https://example.com/billing/callback",
    "logo_url": "https://example.com/logo.svg",
    "currency": "PHP",
    "tiers": [
      {
        "name": "Starter",
        "monthly_price": 299.00,
        "annual_price": 2990.00
      }
    ]
  }'

Configure your backend

Use values from the onboarding success screen. Keep a separate set for development, staging, and production.

NETZONPAY_API_URL=https://dev-api-pay.netzon.dev
NETZONPAY_PORTAL_URL=https://dev-pay.netzon.dev
NETZONPAY_APP_ID=YOUR_ONBOARDED_APP_ID
NETZONPAY_API_KEY=YOUR_ONBOARDING_API_KEY
NETZONPAY_PLAN_STARTER_MONTHLY=MONTHLY_PLAN_ID
NETZONPAY_PLAN_STARTER_ANNUAL=ANNUAL_PLAN_ID
APP_URL=https://your-app.example

Confirm the onboarded plans

This returns the active plans belonging to the authenticated app and is useful for confirming onboarding or powering a server-controlled pricing page.

Integrate the onboarded app

Once onboarding gives you the App ID, API key, and Plan IDs, connect them to your backend. Your server creates a short-lived session, the customer pays through hosted checkout, and your server verifies access afterward.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{
    "app_id": "YOUR_APP_ID",
    "external_user_id": "user-123",
    "email": "customer@example.com",
    "name": "Customer Name",
    "phone": "09170000000",
    "plan_id": "YOUR_PLAN_ID",
    "return_url": "https://your-app.example/billing/result"
  }'

const response = await fetch(
  "https://dev-api-pay.netzon.dev/api/v1/sessions",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.NETZONPAY_API_KEY
    },
    body: JSON.stringify({
      app_id: process.env.NETZONPAY_APP_ID,
      external_user_id: user.id,
      email: user.email,
      name: user.name,
      phone: user.phone,
      plan_id: selectedPlanId,
      return_url: `${process.env.APP_URL}/billing/result`
    })
  }
);

const { data } = await response.json();
return data.payment_url;

$response = Http::withHeaders([
    'X-Api-Key' => env('NETZONPAY_API_KEY'),
])->post('https://dev-api-pay.netzon.dev/api/v1/sessions', [
    'app_id' => env('NETZONPAY_APP_ID'),
    'external_user_id' => (string) $user->id,
    'email' => $user->email,
    'name' => $user->name,
    'phone' => $user->phone,
    'plan_id' => $planId,
    'return_url' => route('billing.result'),
]);

return redirect($response->json('data.payment_url'));

import os
import requests

response = requests.post(
    "https://dev-api-pay.netzon.dev/api/v1/sessions",
    headers={
        "X-Api-Key": os.environ["NETZONPAY_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "app_id": os.environ["NETZONPAY_APP_ID"],
        "external_user_id": str(user.id),
        "email": user.email,
        "name": user.get_full_name(),
        "phone": user.phone,
        "plan_id": selected_plan_id,
        "return_url": f"{os.environ['APP_URL']}/billing/result",
    },
)

response.raise_for_status()
payment_url = response.json()["data"]["payment_url"]

Use the right environment end to end

API credentials, portal URLs, FIUU credentials, callbacks, databases, and test records must stay within the same environment.

Core concepts

How a payment moves through the system

1. Your backend creates a session with its app API key.
2. The customer opens the returned NetzonPay portal URL.
3. NetzonPay creates the FIUU hosted-checkout payload.
4. FIUU handles card entry, 3DS, and payment authorization.
5. FIUU posts signed return/callback data to NetzonPay.
6. NetzonPay verifies the signature and updates payment and subscription state idempotently.
7. Your backend checks the subscription before enabling paid features.

Authentication

Integration endpoints use an app-scoped API key. Admin endpoints use an authenticated administrator session or bearer token.

Create a payment session

Sessions must be created from your trusted backend. NetzonPay verifies that the authenticated app owns both the supplied App ID and Plan ID.

Subscribe multiple units on one plan

A subscriber who needs several units of the same package — branches, seats, tranches, whatever your app calls them — can pay for all of them in one session instead of creating one subscription per unit. Send quantity when creating the session; NetzonPay scales the charge and keeps every recurring cycle in sync automatically. NetzonPay has no opinion on what a "unit" is — that's entirely your app's business logic.

What quantity affects

• The initial charge for the session equals plan.amount × quantity.
• The subscription created after a successful payment stores the same quantity, and every future auto-charge and retry-charge uses it — you don't need to resend it.
• A retried session (after a failed payment) keeps the original quantity; the subscriber cannot change it mid-retry.
• Only one package per subscription. If different unit groups need different packages, create a separate session/subscription per package.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{
    "app_id": "YOUR_APP_ID",
    "external_user_id": "user-123",
    "email": "customer@example.com",
    "name": "Customer Name",
    "plan_id": "YOUR_PLAN_ID",
    "quantity": 5,
    "return_url": "https://your-app.example/billing/result"
  }'

Redirect to hosted checkout

The create-session response provides the session identifier and checkout/payment URL. Redirect the customer to that URL without modifying it.

{
  "success": true,
  "data": {
    "session_id": "d4e5f6a7-b8c9-0123-4567-890abcdef123",
    "payment_url": "https://dev-pay.netzon.dev/pay/d4e5f6a7-b8c9-0123-4567-890abcdef123"
  }
}

Handle the customer’s return safely

The configured return_url is only a navigation destination. It does not carry a trusted payment decision. When the customer returns, your backend must check the subscription using the authenticated user’s own external_user_id.

export async function GET(request) {
  const user = await requireAuthenticatedUser(request);
  const url = new URL(
    "https://dev-api-pay.netzon.dev/api/v1/subscriptions/check"
  );
  url.searchParams.set("app_id", process.env.NETZONPAY_APP_ID);
  url.searchParams.set("external_user_id", String(user.id));

  const response = await fetch(url, {
    headers: { "X-Api-Key": process.env.NETZONPAY_API_KEY },
    cache: "no-store"
  });
  const { data } = await response.json();

  return Response.json({
    active: data.active,
    status: data.status,
    plan_name: data.plan_name
  });
}

Gate access with the subscription check

Do not grant paid access from a browser redirect or query parameter. Your backend should ask NetzonPay for the subscriber’s current access decision.

const url = new URL(
  "https://dev-api-pay.netzon.dev/api/v1/subscriptions/check"
);
url.searchParams.set("app_id", process.env.NETZONPAY_APP_ID);
url.searchParams.set("external_user_id", user.id);

const response = await fetch(url, {
  headers: { "X-Api-Key": process.env.NETZONPAY_API_KEY }
});
const { data } = await response.json();

if (!data.active) {
  return redirect("/subscribe");
}

Subscription response

{
  "success": true,
  "data": {
    "app_id": "YOUR_APP_ID",
    "external_user_id": "user-123",
    "active": true,
    "subscription_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "plan_id": "YOUR_PLAN_ID",
    "status": "active",
    "current_period_end": "2026-08-30T00:00:00Z",
    "trial_end": null,
    "plan_name": "Starter Monthly",
    "amount": 299.00,
    "payment_method": {
      "type": "card",
      "brand": "VISA",
      "last4": "4242"
    }
  }
}

Cache intentionally

The NetzonPay endpoint has a five-second response cache. Your backend may cache the normalized result for 30–60 seconds for ordinary page access, but should re-check before sensitive account or billing operations.

Cancel a subscription

An app can cancel only its own subscription. Use full cancellation when the subscriber wants to stop renewal entirely, and use edit-quantity when they only want to upgrade or downgrade the unit count.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/subscriptions/SUBSCRIPTION_ID/cancel \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{ "reason": "Requested by customer" }'

Full cancellation response

{
  "success": true,
  "data": {
    "status": "cancelled",
    "access_until": "2026-07-05T00:00:00Z",
    "quantity": 3
  }
}

Edit quantity — upgrade or downgrade a multi-unit subscription

Send the target quantity, not a delta — it can be higher (upgrade) or lower (downgrade) than the subscription's current quantity, while keeping the subscription status active, trial, or past due. This endpoint does not fully cancel the subscription. Sending the same quantity the subscription already has is a harmless no-op.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/subscriptions/SUBSCRIPTION_ID/quantity \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{ "quantity": 8, "reason": "Customer upgraded to 8 units" }'

Edit-quantity response

{
  "success": true,
  "data": {
    "status": "active",
    "quantity": 8,
    "previous_quantity": 5,
    "current_period_start": "2026-09-15T00:00:00Z",
    "current_period_end": "2026-10-15T00:00:00Z",
    "amount_charged": 550.00,
    "credit_applied": 250.00,
    "payment_id": "8f2c1a3e-...",
    "updated_at": "2026-09-15T00:00:00Z"
  }
}

Change plan — switch to a higher-priced plan

A different action from Edit Quantity above — this changes Subscription.PlanId itself (e.g. Basic → Premium) rather than the quantity on the same plan — but it runs the identical billing mechanism: a fresh full cycle charged immediately, credited for unused time, gated on a successful charge, renewal date reset to today. Only upgrading to a strictly higher-priced plan on the same app is supported.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/subscriptions/SUBSCRIPTION_ID/plan \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{ "plan_id": "PREMIUM_PLAN_ID", "reason": "Customer upgraded to Premium" }'

Change-plan response

{
  "success": true,
  "data": {
    "status": "active",
    "plan_id": "7a1c8890-...",
    "plan_name": "Premium",
    "current_period_start": "2026-09-20T00:00:00Z",
    "current_period_end": "2026-10-20T00:00:00Z",
    "amount_charged": 799.33,
    "credit_applied": 99.67,
    "payment_id": "3d9e2b1a-..."
  }
}

One-time tokenization — booking-style apps

Everything above this section is about Subscription-billed apps — recurring plans, auto-renewal, quantity upgrade/downgrade. NetzonPay also supports a second, separate billing mode for apps whose business is "one payment, then a bounded window of on-demand charges" — a hotel booking, an equipment rental, an event pass with add-ons. Billing mode is chosen once, when the app is created, and can't be changed afterward.

The flow

1. Guest checks in — you call POST /api/v1/sessions with token_valid_until set to the end of the window (e.g. the check-out date). Guest pays through the normal hosted checkout. No subscription is created.
2. During the window — you call the charge endpoint any time you need to bill an extra, against the same card, with no further card entry.
3. Window ends — you call the close endpoint to invalidate the card token. It can never be charged again.

curl --request POST \
  --url https://dev-api-pay.netzon.dev/api/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_APP_API_KEY' \
  --data '{
    "app_id": "YOUR_APP_ID",
    "external_user_id": "guest-12345",
    "email": "guest@example.com",
    "name": "Jane Guest",
    "plan_id": "YOUR_ROOM_RATE_PLAN_ID",
    "return_url": "https://yourapp.com/booking/confirm",
    "token_valid_until": "2026-09-15T12:00:00Z"
  }'

A complete backend integration

Keep NetzonPay calls behind a small server-side module. This makes authentication, error handling, environment changes, and tests consistent across subscribe, status, and cancellation routes.

const API_URL = process.env.NETZONPAY_API_URL;
const API_KEY = process.env.NETZONPAY_API_KEY;
const APP_ID = process.env.NETZONPAY_APP_ID;

async function netzonPay(path, options = {}) {
  const response = await fetch(`${API_URL}${path}`, {
    ...options,
    headers: {
      "X-Api-Key": API_KEY,
      "Content-Type": "application/json",
      ...options.headers
    }
  });

  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    const error = new Error(body.detail || `NetzonPay error ${response.status}`);
    error.status = response.status;
    error.traceId = body.traceId;
    throw error;
  }
  return body.data;
}

export function createPaymentSession(user, planId, returnUrl, quantity = 1) {
  return netzonPay("/api/v1/sessions", {
    method: "POST",
    body: JSON.stringify({
      app_id: APP_ID,
      external_user_id: String(user.id),
      email: user.email,
      name: user.name,
      phone: user.phone,
      plan_id: planId,
      quantity: quantity,
      return_url: returnUrl
    })
  });
}

export function checkSubscription(userId) {
  const query = new URLSearchParams({
    app_id: APP_ID,
    external_user_id: String(userId)
  });
  return netzonPay(`/api/v1/subscriptions/check?${query}`, {
    headers: { "Content-Type": undefined }
  });
}

export function cancelSubscription(subscriptionId, reason) {
  return netzonPay(`/api/v1/subscriptions/${subscriptionId}/cancel`, {
    method: "POST",
    body: JSON.stringify({ reason })
  });
}

export function setQuantity(subscriptionId, quantity, reason) {
  return netzonPay(`/api/v1/subscriptions/${subscriptionId}/quantity`, {
    method: "POST",
    body: JSON.stringify({ quantity, reason })
  });
}

router.post("/subscribe", requireAuth, async (req, res, next) => {
  try {
    const session = await createPaymentSession(
      req.user,
      req.body.plan_id,
      `${process.env.APP_URL}/subscription/result`
    );
    res.redirect(303, session.payment_url);
  } catch (error) {
    next(error);
  }
});

router.get("/subscription/status", requireAuth, async (req, res, next) => {
  try {
    res.json(await checkSubscription(req.user.id));
  } catch (error) {
    next(error);
  }
});

router.post("/subscription/cancel", requireAuth, async (req, res, next) => {
  try {
    const subscription = await checkSubscription(req.user.id);
    if (!subscription.subscription_id) {
      return res.status(400).json({ error: "No subscription to cancel" });
    }
    res.json(await cancelSubscription(
      subscription.subscription_id,
      req.body.reason || "Customer requested cancellation"
    ));
  } catch (error) {
    next(error);
  }
});

router.post("/subscription/quantity", requireAuth, async (req, res, next) => {
  try {
    const subscription = await checkSubscription(req.user.id);
    if (!subscription.subscription_id) {
      return res.status(400).json({ error: "No subscription to update" });
    }
    res.json(await setQuantity(
      subscription.subscription_id,
      req.body.quantity,
      req.body.reason || "Customer requested quantity change"
    ));
  } catch (error) {
    next(error);
  }
});

Understand the subscription lifecycle

Supported billing periods

How automatic renewal works

The initial payment is customer-present. Successful FIUU tokenization stores a protected payment token. When an active subscription becomes due, NetzonPay submits a server-to-server recurring request and waits for FIUU’s verified result.

Eligibility requirements

• Subscription status is active and the current period has ended.
• A default payment method exists with a real FIUU token, consent, or mandate identifier.
• The payment method is a card or has a supported FIUU recurring record type.
• No recurring payment for the same subscription is already pending.
• Auto-charge is enabled and FIUU recurring credentials belong to the same environment.

FIUU return, notify, and callback endpoints

These endpoints are public because FIUU calls them. NetzonPay validates required fields, verifies skey, applies idempotency, and maps the FIUU order to an existing payment.

Security practices for integrations

Frequently asked questions

Errors and rate limits

Troubleshooting map

Go-live checklist