API PAY-OUT TRANSACTION
Sekitar 6 menit
Request
The Pay-Out API enables merchants to initiate disbursement transactions to various recipients including employees, customers, vendors, and partners. This API supports multiple payment methods for secure and efficient money transfers in the Brazilian market.
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-03:00 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 Format: Alphanumeric string (numbers and letters only) Length: 6-32 characters Used for transaction tracking and reference |
| purpose | M | String(64) | Transaction purpose or description Format: UTF-8 encoded string Maximum length: 64 characters Used for transaction identification and reporting |
| merchant | M | Object | Merchant information container Contains merchant identification and business details See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | O | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| money | M | Object | Transaction amount details with currency specification Contains payment amount and currency information See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 100 represents BRL 100.00 Range: 100-999999999 |
| paymentMethod | M | String(6) | Payment method specification Format: Predefined payment method codes Examples: CPF, CNPJ, PHONE, EMAIL, EVP Determines payment processing channel and rules See Payment Method List |
| cashAccount | M | String(32) | Recipient account identifier Format: CPF/CNPJ/phone/email/EVP account number Examples: "12532481501" (CPF), "+5511999999999" (PHONE) Used for fund disbursement to recipient |
| receiver | M | Object | Recipient information container Contains recipient identification and verification details See Receiver Model |
| taxNumber | M | String | Recipient tax identification number Format: CPF (11 digits) or CNPJ (14 digits) Example: "12345678909" Used for recipient verification and compliance |
| callbackUrl | O | String(256) | Webhook notification URL for transaction status updates Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Used for real-time transaction status notifications |
| additionalParam | O | Object | Additional transaction parameters Format: JSON object Contains supplementary transaction details when required |
Example Body – Pay-Out Transaction Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-03:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"additionalParam": {},
"cashAccount": "12532481501",
"receiver": {
"taxNumber": "12345678909"
},
"merchant": {
"merchantId": "20001"
},
"money": {
"amount": 10000,
"currency": "BRL"
},
"orderNo": "2000102900000000000001",
"paymentMethod": "CPF",
"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-03:00 |
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 | Merchant transaction reference number Format: Alphanumeric string Same as the orderNo provided in the request Used for transaction tracking and reference |
| merchant | M | Object | Merchant information container Contains merchant identification and business details See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | O | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| accountNo | O | String | Merchant account number for transaction settlement Format: Alphanumeric string Used for fund allocation and settlement |
| money | M | Object | Transaction amount details with currency specification Contains confirmed transaction amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 100 represents BRL 100.00 Used for precise amount representation |
| disbursementTime | M | String | Transaction creation timestamp Format: yyyy-MM-ddTHH:mm:ss-03:00 (Brazil timezone) Example: 2020-12-17T10:55:00-03:00 Used for transaction timing and audit |
| channel | M | Object | Payment channel information container Contains payment method details and processing information See Channel Model |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Examples: CPF, CNPJ, PHONE, EMAIL, EVP Indicates the actual payment channel used |
| cashAccount | M | String | Recipient account identifier used for disbursement Format: CPF/CNPJ/phone/email/EVP account number Used for fund disbursement to recipient |
| accountName | O | String | Recipient account holder name Format: UTF-8 encoded string Used for recipient identification and verification |
| 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, CANCELLED Indicates the current state of the transaction See Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-03:00
{
"code": "00",
"message": "Successful",
"orderNo": "2000102900000000000001",
"tradeNo": "1022000109e998347483949",
"status": "PROCESSING",
"disbursementTime": "2020-12-17T10:55:00-03:00",
"merchant": {
"merchantId": "20001",
"merchantName": "test",
"accountNo": "2000124234782342"
},
"money": {
"currency": "BRL",
"amount": 10000
},
"channel": {
"paymentMethod": "CPF",
"cashAccount": "12532481501",
"accountName": "Betty"
}
}
Notification
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP request content type specification Fixed value: application/json Indicates JSON request 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-03:00 |
| X-SIGNATURE | M | String | Digital signature for notification authentication See Callback Signature Verification |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String | Merchant transaction reference number Format: Alphanumeric string Same as the orderNo provided in the request Used for transaction tracking and reference |
| 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 assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | M | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Examples: CPF, CNPJ, PHONE, EMAIL, EVP Indicates the actual payment channel used |
| transactionTime | M | String | Transaction completion timestamp Format: yyyy-MM-ddTHH:mm:ss Example: 2020-12-17T10:55:00-03:00 Used for transaction timing and audit |
| money | M | Object | Transaction amount details with currency specification Contains confirmed transaction amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 100 represents BRL 100.00 Used for precise amount representation |
| status | M | String | Final transaction processing status Format: Predefined status codes Examples: SUCCESS, FAILED, CANCELLED Indicates the final state of the transaction See Status Model |
Return
Important
Notification please return only string SUCCESS
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 10000,
"currency": "BRL"
},
"orderNo": "2000102900000000000001",
"status": "SUCCESS",
"tradeNo": "1022000109e998347483949",
"transactionTime": "2020-12-17T10:55:00-03:00"
}
SUCCESS