Create Settlement

Create a settlement request to withdraw funds to your bank account.

POSThttps://api.zenpayz.com/merchant/api/v1/settlements/create

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

Body Parameters

Parameter	Type	Description
amount REQUIRED	number	Settlement amount
bankAccountId REQUIRED	string	Bank account ID to settle to
description OPTIONAL	string	Description for the settlement
priority OPTIONAL	string	Settlement priority
type OPTIONAL	string	Settlement type
scheduledDate OPTIONAL	string	ISO 8601 date for scheduled settlement

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "settlementId": "stl_xxxxx",
    "merchantId": "mer_xxxxx",
    "amount": 100000,
    "settlementFee": 500,
    "netAmount": 99500,
    "currency": "USD",
    "type": "standard",
    "priority": "normal",
    "status": "PENDING",
    "description": "Monthly settlement",
    "bankAccountId": "ba_xxxxx",
    "scheduledDate": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields

Parameter	Type	Description
settlementId OPTIONAL	string	Unique settlement identifier
merchantId OPTIONAL	string	Merchant identifier
amount OPTIONAL	number	Requested settlement amount
settlementFee OPTIONAL	number	Fee charged for the settlement
netAmount OPTIONAL	number	Amount after fees
currency OPTIONAL	string	ISO 4217 currency code
type OPTIONAL	string	Settlement type
priority OPTIONAL	string	Settlement priority
status OPTIONAL	string	Settlement status
description OPTIONAL	string	Settlement description
bankAccountId OPTIONAL	string	Target bank account
scheduledDate OPTIONAL	string	Scheduled settlement date, if any
createdAt OPTIONAL	string	ISO 8601 creation timestamp

Error Responses

Code	HTTP	Message
INVALID_AMOUNT	400	Amount below minimum
UNAUTHORIZED	401	Invalid API key
INSUFFICIENT_BALANCE	402	Wallet balance too low
BANK_ACCOUNT_NOT_FOUND	404	Bank account doesn't exist

Examples

cURL

curl -X POST https://api.zenpayz.com/merchant/api/v1/settlements/create \
  -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" \
  -d '{
    "amount": 100000,
    "bankAccountId": "ba_xxxxx",
    "description": "Monthly settlement",
    "priority": "normal",
    "type": "standard"
  }'

SDK

const settlement = await zenpays.settlements.create({
  amount: 100000,
  bankAccountId: 'ba_xxxxx',
  description: 'Monthly settlement',
  priority: 'normal',
  type: 'standard',
});

Settlement Status

Status	Description
PENDING	Settlement created, awaiting processing
PROCESSING	Being processed
COMPLETED	Funds transferred to bank
FAILED	Settlement failed
CANCELLED	Settlement was cancelled