Skip to main content

Your First Sub-Merchant

In this tutorial you'll create a merchant and account within your partner hierarchy — the foundation for enabling payments for any entity on your platform.

Time: ~15 minutes Prerequisites: Sandbox credentials from /sandbox. Understand Wallet Structure before starting.

What you'll build​

By the end of this tutorial you'll have:

  1. Created a merchant (representing a business on your platform)
  2. Created an account for that merchant (to hold their funds)
  3. Generated a QRPH code for the account
  4. Checked the merchant's balance

This is the onboarding flow you'd run automatically when a new merchant signs up on your platform.

Step 1: Create a merchant​

A merchant represents a business or entity on your platform — a restaurant, a client company, a rider. Create one for each distinct entity that needs its own funds.

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -X POST "https://api.partners.nextpay.world/v2/merchants" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juana Pizza Co.",
    "external_id": "merchant-user-456",
    "contact_email": "[email protected]"
  }'

Response​

{
  "id": "merch_01HABC",
  "name": "Juana Pizza Co.",
  "external_id": "merchant-user-456",
  "contact_email": "[email protected]",
  "status": "active",
  "created_at": "2025-11-15T10:00:00Z"
}

Store merch_01HABC — you need it to create accounts for this merchant.

The external_id lets you look up this merchant by your own ID later: GET /v2/merchants/external/merchant-user-456.

Step 2: Create an account​

Each merchant needs at least one account to hold funds. An account is the actual wallet — it has a balance and can send and receive money.

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -X POST "https://api.partners.nextpay.world/v2/accounts" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "merch_01HABC",
    "name": "Collections",
    "external_id": "account-user-456-collections"
  }'

Response​

{
  "id": "acct_01HDEF",
  "merchant_id": "merch_01HABC",
  "name": "Collections",
  "external_id": "account-user-456-collections",
  "status": "active",
  "created_at": "2025-11-15T10:01:00Z"
}

Step 3: Generate a QRPH code for the account​

Create a Funding Method to generate a persistent QRPH code for this account. The merchant can display this QR at their counter to accept payments.

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -X POST "https://api.partners.nextpay.world/v2/accounts/acct_01HDEF/funding-methods" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "qrph",
    "external_id": "juana-pizza-counter-qr"
  }'

Response​

{
  "id": "fm_01HGHI",
  "account_id": "acct_01HDEF",
  "type": "qrph",
  "status": "active",
  "external_id": "juana-pizza-counter-qr",
  "qr_image_url": "https://api.partners.nextpay.world/v2/accounts/acct_01HDEF/funding-methods/fm_01HGHI/qr",
  "bank_account": {
    "bank_name": "NextPay Partner Bank",
    "account_number": "8823456789",
    "account_name": "NextPay OPC"
  }
}

The qr_image_url is the merchant's permanent QR code. Print it, display it in the app, embed it on an invoice — it stays active until you archive the Funding Method.

Step 4: Check the merchant's balance​

curl -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  "https://api.partners.nextpay.world/v2/accounts/acct_01HDEF/balances"
{
  "available": 0,
  "pending": 0,
  "reserved": 0,
  "currency": "PHP"
}

The account starts at zero. When someone scans the QR and pays, the balance increases and NextAPI sends a webhook.

Complete onboarding flow​

Here's the full automated onboarding as a single function:

async function onboardMerchant(platformUserId, merchantName, email) {
  const auth = 'Basic ' + Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64');

  // 1. Create merchant
  const merchantRes = await fetch('https://api.partners.nextpay.world/v2/merchants', {
    method: 'POST',
    headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      name: merchantName,
      external_id: `merchant-${platformUserId}`,
      contact_email: email,
    }),
  });
  const merchant = await merchantRes.json();

  // 2. Create account
  const accountRes = await fetch('https://api.partners.nextpay.world/v2/accounts', {
    method: 'POST',
    headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      merchant_id: merchant.id,
      name: 'Collections',
      external_id: `account-${platformUserId}-collections`,
    }),
  });
  const account = await accountRes.json();

  // 3. Generate QR code
  const qrRes = await fetch(
    `https://api.partners.nextpay.world/v2/accounts/${account.id}/funding-methods`,
    {
      method: 'POST',
      headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
      body: JSON.stringify({ type: 'qrph', external_id: `qr-${platformUserId}` }),
    }
  );
  const fundingMethod = await qrRes.json();

  return {
    merchantId: merchant.id,
    accountId: account.id,
    qrImageUrl: fundingMethod.qr_image_url,
  };
}

What's next?​