API PAYOUT
About 6 min
Request
The Pay-Out API enables merchants to initiate secure and efficient disbursement transactions to various stakeholders
including employees, customers, vendors, and partners.
Supported disbursement methods include:
Bank transfers (NEFT, RTGS, IMPS)
UPI transfers
Digital wallets
Other digital payment channels
Request Path:
sandbox:
https://sandbox-gateway.smilepayz.com/v2.0/disbursement/pay-out
production:https://gateway.smilepayz.com/v2.0/disbursement/pay-out
Header Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP content type specification Fixed value: application/json Required for proper request parsing |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+05:30 Note: Must be current server time within ±5 minutes |
| X-SIGNATURE | M | String | Digital signature for request authentication See Signature Generation |
| X-PARTNER-ID | M | String | Unique merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing Please enter merchantID |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String(32) | Unique transaction identifier for merchant tracking Format: Alphanumeric characters only Length: 6-32 characters Must be unique within merchant scope |
| purpose | M | String(64) | Human-readable transaction description Format: UTF-8 encoded string Length: 1-64 characters Used for transaction history and reporting |
| merchant | M | Object | Merchant identification and business information container Contains primary and sub-merchant details Required for transaction routing and settlement |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in payment interface and transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in payment interface and transaction records |
| money | M | Object | Transaction amount and currency specification container Defines payment value and monetary unit Required for payment processing and settlement |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
| paymentMethod | M | String(6) | Payment method specification for Indian disbursement Format: Predefined payment method codes Examples: YES, HDFC, SBI See Payment Method List |
| cashAccount | M | String(32) | Recipient bank account number for disbursement Format: Alphanumeric string Maximum length: 32 characters Used for bank transfer processing |
| ifscCode | M | String(16) | Indian Financial System Code for bank identification Format: 11-character alphanumeric string Examples: YESB0000097, HDFC0000001 Required for Indian bank transfers |
| receiver | M | Object | Recipient information container Contains beneficiary details for disbursement Required for payment processing and compliance |
| name | M | String | Recipient full name for disbursement processing Format: UTF-8 encoded string Used for payment verification and transaction records |
| callbackUrl | O | String(256) | Webhook notification endpoint URL Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Receives real-time transaction status updates |
Important Notes
1. Bank Account Validation: Ensure the cashAccount and ifscCode combination is valid for successful disbursement
2. IFSC Code Requirement: The IFSC code must be exactly 11 characters and correspond to a valid Indian bank branch
3. Currency Specification: All transactions must use INR (Indian Rupee) as the currency
4. Payment Method Support: Only Indian banks and payment methods are supported for disbursement
Example Body – Disbursement Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+05:30
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"ifscCode": "YESB0000097",
"cashAccount": "1234567890",
"merchant": {
"merchantId": "20019"
},
"receiver": {
"name": "testName"
},
"money": {
"amount": 10000,
"currency": "INR"
},
"orderNo": "20019a069b102-455d-41e8-9428-dac",
"paymentMethod": "YES",
"purpose": "Purpose For Disbursement from Java SDK"
}
Response
HTTP Response
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP response content type specification Fixed value: application/json Indicates JSON response format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+05:30 |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| code | M | String | API response status code indicating operation result Format: Two-digit string Success: "00", Error: Other codes Used for programmatic response handling |
| message | M | String | Human-readable response status description Format: UTF-8 encoded string Provides detailed information about the operation result Localized based on request language |
| orderNo | M | String | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction tracking and reconciliation |
| merchant | M | Object | Merchant information container with account details Contains merchant identification and account information See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in payment interface and transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in payment interface and transaction records |
| money | M | Object | Transaction amount details with currency specification Contains confirmed payment amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
| disbursementTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss±HH:mm) Example: 2020-12-17T10:55:00+05:30 Timestamp when disbursement was processed by the system |
| channel | M | Object | Disbursement processing channel details Contains payment method and account information See Channel Model |
| cashAccount | M | String | Recipient bank account number for disbursement Format: Alphanumeric string Maximum length: 32 characters Used for bank transfer processing |
| paymentMethod | M | Number | Payment method specification for Indian disbursement Format: Predefined payment method codes Examples: YES, HDFC, SBI See Payment Method List |
| tradeNo | O | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| status | O | String | Current transaction processing status Format: Predefined status codes Examples: PROCESSING, SUCCESS, FAILED See Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+05:30
{
"channel": {
"cashAccount": "123456789",
"paymentMethod": "YES"
},
"code": "00",
"disbursementTime": "2024-12-13T13:31:11+05:30",
"merchant": {
"accountNo": "21220019202402271029",
"merchantId": "20019",
"merchantName": "20019"
},
"message": "Successful",
"money": {
"amount": 2000,
"currency": "INR"
},
"orderNo": "20019ae81ede6-07bb-4c77-9937-658",
"status": "PROCESSING",
"tradeNo": "122200192412131501111816"
}
Notification/Callback
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP notification content type specification Fixed value: application/json Indicates JSON payload format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+05:30 |
| X-SIGNATURE | M | String | Digital signature for notification verification Format: Base64 encoded signature Used to verify notification authenticity See how to check this value |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction reconciliation and tracking |
| tradeNo | M | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| merchantId | M | String | Primary merchant identifier for transaction routing Format: Alphanumeric string Used for merchant identification and settlement processing |
| merchantName | M | String | Registered merchant business name for display Format: UTF-8 encoded string Shown in transaction records and reports |
| subMerchantId | O | String | Sub-merchant identifier for multi-level structures Format: Alphanumeric string Included when sub-merchant is involved in transaction |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Included when sub-merchant is involved in transaction |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Examples: YES, HDFC, SBI Indicates the actual payment channel used |
| transactionTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss) Timestamp when transaction was completed by payment provider |
| status | M | String | Final transaction processing status Format: Predefined status codes Examples: SUCCESS, FAILED Indicates the final outcome of the transaction See Status Model |
| money | M | Object | Final transaction amount details with currency Contains confirmed payment amount and currency May differ from request amount due to fees or adjustments See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
Return
Important
Notification please return only string SUCCESS
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 10000,
"currency": "INR"
},
"utr": "09787676778",
"orderNo": "2000102900000000000001",
"status": "SUCCESS",
"tradeNo": "1022000109e998347483949",
"transactionTime": "2020-12-17T10:55:00+05:30"
}
SUCCESS