PayOut - Tumipay API

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	`"johndoe@email.com"`
`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

curl --request POST 'https://api-empresas.staging.topup.com.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": "johndoe@email.com",
        "full_name": "John Doe",
        "bank": "BCP",
        "account_number": "1234567890123",
        "account_type": "AHORRO",
        "cci": "12345678912345678910"
    }
}'

use reqwest::Client;
use serde_json::json;

async fn make_payout_request() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let response = client.post("https://api-empresas.staging.topup.com.co/production/api/v1/payout")
        .header("Token-Top", "your_auth_token")
        .header("Authorization", "Basic your_auth_key")
        .header("Content-Type", "application/json")
        .json(&json!({
            "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": "johndoe@email.com",
                "full_name": "John Doe",
                "bank": "BCP",
                "account_number": "1234567890123",
                "account_type": "AHORRO",
                "cci": "12345678912345678910"
            }
        }))
        .send()
        .await?;

    let response_json: serde_json::Value = response.json().await?;
    println!("{:#?}", response_json);

    Ok(())
}

import axios from 'axios';

const makePayoutRequest = async () => {
  try {
    const response = await axios.post('https://api-empresas.staging.topup.com.co/production/api/v1/payout', {
      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: 'johndoe@email.com',
        full_name: 'John Doe',
        bank: 'BCP',
        account_number: '1234567890123',
        account_type: 'AHORRO',
        cci: '12345678912345678910'
      }
    }, {
      headers: {
        'Token-Top': 'your_auth_token',
        'Authorization': 'Basic your_auth_key',
        'Content-Type': 'application/json'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

makePayoutRequest();

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-empresas.staging.topup.com.co/production/api/v1/payout',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "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": "johndoe@email.com",
        "full_name": "John Doe",
        "bank": "BCP",
        "account_number": "1234567890123",
        "account_type": "AHORRO",
        "cci": "12345678912345678910"
    }
}',
  CURLOPT_HTTPHEADER => array(
    'Token-Top: your_auth_token',
    'Authorization: Basic your_auth_key',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.io.IOException;

public class PayoutRequest {
    public static void main(String[] args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newHttpClient();
        String json = "{ \\"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\\": \\"johndoe@email.com\\", \\"full_name\\": \\"John Doe\\", \\"bank\\": \\"BCP\\", \\"account_number\\": \\"1234567890123\\", \\"account_type\\": \\"AHORRO\\", \\"cci\\": \\"12345678912345678910\\" } }";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api-empresas.staging.topup.com.co/production/api/v1/payout"))
                .header("Token-Top", "your_auth_token")
                .header("Authorization", "Basic your_auth_key")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
    "strings"
)

func main() {
    url := "https://api-empresas.staging.topup.com.co/production/api/v1/payout"
    method := "POST"

    payload := strings.NewReader(`{
        "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": "johndoe@email.com",
            "full_name": "John Doe",
            "bank": "BCP",
            "account_number": "1234567890123",
            "account_type": "AHORRO",
            "cci": "12345678912345678910"
        }
    }`)

    client := &http.Client {}
    req, err := http.NewRequest(method, url, payload)

    if err != nil {
        fmt.Println(err)
        return
    }
    req.Header.Add("Token-Top", "your_auth_token")
    req.Header.Add("Authorization", "Basic your_auth_key")
    req.Header.Add("Content-Type", "application/json")

    res, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer res.Body.Close()

    body, err := ioutil.ReadAll(res.Body)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(string(body))
}

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"
        }
    }
}

​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

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