Create Payout

Deprecated — Do Not Use

This endpoint is deprecated and will be removed in a future release. It is no longer maintained and may produce unexpected behavior.

Use Payout Intents instead. Payout Intents provide a more reliable, two-step flow with preview, confirmation, smart routing, and full webhook support.

Create a new payout to transfer funds to a beneficiary.

POSThttps://api.zenpays.com/merchant/api/v1/payouts

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation
Content-Type REQUIRED	application/json
X-Idempotency-Key OPTIONAL	Unique key to prevent duplicates

Body Parameters

Parameter	Type	Description
beneficiaryAccount REQUIRED	string	Beneficiary account number (5-100 chars)
beneficiaryName REQUIRED	string	Beneficiary name (2-200 chars)
amount REQUIRED	number	Payout amount (minimum 1)
payoutType REQUIRED	string	Payout type: IMPS, NEFT, RTGS, or UPI
currency OPTIONAL	string	3-character currency code (default: INR)
country OPTIONAL	string	2-character ISO country code
beneficiaryIfsc OPTIONAL	string	IFSC code (for bank transfers in India)
beneficiaryVpa OPTIONAL	string	UPI VPA (required for UPI payouts)
beneficiarySwift OPTIONAL	string	SWIFT code (for international transfers)
beneficiaryBic OPTIONAL	string	BIC code
beneficiaryRoutingNumber OPTIONAL	string	Routing number
beneficiaryEmail OPTIONAL	string	Beneficiary email address
beneficiaryMobile OPTIONAL	string	Beneficiary mobile number
beneficiaryAddress OPTIONAL	string	Beneficiary address
beneficiaryCity OPTIONAL	string	Beneficiary city
beneficiaryState OPTIONAL	string	Beneficiary state
beneficiaryPostalCode OPTIONAL	string	Beneficiary postal code
beneficiaryBankCode OPTIONAL	string	Beneficiary bank code
beneficiaryAccountType OPTIONAL	string	Account type: CHECKING, SAVINGS, or CURRENT
bankName OPTIONAL	string	Bank name
purpose OPTIONAL	string	Purpose of the payout
description OPTIONAL	string	Payout description
customerId OPTIONAL	string	Associated customer ID
webhookUrl OPTIONAL	string	URL for payout status webhooks
metadata OPTIONAL	object	Custom key-value pairs

Payout Types

Type	Description	Supported Countries
IMPS	IMPS transfer	India
NEFT	NEFT transfer	India
RTGS	RTGS transfer	India
UPI	UPI transfer	India

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "payoutId": "pay_xxxxx",
    "merchantId": "mer_xxxxx",
    "amount": 10000,
    "currency": "INR",
    "status": "processing",
    "externalPayoutId": "pout_xxxxx",
    "processingFee": 25,
    "totalDebitedAmount": 10025,
    "estimatedCompletion": "2024-01-15T11:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "metadata": {}
  }
}

Error Responses

Code	HTTP	Message
INVALID_AMOUNT	400	Amount below minimum or above maximum
INVALID_BENEFICIARY	400	Invalid beneficiary details
UNAUTHORIZED	401	Invalid API key
INSUFFICIENT_BALANCE	402	Wallet balance too low
PAYOUT_FAILED	422	Payout processing failed

Examples

cURL

curl -X POST https://api.zenpays.com/merchant/api/v1/payouts \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: payout-order-123" \
  -d '{
    "amount": 10000,
    "currency": "INR",
    "country": "IN",
    "payoutType": "IMPS",
    "beneficiaryAccount": "1234567890",
    "beneficiaryIfsc": "HDFC0001234",
    "beneficiaryName": "John Doe"
  }'

JavaScript

const payout = await fetch('https://api.zenpays.com/merchant/api/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10000,
    currency: 'INR',
    country: 'IN',
    payoutType: 'IMPS',
    beneficiaryAccount: '1234567890',
    beneficiaryIfsc: 'HDFC0001234',
    beneficiaryName: 'John Doe',
  }),
});

SDK

const payout = await zenpays.payouts.create({
  amount: 10000,
  currency: 'INR',
  country: 'IN',
  payoutType: 'IMPS',
  beneficiaryAccount: '1234567890',
  beneficiaryIfsc: 'HDFC0001234',
  beneficiaryName: 'John Doe',
});

console.log(payout.payoutId); // pay_xxxxx

Payout Status

Status	Description
pending	Payout created, awaiting processing
processing	Being processed by TSP
succeeded	Funds transferred successfully
failed	Payout failed
cancelled	Payout was cancelled
reversed	Payout was reversed

Related Endpoints

• Get Payout
• List Payouts
• Preview Payout