← Blog

SUQO API Integration Guide

28 May 2026 · 10 min read · Developer Guide

This guide walks through integrating the SUQO API into your product — from getting your API key to creating subscriptions, redirecting buyers to a hosted checkout, and handling subscription state via webhooks. If you've been managing recurring billing with spreadsheets or custom eSewa callbacks, this is the integration that replaces all of it. Also see the For Developers page for an overview of integration options.

The SUQO API is a REST API. All endpoints are under /api/v1/. Authentication uses a Bearer token. Requests and responses are JSON.

Before you start

You'll need a SUQO account with KYC completed. KYC connects your business to Nepal's payment infrastructure — it's required before you can collect payments. Sign up at app.suqo.ai, complete verification, and generate your API key from Configuration → API Integration in your dashboard.

You'll also need at least one product with a plan and billing period created. These define the price and billing cycle. Create them via the dashboard once, then fetch their pbp_id (plan billing period ID) from the Products endpoint to reference in your integration.

Authentication

Every API request requires an Authorization header with your Bearer token:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Keep your API key server-side. Never expose it in client-side code or a public repository.

Step 1: Create a subscription

When a customer signs up in your product, create a subscription in SUQO. This does not charge the buyer directly — it returns a hosted checkout link that SUQO uses to collect payment.

POST /api/v1/subscriptions/

{
  "pbp_id": "pbp_3n9k2x",
  "return_url": "https://yourproduct.com/thank-you",
  "client": {
    "phone": "9800000000",
    "full_name": "Aarav Shrestha",
    "email": "[email protected]",
    "address": "Kathmandu, Nepal"
  }
}

A successful response returns the subscription in a pending state, with a checkout link:

{
  "subscription_id": "sub_9f8a7b6c",
  "pbp_id": "pbp_3n9k2x",
  "status": "pending_checkout",
  "checkout_url": "https://app.suqo.ai/pay/sub_9f8a7b6c",
  "next_billing_cycle": null,
  "created_at": "2026-07-09T10:15:00Z"
}

Store subscription_id in your database — you'll use it to look up status and manage the subscription going forward.

Step 2: Redirect the buyer to checkout

Send the customer to checkout_url. SUQO handles the entire payment experience from there — OTP, wallet, or bank payment — and returns them to your return_url afterward.

Important: the redirect back to return_url is not proof of payment. A buyer can land back on your site whether the payment succeeded, failed, or they simply closed the tab. Use webhooks, not the redirect, to confirm the outcome.

Step 3: Get notified via webhooks

Configure a webhook endpoint and signing secret from the Webhooks page in your dashboard. SUQO POSTs signed events to your endpoint as things happen:

checkout.succeeded — payment completed, subscription is now active
checkout.failed — payment declined or abandoned
subscription.status.change — later lifecycle changes: renewal, cancellation, expiry

Every delivery is signed so you can verify it genuinely came from SUQO. Don't mark an order paid until you receive checkout.succeeded — that's the actual outcome, not the browser redirect.

Step 4: List your subscriptions

For dashboards, reporting, or reconciliation, query your subscriptions directly:

GET /api/v1/subscriptions/

The response is a paginated list with status-classified counts (active_subscriptions, due_subscriptions, inactive_subscriptions) and a status field per subscription:

pending_checkout — created, buyer hasn't completed checkout yet
active — currently active
due — billing date passed, payment not yet received
pending_cancellation — scheduled to cancel at the end of the current period
cancelled — cancelled immediately on request
inactive — automatically ended after the grace period elapsed without payment

Treat webhooks as the real-time signal and this list as the source of truth for on-demand reads — not the other way around.

Step 5: Cancel a subscription, or change its billing date

To cancel:

POST /api/v1/subscriptions/{id}/cancel/

No request body needed. This sets the subscription inactive and clears its billing cycle.

To push out the next charge date instead — for example, recording an offline payment or granting an extension — use:

POST /api/v1/subscriptions/update-billing-cycle/

{
  "subscription_id": "sub_9f8a7b6c",
  "next_billing_cycle": "2026-09-01"
}

A complete integration flow

Here's how a typical product integration looks end to end:

Step 1

Customer subscribes in your product

Your product handles the sign-up UX. When a customer completes sign-up, your backend calls POST /api/v1/subscriptions/ with their details and plan ID, then redirects them to the returned checkout_url.

Step 2

SUQO handles the payment

The buyer completes payment on SUQO's hosted checkout — OTP, wallet, or bank — and lands back on your return_url. Your backend waits for the webhook rather than trusting the redirect.

Step 3

Your product reacts to the webhook

On checkout.succeeded, grant access and mark the order paid. On checkout.failed, keep access restricted. Later, subscription.status.change events tell you about renewals, cancellations, and expiry — no polling required.

Step 4

Handle cancellations and plan changes

When a subscriber cancels in your product, call the cancel endpoint. There's no separate "change plan" call — to move someone to a different plan, cancel their current subscription and create a new one against the new plan's pbp_id.

Things to know

No per-call charges. API access is free. There are no rate limits that would affect normal usage, and no developer tier required. SUQO charges 1.99% per successful payment collected.

No merchant API required. You do not need your own eSewa or Khalti merchant account. SUQO handles the payment gateway integration. Subscribers pay through SUQO's payment layer; funds settle to your registered account.

Auto-debit readiness. When auto-debit becomes available in Nepal, it will be exposed through the same API endpoints. Products already integrated with SUQO will get auto-debit support without changing their integration structure.

Webhooks are live. Configure an endpoint and signing secret from the dashboard's Webhooks page. Every delivery is signed so you can verify it's genuinely from SUQO — build your integration around webhooks rather than polling for status changes.

The full API reference is at suqo.ai/docs/api.