Postman Guide

Overview

Postman is an application designed to help with API integration and exploration. Intuitive for different tech skill levels, this is the tool of choice both for experienced developers and no-code enthusiasts to get familiar with our available endpoints, requests, and responses.

Using our Postman Collection, you can start testing our API before you write a single line of code.

Install Postman and TocoPay API Collection

1. Download and install the Postman app (Download here) or use our online Postman project: TocoPay API Postman Project
2. Run In Postman

After following the steps above and opening Postman, you'll see the TocoPay API collection.

🚧

Important

Running calls in Postman for the TocoPay API will not work unless you've properly configured your environment variables.

Environment Selection

TocoPay provides two environments:

• Production: https://api.intqp.com - For real transactions in production environment
• Sandbox: https://api.tocopay.net - For testing and development

Update environment variables

The TocoPay API Postman Collection comes with a built-in TocoPay API boilerplate environment (template).

Step 1: On the top right corner, select No Environment and then choose ToCoPay API Environment.

Step 2: Select the eye icon next to it:

On the next screen, add the following variables:

1. api_key: This is your merchant ID.
2. api_secret: This is the API key you obtained from the merchant management panel.
3. base_url: This should be set to your API base URL
   • Production: https://api.intqp.com
   • Sandbox: https://api.tocopay.net

The result will look something like this:

Making your first request

🚧

Important

This Postman Collection makes use of a pre-request script to automatically generate the signature for every request, which allows you to skip coding the signature process. You can view this script by clicking on the "Pre-request Script" tab within the Collection.

1. The first API you will call is Get merchant profile in your workspace.
2. TocoPay API > Merchant > Get merchant profile
3. An HTTP-200 "OK" response will be shown upon a successful API call.

Authentication Flow

Our API uses MD5 signature authentication:

1. Parameter Collection: Collect all request parameters (including URL query parameters and request body parameters)
2. Remove Signature Field: If the request contains a sign field, remove it first
3. Add Timestamp: Add a timestamp field (Unix timestamp in seconds)
4. Sort Parameters: Sort all parameters alphabetically by key name
5. Build Signature String: Concatenate parameters in key=value& format
6. Add Secret Key: Append &key=your_api_secret to the end of the signature string
7. Generate Signature: Perform MD5 encryption on the signature string and convert to uppercase

Pre-request Script Details

The collection uses a pre-request script that:

1. Validates Environment Variables: Ensures required variables are set
2. Builds Request URL: Constructs the full request path
3. Processes Request Body: Parses JSON request body and replaces variables
4. Generates Signature: Creates signature with request metadata
5. Sets Request Body: Adds signature to the request

Pre-request Script Code

const CryptoJS = require("crypto-js");

// Get environment variables
const apiSecret = pm.variables.get("api_secret");
const apiKey = pm.variables.get("api_key");

// Read current raw JSON body and replace Postman variables
let body = pm.request.body.raw;
body = pm.variables.replaceIn(body);  
let data;

try {
    data = JSON.parse(body);
} catch (e) {
    console.error("Body is not valid JSON:", e);
    return;
}

// Remove existing sign field if present
delete data.sign;

// Add merchant ID if not present
if (!data.uid) {
    data.uid = apiKey;
}

// Add timestamp (in seconds)
data.timestamp = Math.floor(Date.now() / 1000);

// ---- Merge URL query params ----
let queryParams = pm.request.url.query.toObject();
Object.assign(data, queryParams);

// Sort keys alphabetically
const keys = Object.keys(data).sort();

// Build data string in format key=value&
let dataString = "";
keys.forEach(key => {
    const value = data[key];
    if (value !== null && value !== undefined && value !== "") {
        dataString += key + "=" + value + "&";
    }
});
dataString += "key=" + apiSecret;

// Debug output
console.info("debug sign string: ", dataString);

// Generate MD5 hash and convert to uppercase
const sign = CryptoJS.MD5(dataString).toString().toUpperCase();

// Add sign field back to body
data.sign = sign;

// Update request body with new JSON
pm.request.body.update(JSON.stringify(data, null, 2));

Collection Structure

Our Postman collection includes the following main sections:

1. Authentication Related

• Get Merchant Profile: Verify API key and get basic merchant information
• Test Signature: Verify signature algorithm is correct

2. Payment Related

• Create Payment Order: Create a new payment order
• Query Order Status: Query current status of an order
• Cancel Order: Cancel an incomplete order

3. Merchant Related

• Get Balance: Query merchant account balance
• Get Transaction Records: Get historical transaction records
• Withdrawal Request: Apply for withdrawal

4. Callback Testing

• Webhook Test: Test callback notification functionality

Usage Examples

Create Payment Order

1. Select TocoPay API > Payment > Create Payment Order
2. Enter the following parameters in the request body:

{
  "uid": "test1",
  "currency": "VND",
  "bank_id": "6763",
  "orderid": "TEST-202509181510",
  "notify_url": "https://your.domain.com",
  "return_url": "https://your.domain.com",
  "amount": "50000",
  "userip": "127.0.0.1",
  "timestamp": 1758204569,
  "user_name": "",
  "pay_code": "812",
  "custom": "",
  "sign": "FF2A902AEE970062CD239C03CBB07F67"
}

3. Click the Send button
4. The pre-request script will automatically:
   • Add uid (merchant ID)
   • Add timestamp
   • Generate sign signature
5. View the response result

Query Order Status

1. Select TocoPay API > Payment > Query Order Status
2. Enter the order ID in the request body:

{
    "order_id": "ORDER_1234567890"
}

3. Click the Send button
4. View the order status information

Environment Variables Description

Common Issues

1. Signature Verification Failed

• Check if api_secret is correctly set
• Confirm timestamp format is correct (Unix timestamp in seconds)
• Verify parameter sorting is correct

2. Merchant ID Error

• Confirm api_key environment variable is correctly set

3. Request Timeout

• Check network connection
• Confirm API base URL is correct (Production: https://api.intqp.com, Sandbox: https://api.tocopay.net)
• Verify server accessibility

Debugging Tips

1. View Console Output: Check debug information from pre-request script in Postman console
2. Check Request Body: Confirm complete request body after signature generation
3. Verify Environment Variables: Ensure all required environment variables are correctly set
4. Test Signature Algorithm: Use test endpoint to verify signature algorithm

Support

If you encounter any issues while using the Postman collection, please contact our technical support team.