# Cashout Creation Endpoint

## Cashout Request

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

This endpoint allows you to generate cashout requests

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

| Name                                                | Type   | Description                                                                                                                                                       |
| --------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| login<mark style="color:red;">\*</mark>             | string | <p>(max length: 32)</p><p> Tupay "Retiros" login key, found in the merchant panel under Configuration -> API Access</p>                                           |
| pass<mark style="color:red;">\*</mark>              | string | Tupay "Withdrawals" Passphrase key, found in the merchant panel under Settings -> API Access.                                                                     |
| external\_id<mark style="color:red;">\*</mark>      | string | <p>(max length: 100)</p><p>Unique cashout ID on the merchant end</p>                                                                                              |
| country<mark style="color:red;">\*</mark>           | string | <p>(PE)</p><p> Retirement country</p>                                                                                                                             |
| amount<mark style="color:red;">\*</mark>            | number | (up to 2 decimal places) Withdrawal amount in the specified currency                                                                                              |
| currency<mark style="color:red;">\*</mark>          | string | <p>(PEN/USD)</p><p> Retirement currency type </p><p>(ISO 4217 format)</p>                                                                                         |
| document\_id<mark style="color:red;">\*</mark>      | string | <p>(max length: 12)</p><p>Document ID of the beneficiary</p>                                                                                                      |
| document\_type<mark style="color:red;">\*</mark>    | string | <p>(max length: 4) </p><p><a href="#identity-document-type-validation"><mark style="color:blue;"><strong>Type of client identity document</strong></mark></a></p> |
| beneficiary\_name<mark style="color:red;">\*</mark> | string | <p>(max length: 100) </p><p>Beneficiary's last name</p>                                                                                                           |
| beneficiary\_lastname                               | string | <p>(max length: 100) </p><p>Beneficiary's last name</p>                                                                                                           |
| bank\_account<mark style="color:red;">\*</mark>     | string | <p>(max length: 20) </p><p>CCI - Interbank Account, numbers only.</p>                                                                                             |
| notification\_url<mark style="color:red;">\*</mark> | string | <p>(max length: 300)</p><p>If the notification URL is different from the one configured in the merchant panel, it can be configured with this parameter</p>       |
| comments                                            | string | <p>(max length: 200)</p><p>Commentaries about the cashout</p>                                                                                                     |
| account\_type<mark style="color:red;">\*</mark>     | string | <p>(C/S)</p><p> "C" Current Account (Checking) "S" Savings account</p>                                                                                            |

{% tabs %}
{% tab title="200 Cashout request successfully created." %}

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

{% endtab %}

{% tab title="401 The credentials specified are incorrect." %}

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

{% endtab %}

{% tab title="412 Error in the data validation." %}

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

{% endtab %}
{% endtabs %}

## <mark style="color:blue;">Example Request</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",
  "phone": "987654321",
  "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;">Identity Document Type Validation</mark>

Within the Tupay API, it will be possible to find different types of identity documents, for this there is validation by the number of digits. <mark style="color:blue;">**"document\_type":"DNI" , "document\_id":"86970864"**</mark>

<table><thead><tr><th width="353">document_type (value)</th><th>document (Character length)</th></tr></thead><tbody><tr><td>PASS</td><td>Numeric 12 digits</td></tr><tr><td>RUC</td><td>Numeric  11 digits</td></tr><tr><td>CE</td><td>Numeric  9 digits</td></tr><tr><td>DNI</td><td>Numeric 8 digits</td></tr></tbody></table>

## Cashout Code for Wallets

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

## **Cashout Rejection Error Codes**

&#x20;The error information is the one (if) provided by the Bank.

<table><thead><tr><th width="98.33333333333331">Code</th><th width="315">Name</th><th>Description</th></tr></thead><tbody><tr><td>800</td><td><code>ERROR_ACCOUNT_INCORRECT</code></td><td> Invalid bank account</td></tr><tr><td>801</td><td><code>ERROR_ACCOUNT_CLOSED</code></td><td>Bank account is closed</td></tr><tr><td>802</td><td><code>ERROR_AMOUNT_INCORRECT</code></td><td>Invalid amount</td></tr><tr><td>803</td><td><code>ERROR_BANK_INVALID</code></td><td>Invalid bank code</td></tr><tr><td>804</td><td><code>ERROR_BANK_BRANCH_INCORRECT</code></td><td>Invalid bank branch</td></tr><tr><td>805</td><td><code>ERROR_BENEFICIARY_DOCUMENT_ID_INVALID</code></td><td>Invalid beneficiary document</td></tr><tr><td>806</td><td><code>ERROR_BENEFICIARY_NAME_INCORRECT</code></td><td>Beneficiary name doesn't match bank details</td></tr><tr><td>807</td><td><code>ERROR_REJECTED_BY_BANK</code></td><td>Rejected by bank</td></tr><tr><td>808</td><td><code>ERROR_OTHER</code></td><td>Other error</td></tr><tr><td>809</td><td><code>WITHDRAWAL_EXPIRED</code></td><td>Withdrawal expired</td></tr><tr><td>810</td><td><code>LIMIT_EXCEEDED</code></td><td>Beneficiary limit exceeded</td></tr><tr><td>811</td><td><code>RISK_POLICY</code></td><td>Violates bank risk policy</td></tr><tr><td>812</td><td><code>BLOCKED_FROZEN_ACCOUNT</code></td><td>Bank account blocked/frozen</td></tr><tr><td>813</td><td><code>DOCUMENT_ACCOUNT_MISMATCH</code></td><td>Beneficiary document doesn't match bank details</td></tr><tr><td>816</td><td><code>INVALID_ACCOUNT_OR_IFSC_CODE</code> </td><td>Invalid bank account or IFSC code</td></tr><tr><td>818</td><td><code>ACCOUNT_UNABLE</code></td><td>The bank account is unable to receive transfers</td></tr></tbody></table>

## **Cashout Internal Error Codes**

<table><thead><tr><th width="91">Code</th><th>Description</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="broken-reference"> </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>


---

# 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/english/api-documentation/cashout/cashout-creation-endpoint.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.