# Endpoint Creación

## Endpoint Creación

<mark style="color:green;">`POST`</mark> `https://api-stg.tupayonline.com/v3/cashout`

#### Headers

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control signature  |

#### Request Body

<table><thead><tr><th width="153.34765625">Name</th><th width="89.3125">Type</th><th>Description</th></tr></thead><tbody><tr><td>login<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 32) </p><p>Tupay "Retiros" login key, encontrada en el merchant panel bajo Configuración -> API Access. </p></td></tr><tr><td>pass<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 32) </p><p>Tupay "Retiros" Passphrase key, encontrada en el merchant panel bajo Configuracion -> API Access. </p></td></tr><tr><td>bank_account<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 20)</p><p>CCI - Cuenta Interbancaria, únicamente números.</p></td></tr><tr><td>account_type<mark style="color:red;">*</mark></td><td>string</td><td><p>(C/S)</p><p>"C" Cuenta Corriente (Checking)<br>"S" Cuenta de ahorros (Savings)</p></td></tr><tr><td>amount<mark style="color:red;">*</mark></td><td>decimal</td><td><p>(hasta 2 decimales)</p><p>Monto del retiro en la moneda especificada</p></td></tr><tr><td>currency<mark style="color:red;">*</mark></td><td>string </td><td><p>(PEN / USD)</p><p>Tipo de moneda del Retiro <br>(<em>ISO 4217</em> format)</p></td></tr><tr><td>document_type<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 4)</p><p><a href="#validacion-de-tipo-de-documento-de-identidad"><mark style="color:blue;"><strong>Tipo de documento de Identidad del cliente</strong></mark> </a></p></td></tr><tr><td>country<mark style="color:red;">*</mark></td><td>string</td><td><p><strong>(PE)</strong></p><p>País del retiro</p></td></tr><tr><td>beneficiary_name</td><td>string</td><td><p>(max length: 100)</p><p>Apellido del beneficiario</p></td></tr><tr><td>beneficiary_lastname<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 100)</p><p>Nombre del beneficiario</p></td></tr><tr><td>phone</td><td>string</td><td>Número de teléfono</td></tr><tr><td>comments</td><td>string</td><td><p>(max length: 200)</p><p>Comentarios</p></td></tr><tr><td>notification_url</td><td>string</td><td><p>(max length: 300)</p><p>Si la URL de notificación es distinta a la configurada en el merchant panel, se puede configurar con este parámetro</p></td></tr><tr><td>external_id</td><td>string</td><td><p>(max length: 100)</p><p>ID único para retiros del lado de su lado</p></td></tr><tr><td>document_id<mark style="color:red;">*</mark></td><td>string</td><td><p>(max length: 12)</p><p>Numero de Identidad del cliente.</p></td></tr><tr><td>bank_code</td><td>number</td><td>Código de Billetera.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Solicitud de retiro creada exitosamente." %}

```bash
{
    "cashout_id": "8405147"
}
```

{% endtab %}

{% tab title="401 Las credenciales especificadas son incorrectas." %}

```bash
{
    "code": 401,
    "message": "Invalid credentials."
}
```

{% endtab %}

{% tab title="412 Error en la validación de datos." %}

```bash
{
    "code": 300,
    "message": "bank_account: must not be null; Invalid Bank account"
}
```

{% endtab %}
{% endtabs %}

## <mark style="color:blue;">Request de Ejemplo</mark>

{% tabs %}
{% tab title="Cashout CCI" %}

```json

{
  "login": "BcWeAdKs",
  "pass": "OGJSucxztCMEEPTdGPaxvdEzjWEM",
  "account_type": "S",
  "amount": "20",
  "bank_account": "00320001310356642337",
  "beneficiary_lastname": "Gonzales",
  "beneficiary_name": "Alex",
  "country": "PE",
  "currency": "PEN",
  "document_type": "DNI",
  "document_id": "71594743",
  "external_id": "65b3d062f0da510ead84f11d",
  "notification_url": "https://tupaypagos.com/0/notify/tupay",
  "comments":"Comentarios adicionales"
}
```

{% endtab %}

{% tab title="Cashout Wallet" %}

```json

{
  "login": "BcWeAdKs",
  "pass": "OGJSucxztCMEEPTdGPaxvdEzjWEM",
  "account_type": "",
  "bank_account": "",
  "amount": "20",
  "bank_code": "901",
  "beneficiary_lastname": "Gonzales",
  "beneficiary_name": "Alex",
  "country": "PE",
  "currency": "PEN",
  "document_type": "DNI",
  "document_id": "71594743",
  "phone": "987654321",
  "external_id": "65b3d062f0da510ead84f11d",
  "notification_url": "https://tupaypagos.com/0/notify/tupay",
  "comments":"Comentarios adicionales"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Java" %}

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"login\": \"tKoFCFdhgI\",\n    \"pass\": \"7/s!w8@S:hDC2v\",\n    \"external_id\":\"postmanV3Public5321\",\n    \"account_type\": \"DNI\",\n    \"amount\": \"20\",\n    \"bank_account\": \"00320001310356642337\",\n    \"beneficiary_lastname\": \"Gonzales\",\n    \"beneficiary_name\": \"Alex\",\n    \"country\": \"PE\",\n    \"currency\": \"PEN\",\n    \"document_type\": \"DNI\",\n    \"document_id\": \"71594743\",\n    \"notification_url\": \"https://tupaypagos.com/0/notify/tupay\",\n    \"comments\":\"Comentarios adicionales\"\n}");
Request request = new Request.Builder()
  .url("https://api-stg.tupayonline.com/v3/deposits")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Payload-Signature", "af9b8d360fa1adde79db12eb700629a28dcc2b0fb61d7ddbf0b8ecc88d212056")
  .addHeader("Cookie", "GCLB=CLODnJ__1rqLhQE")
  .build();
Response response = client.newCall(request).execute();
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Payload-Signature", "af9b8d360fa1adde79db12eb700629a28dcc2b0fb61d7ddbf0b8ecc88d212056");
myHeaders.append("Cookie", "GCLB=CLODnJ__1rqLhQE");

const raw = JSON.stringify({
  "login": "tKoFCFdhgI",
  "pass": "7/s!w8@S:hDC2v",
  "external_id": "postmanV3Public5321",
  "account_type": "DNI",
  "amount": "20",
  "bank_account": "00320001310356642337",
  "beneficiary_lastname": "Gonzales",
  "beneficiary_name": "Alex",
  "country": "PE",
  "currency": "PEN",
  "document_type": "DNI",
  "document_id": "71594743",
  "notification_url": "https://tupaypagos.com/0/notify/tupay",
  "comments": "Comentarios adicionales"
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://api-stg.tupayonline.com/v3/deposits", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api-stg.tupayonline.com/v3/deposits',
  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 =>'{
    "login": "tKoFCFdhgI",
    "pass": "7/s!w8@S:hDC2v",
    "external_id":"postmanV3Public5321",
    "account_type": "DNI",
    "amount": "20",
    "bank_account": "00320001310356642337",
    "beneficiary_lastname": "Gonzales",
    "beneficiary_name": "Alex",
    "country": "PE",
    "currency": "PEN",
    "document_type": "DNI",
    "document_id": "71594743",
    "notification_url": "https://tupaypagos.com/0/notify/tupay",
    "comments":"Comentarios adicionales"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Payload-Signature: af9b8d360fa1adde79db12eb700629a28dcc2b0fb61d7ddbf0b8ecc88d212056',
    'Cookie: GCLB=CLODnJ__1rqLhQE'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
```

{% endtab %}

{% tab title="C#" %}

```csharp
var options = new RestClientOptions("https://api-stg.tupayonline.com")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/v3/deposits", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Payload-Signature", "af9b8d360fa1adde79db12eb700629a28dcc2b0fb61d7ddbf0b8ecc88d212056");
request.AddHeader("Cookie", "GCLB=CLODnJ__1rqLhQE");
var body = @"{" + "\n" +
@"    ""login"": ""tKoFCFdhgI""," + "\n" +
@"    ""pass"": ""7/s!w8@S:hDC2v""," + "\n" +
@"    ""external_id"":""postmanV3Public5321""," + "\n" +
@"    ""account_type"": ""DNI""," + "\n" +
@"    ""amount"": ""20""," + "\n" +
@"    ""bank_account"": ""00320001310356642337""," + "\n" +
@"    ""beneficiary_lastname"": ""Gonzales""," + "\n" +
@"    ""beneficiary_name"": ""Alex""," + "\n" +
@"    ""country"": ""PE""," + "\n" +
@"    ""currency"": ""PEN""," + "\n" +
@"    ""document_type"": ""DNI""," + "\n" +
@"    ""document_id"": ""71594743""," + "\n" +
@"    ""notification_url"": ""https://tupaypagos.com/0/notify/tupay""," + "\n" +
@"    ""comments"":""Comentarios adicionales""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
```

{% endtab %}
{% endtabs %}

## <mark style="color:blue;">Código de Cashout para Billeteras</mark>

<table><thead><tr><th width="216.44921875">bank_code</th><th>descripcion</th></tr></thead><tbody><tr><td>901</td><td>Yape</td></tr><tr><td>902</td><td>Plin</td></tr><tr><td>921</td><td>Ligo</td></tr><tr><td>776</td><td>Prexpe</td></tr><tr><td>806</td><td>Wayki Caja Cusco</td></tr><tr><td>904</td><td>Bim</td></tr><tr><td>922</td><td>Dale</td></tr><tr><td>55</td><td>Ripley</td></tr><tr><td>775</td><td>Luquea</td></tr></tbody></table>

## <mark style="color:blue;">Validación de Tipo de Documento de Identidad</mark>

Dentro de la API de Tupay, será posible encontrar distintos tipos de documento de identidad, para ello se tiene una validación por la cantidad de dígitos. [<mark style="color:blue;">**"document\_type":"DNI"**</mark>](#user-content-fn-1)[^1] <mark style="color:blue;">**,"**</mark><mark style="color:blue;">**`document_id`**</mark><mark style="color:blue;">**":"86970864"**</mark>

<table><thead><tr><th width="353">document_type (valores)</th><th>document (Longitud de caracteres)</th></tr></thead><tbody><tr><td>PASS</td><td>Numérico 12 dígitos</td></tr><tr><td>RUC</td><td>Numérico 11 dígitos</td></tr><tr><td>CE</td><td>Numérico 9 dígitos</td></tr><tr><td>DNI</td><td>Numérico 8 dígitos</td></tr></tbody></table>

## <mark style="color:blue;">Código de Errores</mark>

### Códigos de error de rechazo de retiro.

<table><thead><tr><th width="105.33333333333331">Codigo</th><th width="245.2265625">Nombre</th><th>Description</th></tr></thead><tbody><tr><td>800</td><td><code>ERROR_ACCOUNT_INCORRECT</code></td><td>Cuenta de banco inválida</td></tr><tr><td>801</td><td><code>ERROR_ACCOUNT_CLOSED</code></td><td>Cuenta de banco cerrada</td></tr><tr><td>802</td><td><code>ERROR_AMOUNT_INCORRECT</code></td><td>Monto invalido</td></tr><tr><td>803</td><td><code>ERROR_BANK_INVALID</code></td><td>Bank code inválido</td></tr><tr><td>804</td><td><code>ERROR_BANK_BRANCH_INCORRECT</code></td><td>Bank branch inválida</td></tr><tr><td>805</td><td><code>ERROR_BENEFICIARY_DOCUMENT_ID_INVALID</code></td><td>Documento del cliente inválido</td></tr><tr><td>806</td><td><code>ERROR_BENEFICIARY_NAME_INCORRECT</code></td><td>Nombre del cliente distinto al de la cuenta bancaria</td></tr><tr><td>807</td><td><code>ERROR_REJECTED_BY_BANK</code></td><td>Rechazado por el banco</td></tr><tr><td>808</td><td><code>ERROR_OTHER</code></td><td>Otro</td></tr><tr><td>809</td><td><code>WITHDRAWAL_EXPIRED</code></td><td>Reitro expirado</td></tr><tr><td>810</td><td><code>LIMIT_EXCEEDED</code></td><td>Limite excedido</td></tr><tr><td>811</td><td><code>RISK_POLICY</code></td><td>Marcado como operación riesgosa por el banco</td></tr><tr><td>812</td><td><code>BLOCKED_FROZEN_ACCOUNT</code></td><td>Cuenta bloqueada/congelada</td></tr><tr><td>813</td><td><code>DOCUMENT_ACCOUNT_MISMATCH</code></td><td>Documento del cliente no coincide</td></tr><tr><td>816</td><td><code>INVALID_ACCOUNT_OR_IFSC_CODE</code></td><td>Cuenta de banco o código IFSC inválidos</td></tr><tr><td>818</td><td><code>ACCOUNT_UNABLE</code></td><td>Esta cuenta no puede recibir transferencias</td></tr><tr><td>819</td><td><code>INVALID_ACCOUNT_TYPE</code></td><td>Tipo de cuenta inválido</td></tr></tbody></table>

### Códigos de error internos de retiro

<table><thead><tr><th width="104">Codigo</th><th>Descripción</th></tr></thead><tbody><tr><td>300</td><td>Invalid params + [param name] + [reason]</td></tr><tr><td>302</td><td>Invalid control string. </td></tr><tr><td>303</td><td>Invalid bank code</td></tr><tr><td>401</td><td>Invalid credentials</td></tr><tr><td>402</td><td>Unregistered IP address (Go to API Access to whitelist the IP in the Merchant Panel)</td></tr><tr><td>502</td><td>Invalid request body  -  Please check that the JSON is well formatted</td></tr><tr><td>504</td><td>User unauthorized due to cadastral situation.</td></tr><tr><td>508</td><td>Limit exceeded: {TRANSACTION|DAILY|MONTHLY|USER MONTHLY QUANTITY}</td></tr><tr><td>509</td><td>Cashout not found with this ID</td></tr><tr><td>510</td><td>Invalid status: cashout is not Pending</td></tr><tr><td>511</td><td>External ID already used</td></tr><tr><td>514</td><td>Insufficient funds</td></tr><tr><td>515</td><td>Invalid user status: {BLACKLISTED|BLOCKED|SUSPENDED}</td></tr><tr><td>518</td><td>Country not available</td></tr><tr><td>519</td><td>Merchant not enabled. Contact your Account Manager</td></tr><tr><td>524</td><td>Invalid Credentials. Contact integration@tupaypagos.com</td></tr><tr><td>525</td><td>Close loop rejection</td></tr><tr><td>526</td><td>Invalid currency</td></tr><tr><td>533</td><td>Invalid Amount. The minimum amount is {currency} {amount} or equivalent in USD</td></tr><tr><td>537</td><td>Could not make the cashout. Contact integration@tupaypagos.com</td></tr><tr><td>538</td><td>Invalid account status: {BLACKLISTED}</td></tr><tr><td>539</td><td>Payout method unavailable. The country and/or bank selected is not available. Please check with your Account Manager</td></tr><tr><td>540</td><td>Beneficiary email or phone is required</td></tr><tr><td>541</td><td>email already used by another beneficiary</td></tr><tr><td>542</td><td>phone already used by another beneficiary</td></tr><tr><td>543</td><td>must be a<a href="/pages/-M8muWcG4tmJbnohBWM5#phone-numbers-validations"> </a>valid phone number</td></tr><tr><td>702</td><td>Could not cancel cashout</td></tr><tr><td>703</td><td>Could not make the cashout. Contact integration@tupaypagos.com</td></tr></tbody></table>

[^1]:


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tupayonline.com/documentacion-de-la-api/tu-payout/endpoint-creacion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.