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