API PAY-OUT TRANSACTION

Request

The Pay-Out Transaction API enables merchants to initiate secure and efficient money transfers to various recipients including employees, customers, vendors, and business partners. This API supports multiple Peruvian banking institutions and payment methods for comprehensive disbursement solutions.

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: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 Must be unique across all transactions for the merchant
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 for display purposes Format: UTF-8 encoded string Used for transaction identification and customer display
subMerchantId	O	String	Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for complex merchant hierarchies
subMerchantName	O	String	Sub-merchant business name for display purposes Format: UTF-8 encoded string Used for transaction identification in multi-level structures
money	M	Object	Transaction amount and currency specification Contains payment amount and currency details See Money Model
currency	M	String	ISO 4217 currency code specification Fixed value: PEN (Peruvian Sol) Determines payment processing rules and settlement currency
amount	M	Number	Transaction amount in smallest currency unit Format: Integer value Example: 20000 represents PEN 200.00 Range: 100-999999999
paymentMethod	M	String(6)	Payment method for transaction processing Format: Predefined payment method codes Examples: BCP, INTERBANK, SCOTIABANK_PE See Payment Method List
cashAccount	M	String(32)	Recipient's bank account number Format: Alphanumeric string Maximum length: 32 characters Must be a valid Peruvian bank account number
cashAccountType	M	String(32)	Bank account type specification Format: Predefined account type codes Values: CORRIENTE (Checking), AHORROS (Savings) Determines account type for transaction processing
cci	C	String(20)	Interbank Account Code (CCI) for faster processing Format: 20-digit alphanumeric string Recommended for faster payment processing and reduced transaction delays
receiver	M	Object	Recipient information container Contains recipient identification and contact details See Receiver Model
name	M	String	Recipient's full name for transaction identification Format: UTF-8 encoded string Used for transaction records and recipient verification
email	M	String	Recipient's email address for notifications Format: Valid email address Used for transaction notifications and communication
phone	M	String	Recipient's phone number for contact purposes Format: International phone number format Used for transaction verification and support
idType	M	String	Identity document type specification Format: Predefined identity type codes Values: DNI (National ID), CE (Foreigner ID), PAS (Passport), RUC (Tax ID) Determines identity verification requirements
identity	M	String	Identity document number Format: Alphanumeric string Must match the specified idType format 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 asynchronous transaction notifications

Important Notes

1. Transaction Uniqueness: orderNo must be unique across all transactions for your merchant account
2. Amount Format: All amounts are specified in the smallest currency unit (e.g., 20000 = PEN 200.00)
3. Timezone: All timestamps use UTC-5 (Peru timezone)
4. Bank Account: Must be a valid Peruvian bank account number
5. CCI Code: Recommended for faster processing and reduced delays
6. Identity Types: DNI (National ID), CE (Foreigner ID), PAS (Passport), RUC (Tax ID)

Example Body – Disbursement Request:

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-05:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

{
    "cashAccount": "12532481501",
    "cashAccountType": "CORRIENTE",
    "cci": "12345678901234567890",
    "receiver": {
        "idType": "DNI",
        "identity": "12345678909",
        "name": "Maria Rodriguez Lopez",
        "phone": "51987654321",
        "email": "[email protected]"
    },
    "merchant": {
        "merchantId": "20001"
    },
    "money": {
        "amount": 20000,
        "currency": "PEN"
    },
    "orderNo": "2000102900000000000001",
    "paymentMethod": "BCP",
    "purpose": "Salary payment for March 2024"
}

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: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 identifier Format: Alphanumeric string Same as the orderNo provided in the request Used for transaction tracking and reconciliation
tradeNo	O	String	Internal transaction reference number 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 Indicates the current state of the transaction See Status Model
disbursementTime	M	String	Transaction processing timestamp Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00-05:00 Timezone: UTC-5 (Peru timezone)
merchant	M	Object	Merchant information container Contains merchant identification and account 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 for display purposes Format: UTF-8 encoded string Used for transaction identification and customer display
subMerchantId	O	String	Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for complex merchant hierarchies
subMerchantName	O	String	Sub-merchant business name for display purposes Format: UTF-8 encoded string Used for transaction identification in multi-level structures
accountNo	O	String	Merchant account number for transaction processing Format: Alphanumeric string Used for account identification and balance management
money	M	Object	Transaction amount and currency specification Contains confirmed transaction amount and currency See Money Model
currency	M	String	ISO 4217 currency code specification Fixed value: PEN (Peruvian Sol) Determines payment processing rules and settlement currency
amount	M	Number	Transaction amount in smallest currency unit Format: Integer value Example: 20000 represents PEN 20000 Range: 100-999999999
channel	M	Object	Payment channel information container Contains payment method and processing details See Channel Model
paymentMethod	M	String	Payment method used for transaction processing Format: Predefined payment method codes Example: BCP Indicates the actual payment channel used
cashAccount	M	String	Recipient's bank account number Format: Alphanumeric string Used for transaction verification and processing
accountName	M	String	Recipient's account holder name Format: UTF-8 encoded string Used for transaction verification and recipient identification

Example Body – Transaction Response:

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00-05:00

{
  "code": "00",
  "message": "Successful",
  "orderNo": "2000102900000000000001",
  "tradeNo": "1522000109e998347483949",
  "status": "PROCESSING",
  "disbursementTime": "2020-12-17T10:55:00-05:00",
  "merchant": {
    "merchantId": "20001",
    "merchantName": "test",
    "accountNo": "2000124234782342"
  },
  "money": {
    "currency": "PEN",
    "amount": 20000
  },
  "channel": {
    "paymentMethod": "BCP",
    "cashAccount": "12532481501",
    "accountName": "Maria Rodriguez Lopez"
  }
}

Notification

HTTP Request

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:00 Note: Must be current server time within ±5 minutes
X-SIGNATURE	M	String	Digital signature for request authentication See Callback Signature Verification

Body Parameters

Field	Required	Type	Description
orderNo	M	String	Merchant transaction identifier Format: Alphanumeric string Same as the orderNo provided in the original request Used for transaction tracking and reconciliation
tradeNo	M	String	Internal transaction reference number 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 for display purposes Format: UTF-8 encoded string Used for transaction identification and customer display
subMerchantId	O	String	Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for complex merchant hierarchies
subMerchantName	O	String	Sub-merchant business name for display purposes Format: UTF-8 encoded string Used for transaction identification in multi-level structures
paymentMethod	M	String	Payment method used for transaction processing Format: Predefined payment method codes Example: BCP Indicates the actual payment channel used See Payment Method List
transactionTime	M	String	Transaction processing timestamp Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00-05:00 Timezone: UTC-5 (Peru timezone)
status	M	String	Current transaction processing status Format: Predefined status codes Examples: PROCESSING, SUCCESS, FAILED, CANCELLED Indicates the current state of the transaction See Status Model
money	M	Object	Transaction amount and currency specification Contains confirmed transaction amount and currency See Money Model
currency	M	String	ISO 4217 currency code specification Fixed value: PEN (Peruvian Sol) Determines payment processing rules and settlement currency
amount	M	Number	Transaction amount in smallest currency unit Format: Integer value Example: 20000 represents PEN 20000 Range: 100-999999999

Return

Important Response Requirement

Notification Response: Please return only the string SUCCESS to acknowledge receipt of the notification

{
  "merchantId": "20001",
  "merchantName": "test",
  "money": {
    "amount": 20000,
    "currency": "PEN"
  },
  "orderNo": "2000102900000000000001",
  "status": "SUCCESS",
  "tradeNo": "1522000109e998347483949",
  "transactionTime": "2020-12-17T10:55:00-05:00"
}

SUCCESS