PayOut Form - Tumipay API

Overview

The PayOut Form API for Peru enables secure disbursements to bank accounts and digital wallets through bank transfer methods. The initiate response always includes a form_url for the beneficiary to complete banking data; 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/form`	Initiate PayOut Form transaction
Complete	`POST /api/v1/partial-payout/{uuid}/complete`	Complete beneficiary banking data
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_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	`"johndoe@email.com"`
`full_name`	string	✅	Customer full name	`"John Doe"`
`legal_doc`	string	Optional	Customer’s legal document number	`"12345678"`
`bank`	string	Optional	Destination bank code	`"BCP"`, `"YAPE"`, `"PLIN"`, etc.
`account_number`	string	Optional	Bank account number or wallet ID	`"1234567890123"`
`account_type`	string	Optional	Account type: `AHORRO`, `CORRIENTE`, `WALLET`	`"AHORRO"`
`cci`	string	Optional	Interbank account code (20 digits)	`"12345678912345678910"`

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
`form_url`	string	URL for the beneficiary to complete banking data in the hosted form

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

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/payout/form' \
--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_type": "DNI",
        "phone_code": "51",
        "phone_number": "900000001",
        "email": "johndoe@email.com",
        "full_name": "John Doe"
    }
}'

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"
        },
        "form_url": "https://checkout.tumipay.co/payout/form?uuid=550e8400-e29b-41d4-a716-446655440000"
    }
}

`POST /api/v1/partial-payout/{uuid}/complete`

Use {uuid} from form_url. Headers: Token-Top, Authorization: Basic …, Content-Type: application/json.

Request Parameters — Bank transfer

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"`
`bank`	string	✅	Destination bank code	`"BCP"`
`account_number`	string	✅	Bank account number	`"19171017707056"`
`account_type`	string	✅	`AHORRO` or `CORRIENTE`	`"AHORRO"`
`cci`	string	Conditional	Interbank account code (20 digits)	`"00219117101770705655"`

The cci field is required for traditional bank accounts but optional for digital wallets (YAPE, PLIN, BIM).

Request Parameters — Wallet

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"`
`bank`	string	✅	Wallet code	`"YAPE"`
`account_type`	string	✅	`WALLET`	`"WALLET"`
`phone_number`	string	✅	Registered wallet phone number (9 digits)	`"915579718"`

Response Structure

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)

Examples

cURL — Bank

curl --request POST 'https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/550e8400-e29b-41d4-a716-446655440000/complete' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "legal_doc": "12345678",
    "legal_doc_type": "DNI",
    "bank": "BCP",
    "account_number": "19171017707056",
    "account_type": "AHORRO",
    "cci": "00219117101770705655"
}'

Response Example

{
    "code": "01",
    "status": "SUCCESS",
    "message": "Operacion exitosa",
    "data": {
        "ticket": "1achNGuPvS9B9v6",
        "date": "2025-10-15 17:42:25"
    }
}

Overview

Country Configuration

​Overview

​Key Features

​Quick Reference

​Request Parameters

​Required Fields

​Customer Data Object

​Response Structure

​Success Response

​Data Object

​Transaction Status Flow

​Examples

​Request Example

​Response Example

​POST /api/v1/partial-payout/{uuid}/complete

​Request Parameters — Bank transfer

​Request Parameters — Wallet

​Response Structure

​Data Object

​Examples

​Response Example

Overview

Key Features

Quick Reference

Request Parameters

Required Fields

Customer Data Object

Response Structure

Success Response

Data Object

Transaction Status Flow

Examples

Request Example

Response Example

`POST /api/v1/partial-payout/{uuid}/complete`

Request Parameters — Bank transfer

Request Parameters — Wallet

Response Structure

Data Object

Examples

Response Example