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

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

async fn make_payout_form_request() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let response = client.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")
        .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_type": "DNI",
                "phone_code": "51",
                "phone_number": "900000001",
                "email": "johndoe@email.com",
                "full_name": "John Doe"
            }
        }))
        .send()
        .await?;

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

    Ok(())
}

import axios from 'axios';

const makePayoutFormRequest = async () => {
  try {
    const response = await axios.post('https://api-empresas.staging.topup.com.co/production/api/v1/payout/form', {
      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'
      }
    }, {
      headers: {
        'Token-Top': 'your_auth_token',
        'Authorization': 'Basic your_auth_key',
        'Content-Type': 'application/json'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

makePayoutFormRequest();

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-empresas.staging.topup.com.co/production/api/v1/payout/form',
  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_type": "DNI",
        "phone_code": "51",
        "phone_number": "900000001",
        "email": "johndoe@email.com",
        "full_name": "John Doe"
    }
}',
  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 PayoutFormRequest {
    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_type\\": \\"DNI\\", \\"phone_code\\": \\"51\\", \\"phone_number\\": \\"900000001\\", \\"email\\": \\"johndoe@email.com\\", \\"full_name\\": \\"John Doe\\" } }";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("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")
                .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/form"
    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_type": "DNI",
            "phone_code": "51",
            "phone_number": "900000001",
            "email": "johndoe@email.com",
            "full_name": "John Doe"
        }
    }`)

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

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": "YAPE",
    "account_type": "WALLET",
    "phone_number": "915579718"
}'

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

async fn complete_payout_form() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let uuid = "550e8400-e29b-41d4-a716-446655440000";
    let response = client
        .post(format!(
            "https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/{}/complete",
            uuid
        ))
        .header("Token-Top", "your_auth_token")
        .header("Authorization", "Basic your_auth_key")
        .header("Content-Type", "application/json")
        .json(&json!({
            "legal_doc": "12345678",
            "legal_doc_type": "DNI",
            "bank": "BCP",
            "account_number": "19171017707056",
            "account_type": "AHORRO",
            "cci": "00219117101770705655"
        }))
        .send()
        .await?;

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

    Ok(())
}

import axios from 'axios';

const completePayoutForm = async (uuid: string) => {
  try {
    const response = await axios.post(
      `https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/${uuid}/complete`,
      {
        legal_doc: '12345678',
        legal_doc_type: 'DNI',
        bank: 'BCP',
        account_number: '19171017707056',
        account_type: 'AHORRO',
        cci: '00219117101770705655'
      },
      {
        headers: {
          'Token-Top': 'your_auth_token',
          'Authorization': 'Basic your_auth_key',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

<?php
$uuid = '550e8400-e29b-41d4-a716-446655440000';
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/' . $uuid . '/complete',
  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 =>'{
    "legal_doc": "12345678",
    "legal_doc_type": "DNI",
    "bank": "BCP",
    "account_number": "19171017707056",
    "account_type": "AHORRO",
    "cci": "00219117101770705655"
}',
  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 PayoutFormComplete {
    public static void main(String[] args) throws IOException, InterruptedException {
        HttpClient client = HttpClient.newHttpClient();
        String uuid = "550e8400-e29b-41d4-a716-446655440000";
        String json = "{ \\"legal_doc\\": \\"12345678\\", \\"legal_doc_type\\": \\"DNI\\", \\"bank\\": \\"BCP\\", \\"account_number\\": \\"19171017707056\\", \\"account_type\\": \\"AHORRO\\", \\"cci\\": \\"00219117101770705655\\" }";

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/" + uuid + "/complete"))
                .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() {
    uuid := "550e8400-e29b-41d4-a716-446655440000"
    url := "https://api-empresas.staging.topup.com.co/production/api/v1/partial-payout/" + uuid + "/complete"
    method := "POST"

    payload := strings.NewReader(`{
        "legal_doc": "12345678",
        "legal_doc_type": "DNI",
        "bank": "BCP",
        "account_number": "19171017707056",
        "account_type": "AHORRO",
        "cci": "00219117101770705655"
    }`)

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

​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