Overview
The PayOut API for Peru enables secure disbursements to bank accounts and digital wallets through bank transfer methods. Transactions are processed asynchronously with webhook notifications for status updates.
Key Features
- Bank Transfer Support: Standard
BANK_TRANSFER method
- Currency: Peruvian Sol (
PEN)
- Asynchronous Processing: Background processing with webhook notifications
- Wide Bank Coverage: Support for major Peruvian banks and digital wallets (Yape, Plin, BIM)
- CCI Support: Interbank account code (Código de Cuenta Interbancaria) for transfers
Quick Reference
| Parameter | Value | Description |
|---|
| Endpoint | POST /api/v1/payout | Initiate PayOut transaction |
| Currency | PEN | Peruvian Sol |
| Country Code | PE | Peru |
| Auth Required | Yes | Token-Top + Basic Auth |
| Processing | Async | Status updates via webhook |
Request Parameters
Required Fields
| Field | Type | Description | Example |
|---|
payment_method | string | Disbursement method | "BANK_TRANSFER" |
reference | string | Unique transaction identifier from your system | "3cNPNGbX7meiMppXzVz7g781ysektqq5X" |
amount | float | Transaction amount in PEN | 1.50 (= S/ 1.50 PEN) |
currency | string | Three-letter currency code (ISO 4217) | "PEN" |
country | string | Two-letter country code (ISO 3166-1 alpha-2) | "PE" |
ipn_url | string | Webhook URL for transaction status updates | "http://example.com/tu-webhook" |
customer_data | object | Customer and account information (see below) | - |
Customer Data Object
| Field | Type | Required | Description | Example |
|---|
legal_doc | string | ✅ | Customer’s legal document number | "12345678" |
legal_doc_type | string | ✅ | Document type: DNI, RUC, CE, PPN | "DNI" |
phone_code | string | ✅ | Country calling code | "51" |
phone_number | string | ✅ | Phone number without country code | "900000001" |
email | string | ✅ | Customer email address | "[email protected]" |
full_name | string | ✅ | Customer full name | "John Doe" |
bank | string | ✅ | Destination bank code | "BCP", "YAPE", "PLIN", etc. |
account_number | string | ✅ | Bank account number or wallet ID | "1234567890123" |
account_type | string | ✅ | Account type: AHORRO, CORRIENTE, WALLET | "AHORRO" |
cci | string | Conditional | Interbank account code (20 digits) | "12345678912345678910" |
The cci field is required for traditional bank accounts but optional for digital wallets (YAPE, PLIN, BIM).
Response Structure
Success Response
| Field | Type | Description |
|---|
code | string | Response code ("01" = success) |
status | string | Transaction status ("SUCCESS") |
message | string | Description of the response |
data | object | Transaction data object |
Data Object
| Field | Type | Description |
|---|
ticket | string | Unique transaction identifier (TumiPay ID) |
date | string | Transaction timestamp (YYYY-MM-DD HH:MM:SS) |
transaction | object | Transaction details echo |
Transaction Status Flow
| Status | Description |
|---|
PENDING | Transaction created, processing initiated |
APPROVED | Funds successfully transferred to recipient |
REJECTED | Transaction rejected by bank or validation failure |
Examples
Request Example
curl --request POST 'https://api-empresas.staging.tumipay.co/production/api/v1/payout' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
"payment_method": "BANK_TRANSFER",
"reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
"amount": 150,
"currency": "PEN",
"country": "PE",
"ipn_url": "http://example.com/tu-webhook",
"customer_data": {
"legal_doc": "12345678",
"legal_doc_type": "DNI",
"phone_code": "51",
"phone_number": "900000001",
"email": "[email protected]",
"full_name": "John Doe",
"bank": "BCP",
"account_number": "1234567890123",
"account_type": "AHORRO",
"cci": "12345678912345678910"
}
}'
Response Example
{
"code": "01",
"status": "SUCCESS",
"message": "Operacion exitosa",
"data": {
"ticket": "1achNGuPvS9B9v6",
"date": "2025-10-15 17:42:25",
"transaction": {
"reference": "3cNPNGbX7meiMppXzVz7g781ysektqq5X",
"amount": 150,
"currency": "PEN",
"payment_method": "BANK_TRANSFER"
}
}
}
