> ## Documentation Index
> Fetch the complete documentation index at: https://docs.v2.topup.com.co/llms.txt
> Use this file to discover all available pages before exploring further.

# PayOut Form

> Country-specific information for PayOut Form transactions in Peru.

## 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

<CodeGroup dropdown>
  ```bash cURL theme={null}
  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"
      }
  }'
  ```

  ```rust Rust theme={null}
  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(())
  }
  ```

  ```typescript TypeScript theme={null}
  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 PHP theme={null}
  <?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;
  ```

  ```java Java theme={null}
  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());
      }
  }
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
    "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"` |

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

### 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

<CodeGroup dropdown>
  ```bash cURL — Bank theme={null}
  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"
  }'
  ```

  ```bash cURL — Wallet theme={null}
  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"
  }'
  ```

  ```rust Rust theme={null}
  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(())
  }
  ```

  ```typescript TypeScript theme={null}
  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 PHP theme={null}
  <?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;
  ```

  ```java Java theme={null}
  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());
      }
  }
  ```

  ```go Go theme={null}
  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))
  }
  ```
</CodeGroup>

### Response Example

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