Use NextAPI with Postman

Postman lets you explore and test all NextAPI endpoints interactively before writing code. This guide shows you how to set up Postman with NextAPI's sandbox credentials and make your first requests.

Prerequisites

• Postman installed (desktop app or web)
• Sandbox credentials from /sandbox — your Client ID and Client Secret

Step 1: Import the OpenAPI spec

NextAPI's full API spec is available at the live endpoint. Import it directly into Postman:

1. Open Postman
2. Click Import (top left)
3. Select Link
4. Enter: https://api.partners.nextpay.world/v2/openapi
5. Click Continue → Import

Postman creates a collection with all 36+ endpoints automatically organized by category.

Alternatively, browse the interactive API Reference on this site — each endpoint has a "Try It" panel.

Step 2: Create a sandbox environment

1. In Postman, click Environments → + (New Environment)
2. Name it NextAPI Sandbox
3. Add these variables:

Variable	Initial Value	Notes
base_url	https://api.partners.nextpay.world/v2	Sandbox and production share the same URL
client_id	YOUR_CLIENT_ID	From your sandbox credentials
client_secret	YOUR_CLIENT_SECRET	From your sandbox credentials
merchant_id	(empty)	Fill in after creating a merchant
account_id	(empty)	Fill in after creating an account

4. Click Save
5. Select NextAPI Sandbox from the environment dropdown (top right)

Step 3: Configure Basic Auth

NextAPI uses Basic Auth — your Client ID as the username and Client Secret as the password, Base64-encoded.

Postman handles the encoding automatically:

1. Open any request in the imported collection
2. Click the Authorization tab
3. Set Type to Basic Auth
4. Enter {{client_id}} in the Username field
5. Enter {{client_secret}} in the Password field

To apply this to all requests at once:

1. Click the collection root (e.g., NextPay Partners API v2)
2. Go to Authorization tab
3. Set Type to Basic Auth with {{client_id}} / {{client_secret}}
4. All requests inherit this auth — individual requests can override if needed

Step 4: Make your first request

List merchants (GET, no body required):

1. Open Core - Merchant → List Merchants
2. The URL should show {{base_url}}/v2/merchants
3. Click Send

You'll get a 200 response with an empty merchants array (or your existing sandbox merchants).

Create a merchant:

1. Open Core - Merchant → Create Merchant
2. Switch to the Body tab → raw → JSON
3. Enter:

{
  "name": "Test Merchant",
  "external_id": "test-001",
  "contact_email": "[email protected]"
}

4. Click Send
5. Copy the id from the response → paste into your merchant_id environment variable

Step 5: Chain requests with scripts

Postman's Tests tab lets you save response values to environment variables automatically:

// Add this to the "Tests" tab of the Create Merchant request
const response = pm.response.json();
pm.environment.set('merchant_id', response.id);
pm.test('Merchant created', () => {
  pm.expect(response.status).to.equal('active');
});

Now when you run "Create Merchant", the merchant_id variable updates automatically for subsequent requests.

Similarly for accounts:

// Tests tab of Create Account request
const response = pm.response.json();
pm.environment.set('account_id', response.id);

Step 6: Add the idempotency key

State-changing requests (POST) should include X-Idempotency-Key. In Postman, add it as a header:

1. Open any POST request
2. Go to Headers
3. Add: X-Idempotency-Key → {{$randomUUID}}

The {{$randomUUID}} dynamic variable generates a unique UUID each time you send — perfect for testing without duplicate submissions.

Common request examples

Check account balance

GET {{base_url}}/accounts/{{account_id}}/balances

Create a payment intent

POST {{base_url}}/payment-intents

Body:
{
  "account_id": "{{account_id}}",
  "amount": 10000,
  "description": "Test payment",
  "external_id": "test-pi-001"
}

Create a payout request

POST {{base_url}}/payout-requests

Body:
{
  "account_id": "{{account_id}}",
  "amount": 10000,
  "recipient": {
    "type": "bank_account",
    "bank_code": "BPI",
    "account_number": "1234567890",
    "account_name": "Test Recipient"
  },
  "description": "Test payout",
  "reference": "test-pr-001"
}

Tips

Use the Collection Runner to run a sequence of requests in order — create merchant → create account → generate QR → check balance. Good for testing your full integration flow.

Save successful responses as examples on each request. These show up in the right panel for reference when you forget the response format.

Environment for production: Duplicate your sandbox environment and rename it NextAPI Production. Update client_id and client_secret to your production credentials. Switch environments with one click when ready to go live.

View the raw request: Click the down arrow next to Send → Send and Download to capture the exact HTTP request Postman sends. Useful for debugging auth issues.

Troubleshooting

Problem	Solution
401 Unauthorized	Check client_id and client_secret environment variables are set. Ensure Authorization type is Basic Auth.
422 Unprocessable Entity	Check the request body — a required field may be missing or the amount is 0 or negative.
Empty response	Make sure the NextAPI Sandbox environment is selected (top-right dropdown).
X-Idempotency-Key errors	Use a new unique value for each test run — {{$randomUUID}} handles this automatically.

Related

• Your First API Call — verify auth with cURL first
• Authentication — how Basic Auth works
• API Reference — interactive docs with Try It