Confirm Payout Intent

Submit the required fields to confirm and execute a payout intent.

POSThttps://api.zenpayz.com/payment/api/v1/payout-intents/{intentId}/confirm

Bearer · API key

Request

Path Parameters

Parameter	Type	Description
intentId REQUIRED	string	Payout intent ID

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

The body should contain the fields listed in the requiredFields array from the create intent response. Always check requiredFields — the exact fields vary by currency, country, and the TSP selected by smart routing.

Always use requiredFields

When you create a payout intent, the response includes a requiredFields array that tells you exactly which fields are needed to confirm. Some fields may be required for one currency but optional for another. Never hardcode assumptions — always read requiredFields from the create response.

Fiat Payout Fields

Parameter	Type	Description
beneficiaryAccount OPTIONAL	string	Bank account number (5-34 characters)
beneficiaryEmail OPTIONAL	string	Beneficiary email address
beneficiaryBankCode OPTIONAL	string	Bank code in Sulifu format (e.g. dp_axisbank_in, dp_hdfcbank_in, dp_sboi_in)
beneficiaryIfsc OPTIONAL	string	IFSC code for Indian banks (e.g. HDFC0001234)
beneficiaryName OPTIONAL	string	Full name of the beneficiary
beneficiaryMobile OPTIONAL	string	Beneficiary phone number with country code
beneficiaryAddress OPTIONAL	string	Street address
beneficiaryCity OPTIONAL	string	City
beneficiaryState OPTIONAL	string	State or province
beneficiaryPostalCode OPTIONAL	string	Postal/ZIP code
beneficiaryAccountType OPTIONAL	string	Account type: CHECKING or SAVINGS
beneficiaryDocumentId OPTIONAL	string	Government-issued document ID (required in some regions)

Crypto Payout Fields

Parameter	Type	Description
chain OPTIONAL	string	Blockchain network: tron, ethereum, bitcoin, solana, etc.
walletAddress OPTIONAL	string	Destination wallet address
walletMemo OPTIONAL	string	Memo or destination tag (for XRP, XLM, etc.)

Common Optional Fields

Parameter	Type	Description
customerId OPTIONAL	string	Customer ID for tracking
customerEmail OPTIONAL	string	Customer email
customerPhone OPTIONAL	string	Customer phone number

Example: INR Bank Transfer

For INR payouts, the following fields are typically required:

{
  "beneficiaryAccount": "1234567890",
  "beneficiaryEmail": "rajesh@example.com",
  "beneficiaryBankCode": "dp_axisbank_in",
  "beneficiaryAddress": "123 Main Street",
  "beneficiaryCity": "Mumbai",
  "beneficiaryState": "Maharashtra",
  "beneficiaryPostalCode": "400001",
  "beneficiaryName": "Rajesh Kumar",
  "beneficiaryMobile": "+919876543210",
  "beneficiaryIfsc": "HDFC0001234"
}

Example: Crypto (USDT) Payout

{
  "chain": "tron",
  "walletAddress": "TXyz123abc456def789ghi"
}

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "intentId": "poi_mnblh1o5_e8190e32",
    "status": "processing",
    "payoutId": "payout_1774778823937_17298d89",
    "externalPayoutId": "po6efbc8502da51774842226226",
    "amount": "100.00000000",
    "currency": "INR",
    "processingFee": "0.00000000",
    "totalDebitedAmount": "100.00000000",
    "confirmedAt": "2026-03-29T10:07:05.144Z"
  },
  "message": "Payout intent confirmed",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2026-03-29T10:07:05.148Z",
    "processing_time_ms": 1515,
    "api_version": "v1",
    "endpoint": "POST /payout-intents/{intentId}/confirm",
    "user_type": "merchant"
  }
}

Response Fields

Parameter	Type	Description
intentId OPTIONAL	string	The payout intent ID
status OPTIONAL	string	Intent status (processing)
payoutId OPTIONAL	string	Internal payout ID for tracking
externalPayoutId OPTIONAL	string	TSP transaction ID — use this to match with webhook callbacks
amount OPTIONAL	string	Payout amount
currency OPTIONAL	string	Payout currency
processingFee OPTIONAL	string	Processing fee charged
totalDebitedAmount OPTIONAL	string	Total amount debited from wallet (amount + fee)
confirmedAt OPTIONAL	string	ISO 8601 timestamp of confirmation

Linking confirm response to webhooks

The externalPayoutId in the confirm response matches the transactionId in webhook callbacks. Use this to link the payout intent confirmation to the webhook status updates:

• Confirm response: intentId + payoutId + externalPayoutId
• Webhook callback: intentId + payoutId + transactionId (same as externalPayoutId)

Error Responses

Code	HTTP	Message
PAYOUT_INTENT_CONFIRM_FAILED	400	Missing required fields, expired intent, or insufficient wallet balance
VALIDATION_ERROR	400	Invalid field values (e.g. unsupported bank code)
NOT_FOUND	404	Intent not found or does not belong to this merchant

Common Errors

• "Required bank_code in extra field" — You're missing beneficiaryBankCode in your confirmation payload. Check requiredFields from the create response.
• "Beneficiary address fields required" — For non-USDT payouts, address fields (beneficiaryAddress, beneficiaryCity, beneficiaryState, beneficiaryPostalCode) are mandatory.
• "Unsupported bank code" — Use the ZenPays bank code format: dp_{bankname}_in (e.g. dp_hdfcbank_in, dp_axisbank_in, dp_sboi_in). The available codes are listed in the options array of the beneficiaryBankCode field in requiredFields.

Examples

cURL

curl -X POST "https://api.zenpayz.com/payment/api/v1/payout-intents/poi_mnblh1o5_e8190e32/confirm" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2026-03-29T10:07:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryAccount": "1234567890",
    "beneficiaryEmail": "rajesh@example.com",
    "beneficiaryBankCode": "dp_axisbank_in",
    "beneficiaryAddress": "123 Main Street",
    "beneficiaryCity": "Mumbai",
    "beneficiaryState": "Maharashtra",
    "beneficiaryPostalCode": "400001",
    "beneficiaryName": "Rajesh Kumar",
    "beneficiaryMobile": "+919876543210",
    "beneficiaryIfsc": "HDFC0001234"
  }'

JavaScript

const response = await fetch(
  'https://api.zenpayz.com/payment/api/v1/payout-intents/poi_mnblh1o5_e8190e32/confirm',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Secret-Salt': secretSalt,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      beneficiaryAccount: '1234567890',
      beneficiaryEmail: 'rajesh@example.com',
      beneficiaryBankCode: 'dp_axisbank_in',
      beneficiaryAddress: '123 Main Street',
      beneficiaryCity: 'Mumbai',
      beneficiaryState: 'Maharashtra',
      beneficiaryPostalCode: '400001',
      beneficiaryName: 'Rajesh Kumar',
      beneficiaryMobile: '+919876543210',
      beneficiaryIfsc: 'HDFC0001234',
    }),
  }
);

const result = await response.json();
console.log(result.data.payoutId); // 'payout_xxxxx'
console.log(result.data.status);   // 'processing'

SDK

const result = await zenpays.payouts.confirmPayoutIntent('poi_mnblh1o5_e8190e32', {
  beneficiaryAccount: '1234567890',
  beneficiaryEmail: 'rajesh@example.com',
  beneficiaryBankCode: 'dp_axisbank_in',
  beneficiaryAddress: '123 Main Street',
  beneficiaryCity: 'Mumbai',
  beneficiaryState: 'Maharashtra',
  beneficiaryPostalCode: '400001',
  beneficiaryName: 'Rajesh Kumar',
  beneficiaryMobile: '+919876543210',
  beneficiaryIfsc: 'HDFC0001234',
});

console.log(result.payoutId); // 'payout_xxxxx'
console.log(result.status);   // 'processing'

Related Endpoints

• Create Payout Intent
• Get Payout Intent
• List Payout Intents
• Cancel Payout Intent