Your First API Call

Make your first authenticated request to the NextAPI in under 5 minutes. By the end of this tutorial, you'll have listed your merchants using the live API.

Prerequisites

• NextAPI sandbox credentials (Client ID and Client Secret). Request sandbox access if you don't have them yet.

Step 1: Understand Authentication

NextAPI uses Basic Authentication. Your credentials are your Client ID and Client Secret, combined and Base64-encoded.

The format is:

Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)

Step 2: Make Your First Request

Let's verify your credentials work by hitting the health endpoint, then list your merchants.

Check API Health

curl -X GET "https://api.partners.nextpay.world/v2/health" \
  -H "Content-Type: application/json"

You should get a 200 OK response confirming the API is available.

List Your Merchants

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual sandbox credentials:

cURL

curl -X GET "https://api.partners.nextpay.world/v2/merchants" \
  -H "Content-Type: application/json" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

Node.js

const credentials = Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64');

const response = await fetch('https://api.partners.nextpay.world/v2/merchants', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${credentials}`,
  },
});

const data = await response.json();
console.log(data);

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.get(
    'https://api.partners.nextpay.world/v2/merchants',
    auth=HTTPBasicAuth('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'),
    headers={'Content-Type': 'application/json'},
)

print(response.json())

Expected Response

{
  "data": [
    {
      "id": "mrc_abc123",
      "display_name": "My Test Merchant",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Step 3: Create a Payout Request

Now let's send money. Create a payout request to disburse funds to a bank account:

cURL

curl -X POST "https://api.partners.nextpay.world/v2/payout-requests" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: my-first-payout-001" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "amount": 10000,
    "description": "Test payout",
    "recipient": {
      "name": "Juan Dela Cruz",
      "bank_code": "BPI",
      "account_number": "1234567890"
    }
  }'

Node.js

const credentials = Buffer.from('YOUR_CLIENT_ID:YOUR_CLIENT_SECRET').toString('base64');

const response = await fetch('https://api.partners.nextpay.world/v2/payout-requests', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${credentials}`,
    'X-Idempotency-Key': 'my-first-payout-001',
  },
  body: JSON.stringify({
    account_id: 'YOUR_ACCOUNT_ID',
    amount: 10000,
    description: 'Test payout',
    recipient: {
      name: 'Juan Dela Cruz',
      bank_code: 'BPI',
      account_number: '1234567890',
    },
  }),
});

const data = await response.json();
console.log(data);

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    'https://api.partners.nextpay.world/v2/payout-requests',
    auth=HTTPBasicAuth('YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET'),
    headers={
        'Content-Type': 'application/json',
        'X-Idempotency-Key': 'my-first-payout-001',
    },
    json={
        'account_id': 'YOUR_ACCOUNT_ID',
        'amount': 10000,
        'description': 'Test payout',
        'recipient': {
            'name': 'Juan Dela Cruz',
            'bank_code': 'BPI',
            'account_number': '1234567890',
        },
    },
)

print(response.json())

Idempotency

Always include an X-Idempotency-Key header for POST requests. This prevents duplicate operations if you need to retry a request. See IDs and Idempotency for more details.

Step 4: Check Payout Status

Use the payout request ID from the response to check its status:

curl -X GET "https://api.partners.nextpay.world/v2/payout-requests/YOUR_PAYOUT_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET"

What's Next?

You've successfully authenticated, listed merchants, and created a payout request.

• Set up webhooks to get real-time notifications: Setup Webhooks
• Understand the payout lifecycle: Payout Lifecycle
• Explore the full API: API Reference
• Learn about wallet structure: Wallet Structure