API Documentation — Nexivo Pay

Overview

Integrate secure PayIn collection and PayOut disbursement with high-speed webhooks.

Base API URL

https://nexivopay.pro/api/v1/

Official PHP Integration SDK

Complete boilerplate with PayIn, PayOut, and signed webhook handler.

Download SDK (.zip)

Request & Response Specs

All endpoints require HTTP POST with Content-Type: application/json. Every response is delivered as JSON with standard HTTP status codes.

Authentication

Every request to the API must include these HTTP headers for secure signature validation.

Header Name	Format / Example	Required
`X-API-Key`	Your primary API Key (from Merchant Dashboard)	Yes
`X-Merchant-ID`	Your registered identifier e.g. `M2026XXXXXX`	Yes
`Content-Type`	`application/json`	Yes

Your Secret Key is strictly used for verifying inbound webhook callback signatures and should never be transmitted in API headers.

Example Request Headers

X-API-Key: ak_live_382947190248102948
X-Merchant-ID: M2026E96939
Content-Type: application/json

Payment Channels

Available mobile financial channels and corresponding gateway routing codes.

Provider	Method Code	PayIn	PayOut
bKash	`101`	Active	Active
Nagad	`102`	Active	Active

Settlement currency for all channels is natively fixed to BDT (৳).

PayIn — Create Payment

Initialize a checkout session and redirect the user to the generated payment interface.

POST /api/v1/payin/create

Payload Parameters

Field	Type	Description	Required
`trx_id`	string	Unique reference ID generated by your platform	Yes
`amount`	decimal	Payment amount (Min: ৳100.00, Max: ৳50,000.00)	Yes
`method_code`	integer	`101` = bKash, `102` = Nagad	Yes
`customer_name`	string	Full name of the payer	Yes
`callback_url`	string	Your webhook endpoint for signed instant updates	Yes
`customer_email`	string	Customer email address	Optional
`customer_phone`	string	Customer mobile number	Optional
`return_url`	string	URL to redirect the customer after payment	Optional

Implementation Example (PHP cURL)

$data = [
    'trx_id'        => 'ORDER-' . time(),
    'amount'        => 500.00,
    'method_code'   => 101,
    'customer_name' => 'Tanvir Ahmed',
    'callback_url'  => 'https://yourdomain.com/webhook/payin',
    'return_url'    => 'https://yourdomain.com/payment/success'
];

$ch = curl_init('https://nexivopay.pro/api/v1/payin/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: YOUR_API_KEY',
        'X-Merchant-ID: YOUR_MERCHANT_ID'
    ]
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($response['success']) && !empty($response['data']['payment_url'])) {
    header('Location: ' . $response['data']['payment_url']);
    exit;
}

JSON Success Response (200 OK)

{
    "success": true,
    "message": "Payment request created",
    "data": {
        "transaction_id": "TRX20261013ABC999",
        "trx_id": "ORDER-1791842966",
        "amount": 500.00,
        "currency": "BDT",
        "status": "pending",
        "payment_url": "https://nexivopay.pro/pay/TRX20261013ABC999"
    }
}

PayOut — Withdrawal

Instantly disburse funds to your customer's personal wallet via API.

POST /api/v1/payout/create

Payload Parameters

Field	Type	Description	Required
`trx_id`	string	Your unique withdrawal reference	Yes
`amount`	decimal	Disbursement amount	Yes
`method_code`	integer	`101` = bKash, `102` = Nagad	Yes
`account_number`	string	11-digit recipient mobile wallet number	Yes
`account_name`	string	Full name of the beneficiary account	Yes
`notify_url`	string	Webhook URL for status updates	Yes

JSON Success Response (200 OK)

{
    "success": true,
    "message": "Payout request submitted",
    "data": {
        "transaction_id": "OUT20261013PAY456",
        "trx_id": "WIT-88401",
        "amount": 1000.00,
        "fee": 0.00,
        "net_amount": 1000.00,
        "currency": "BDT",
        "status": "processing",
        "account_number": "017***5678"
    }
}

Check Status

Query the real-time processing status of any PayIn or PayOut request.

POST /api/v1/transaction/status

Request Payload

{
    "trx_id": "ORDER-1791842966"
}

Callback / Webhook

We dispatch an HTTP POST request to your callback URL with an HMAC SHA-256 signature immediately when a transaction status updates.

Always calculate and verify the signature before marking any order as paid. Return HTTP status 200 to acknowledge receipt.

Incoming Webhook Payload

{
    "transaction_id": "TRX20261013ABC999",
    "trx_id": "ORDER-1791842966",
    "type": "payin",
    "amount": 500.00,
    "currency": "BDT",
    "status": "completed",
    "signature": "e4ykY9OKJvjVxvrpOVaDfyQEl4UoLCa5CLAde8TwzDM"
}

Webhook Signature Verification (PHP)

$secretKey = 'YOUR_SECRET_KEY_FROM_MERCHANT_DASHBOARD';$rawInput  = file_get_contents('php://input');
$payload   = json_decode($rawInput, true);

if (!$payload) {
    http_response_code(400);
    exit('Invalid JSON');
}

$expectedSignature = hash('sha256', 
    $payload['transaction_id'] .$payload['trx_id'] . 
    $payload['status'] .$secretKey
);

if (hash_equals($expectedSignature,$payload['signature'] ?? '')) {
    if ($payload['status'] === 'completed') {
        // Credit the customer or fulfill the order
    }
    echo json_encode(['success' => true]);
} else {
    http_response_code(401);
    echo json_encode(['success' => false, 'message' => 'Invalid signature']);
}

Error Codes

Standard error responses returned by the payment gateway API.

Error Code	HTTP Status	Reason
`AUTH_FAILED`	401	Missing or invalid X-API-Key / X-Merchant-ID headers
`INSUFFICIENT_BALANCE`	402	Merchant balance is lower than the requested payout amount
`INVALID_PARAMS`	400	Missing or invalid payload parameters
`DUPLICATE_ORDER`	409	Transaction reference (trx_id) has already been processed
`SERVER_ERROR`	500	Internal gateway error occurred