Create Payout

Send money to recipients via the Payzava Payout API

Create a server-to-server payout to send money to a recipient's MFS account.

Endpoint

POST /payout/create-by-server

Request headers

HeaderRequiredDescription
x-api-keyYesYour API key
x-payout-signatureYesHMAC-SHA256 signature (see below)
Content-TypeYesapplication/json

Generating the signature

The payout signature ensures the request came from your server and has not been tampered with.

Formula

HMAC-SHA256(payoutSecretKey, "{amount}:{merchantRef}:{timestamp}")

Parameters

ParameterDescription
payoutSecretKeyYour payout secret key from the dashboard (Settings → Development Info)
amountThe payout amount (must match the amount in the request body)
merchantRefYour unique reference ID for this payout (must match merchantRef in body)
timestampUnix timestamp in seconds (must be within 5 minutes of server time)

Node.js example

const crypto = require("crypto");

const payoutSecretKey = "your_payout_secret_key";
const amount = 500;
const merchantRef = "ref_001";
const timestamp = Math.floor(Date.now() / 1000);

const message = `${amount}:${merchantRef}:${timestamp}`;
const signature = crypto
  .createHmac("sha256", payoutSecretKey)
  .update(message)
  .digest("hex");

Request body

FieldTypeRequiredDescription
amountnumberYesPayout amount in BDT
merchantRefstringYesYour unique reference for this payout. Used for idempotency.
timestampnumberYesUnix timestamp in seconds (must be within 5 minutes)
recipientNumberstringYesRecipient's mobile number
recipientNamestringNoRecipient's name
descriptionstringNoDescription of the payout
paymentMethodIdstringYesPayment method ID for the recipient's MFS provider

Response

{
  "success": true,
  "data": {
    "payoutId": "payout_xyz789",
    "merchantRef": "ref_001",
    "amount": 500,
    "status": "Processing",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Full example

const axios = require("axios");
const crypto = require("crypto");

// Configuration
const API_KEY = "sk_sandbox_your_api_key";
const PAYOUT_SECRET = "your_payout_secret_key";
const BASE_URL = "https://sandbox.payzava.com/cp/api/v1";

// Payout details
const amount = 500;
const merchantRef = `ref_${Date.now()}`; // Unique reference
const timestamp = Math.floor(Date.now() / 1000);

// Generate signature
const message = `${amount}:${merchantRef}:${timestamp}`;
const signature = crypto
  .createHmac("sha256", PAYOUT_SECRET)
  .update(message)
  .digest("hex");

// Create payout
const response = await axios.post(
  `${BASE_URL}/payout/create-by-server`,
  {
    amount,
    merchantRef,
    timestamp,
    recipientNumber: "01712345678",
    recipientName: "John Doe",
    description: "Withdrawal request #123",
    paymentMethodId: "your_payment_method_id",
  },
  {
    headers: {
      "Content-Type": "application/json",
      "x-api-key": API_KEY,
      "x-payout-signature": signature,
    },
  }
);

console.log("Payout ID:", response.data.data.payoutId);
console.log("Status:", response.data.data.status);

Idempotency

The merchantRef field ensures idempotency. If you send two requests with the same merchantRef, only the first one will create a new payout. The second request will return the existing payout.

Timestamp validation

The timestamp must be within 5 minutes of the server's current time. Requests with timestamps outside this window will be rejected.

IP whitelist

For security, you must whitelist your server's IP address in the dashboard under Settings → Development Info before making server-to-server payout requests.

Sandbox testing

In sandbox mode, trigger payout completion with:

POST /sandbox/trigger-payout

await axios.post(
  "https://sandbox.payzava.com/cp/api/v1/sandbox/trigger-payout",
  { payoutId: "payout_xyz789" },
  { headers: { "x-api-key": "sk_sandbox_your_api_key" } }
);