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": "323e4567-e89b-12d3-a456-426614174002",
  "name": "Juana Pizza Co.",
  "external_id": "merchant-user-456",
  "contact_email": "[email protected]",
  "status": "active",
  "created_at": "2025-11-15T10:00:00Z"
}

Store the merchant id from the response — 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": "323e4567-e89b-12d3-a456-426614174002",
    "name": "Collections",
    "external_id": "account-user-456-collections"
  }'

Response​

{
  "id": "YOUR_ACCOUNT_UUID",
  "merchant_id": "323e4567-e89b-12d3-a456-426614174002",
  "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/funding-methods" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_UUID",
    "external_id": "juana-pizza-counter-qr",
    "payment_instrument_options": {
      "method_type": "qrph_p2m_reference",
      "method_provider": "ph_netbank"
    }
  }'

Response​

{
  "id": "723e4567-e89b-12d3-a456-426614174006",
  "account_id": "YOUR_ACCOUNT_UUID",
  "external_id": "juana-pizza-counter-qr",
  "status": "enabled",
  "payment_instrument": {
    "id": "823e4567-e89b-12d3-a456-426614174007",
    "method_type": "qrph_p2m_reference",
    "method_provider": "ph_netbank",
    "method_details": {
      "merchant_name": "Juana Pizza Co.",
      "reference_label": "...",
      "routing_account": "..."
    },
    "status": "active",
    "persistence_mode": "persistent",
    "usage_mode": "multiple"
  }
}

The QR code data is in payment_instrument.method_details — use reference_label and routing_account to generate or display the QRPH 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/YOUR_ACCOUNT_UUID/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/funding-methods',
    {
      method: 'POST',
      headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        account_id: account.id,
        external_id: `qr-${platformUserId}`,
        payment_instrument_options: {
          method_type: 'qrph_p2m_reference',
          method_provider: 'ph_netbank',
        },
      }),
    }
  );
  const fundingMethod = await qrRes.json();

  return {
    merchantId: merchant.id,
    accountId: account.id,
    // QR data is in fundingMethod.payment_instrument.method_details
    qrMethodDetails: fundingMethod.payment_instrument?.method_details,
  };
}

What's next?​