# Deposit Creation Endpoint

## Deposit creation

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

This endpoint allows you to generate deposit transactions.

#### Headers

| Name              | Type   | Description                                                                    |
| ----------------- | ------ | ------------------------------------------------------------------------------ |
| Content-Type      | string | `application/json`                                                             |
| X-Date            | string | <p>ISO8601 Datetime with Timezone: <br><code>yyyy-MM-dd'T'HH:mm:ssZ</code></p> |
| X-Login           | string | Merchant X-Login API Key                                                       |
| Authorization     | string | Authorization control hash                                                     |
| X-Idempotency-Key | string | Unique idempotency key                                                         |

#### Request Body

| Name                                                    | Type    | Description                                                                                                                                                                                                  |
| ------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| country<mark style="color:red;">\*</mark>               | string  | <p>(PE) </p><p>Country of deposit</p>                                                                                                                                                                        |
| amount<mark style="color:red;">\*</mark>                | number  | Amount of the deposit                                                                                                                                                                                        |
| invoice\_id<mark style="color:red;">\*</mark>           | string  | <p>(max length: 128) </p><p>(random:  ^\[A-Za-z0-9-\_]\*$ )</p><p>Unique deposit ID by the merchant.</p>                                                                                                     |
| currency<mark style="color:red;">\*</mark>              | string  | <p><strong>(PEN / USD)</strong></p><p>Currency of the deposit</p>                                                                                                                                            |
| request\_payer\_data\_on\_validation\_failure           | boolean | <p>(default:false)</p><p>Flag used to specify whether to ignore error for invalid phone, zip\_code and/or state.</p>                                                                                         |
| payer{}<mark style="color:red;">\*</mark>               | object  | Object containing details of the payer.                                                                                                                                                                      |
| client\_ip                                              | string  | Valid IPv4/v6 Address of the customer                                                                                                                                                                        |
| device\_id                                              | string  | <p>(max length: 100)</p><p>Unique customer's device ID created using our JS library</p>                                                                                                                      |
| back\_url<mark style="color:red;">\*</mark>             | string  | HTTPS URL used to redirect the customer in case of cancelling the deposit                                                                                                                                    |
| success\_url<mark style="color:red;">\*</mark>          | string  | HTTPS URL used to redirect the customer in case of success                                                                                                                                                   |
| error\_url<mark style="color:red;">\*</mark>            | string  | HTTPS URL used to redirect the customer in case of error while generating the payment                                                                                                                        |
| notification\_url<mark style="color:red;">\*</mark>     | string  | HTTPS URL used to send the notifications about deposit's change of status                                                                                                                                    |
| test                                                    | boolean | Mark to indicate that it is a test deposit. If it is sent as **true**, it will not affect the balance of the trade.                                                                                          |
| mobile                                                  | boolean | <p>(default: false)</p><p>The mobile flag is a boolean and has to be sent with the value true if the customer generates the deposit from a mobile device. If it is not sent, the default value is false.</p> |
| payment\_method<mark style="color:red;">\*</mark>       | string  | It must be sent with the value XA/XAQR [<mark style="color:orange;">**(Payment Method)**</mark>](#payment-methods)                                                                                           |
| prayer.last\_name<mark style="color:red;">\*</mark>     | string  | <p>(max length: 128)</p><p>Customer's last\_name</p>                                                                                                                                                         |
| prayer.first\_name<mark style="color:red;">\*</mark>    | string  | <p>(max length: 128)</p><p>Customer's first name</p>                                                                                                                                                         |
| prayer.email<mark style="color:red;">\*</mark>          | string  | <p> (max length: 255)</p><p>Valid customer's email address</p>                                                                                                                                               |
| prayer.document\_type<mark style="color:red;">\*</mark> | string  | <p> (max length: 10)</p><p>Client document type. Optional, if sent it must be a valid value. (Type of document of identy)</p>                                                                                |
| prayer.document<mark style="color:red;">\*</mark>       | string  | <p> (max length: 30)</p><p>Make sure it is correct and that the user cannot change it every time they want to generate a new deposit.</p>                                                                    |
| prayer.id                                               | string  | <p> (max length: 128)</p><p>Customer identifier generated at your end, used to identify customer transactions in the Tupay Panel. If you do not send, we will autogenerate it</p>                            |
| prayer.address.zip\_code                                | string  | <p>(max length: 16)</p><p>Customer's zip code</p>                                                                                                                                                            |
| prayer.address.city                                     | string  | <p>(max length: 128)</p><p>Customer's city</p>                                                                                                                                                               |
| prayer.address.street                                   | string  | <p>(max length: 255)</p><p>Customer's street</p>                                                                                                                                                             |
| prayer.address{}                                        | object  | Object containing customer's address details                                                                                                                                                                 |
| prayer.phone                                            | string  | <p>(max length: 32)</p><p>Valid customer's phone number</p>                                                                                                                                                  |
| fee\_on\_payer                                          | boolean | <p>(default: false)</p><p>Choose whether the deposit fee will be paid by the client or debited from their balance</p>                                                                                        |
| client\_ip                                              | string  | Valid IPv4/v6 client address                                                                                                                                                                                 |
| expiration                                              | number  | Time expiration transactions.                                                                                                                                                                                |

{% tabs %}
{% tab title="201 Deposit request created successfully with ONE\_SHOT Experience" %}

```java
{
    "checkout_type": "ONE_SHOT",
    "redirect_url": "https://payment-stg.tupayonline.com/v1/checkout/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI1NjkzMDY5MSIsImlhdCI6MTcwNzg3ODk1MCwiZXhwIjoxNzA5MTc0OTUwLCJsYW5ndWFnZSI6ImVzIn0.gR5a1bIzgiZ8kUGK5MCFaLmuf_yPzr0tMZs4RCgfEsn6_qYXT7IIWmfAcz3uR3_V/PE/XA/3041/47591",
    "iframe": true,
    "deposit_id": 301178390,
    "merchant_invoice_id": "19574-7770615745349746664",
    "payment_info": {
        "type": "MULTIGATEWAY",
        "payment_method": "XA",
        "payment_method_name": "Tupay",
        "amount": 10.00,
        "currency": "PEN",
        "expiration_date": "2026-05-27 10:49:10",
        "created_at": "2024-02-14 02:49:10",
        "metadata": {
            "reference": 56930691,
            "beneficiary_name": "TUPAY",
            "payment_method_code": "XA"
        },
        "multigateway_metadata": [
            {
                "beneficiaryName": "Tupay",
                "agreement": "A-659374",
                "reference": "56930691",
                "paymentMethodCode": "BC",
                "payerName": "Nombre Apellido",
                "paymentMethodName": "Tupay",
                "paymentMethodType": "BANK_TRANSFER"
            },
            {
                "beneficiaryName": "Tupay",
                "agreement": "A-659374",
                "reference": "56930691",
                "paymentMethodCode": "BP",
                "payerName": "Nombre Apellido",
                "paymentMethodName": "Tupay",
                "paymentMethodType": "BANK_TRANSFER"
            },
            {
                "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAV4AAAFeAQAAAADlUEq3AAAFXUlEQVR42u1bQa6jSgx0xIIlR+Am4WJIROJi5CZ9hCxZIDyuqm6SjPSlv5iNZ14W6OWliITbbZerK+b//3XYD/jfAr/M7PaaR7wbzYaH+dN",
                "subType": "VOUCHER",
                "reference": "56930691",
                "paymentMethodCode": "NQR",
                "paymentMethodName": "TEST",
                "paymentMethodType": "QR_CODE"
            },
            {
                "paymentMethodType": "CREDIT_CARD",
                "redirectUrl": "https://pay-stg.tupayonline.com/validate/bbf7WD95WlaTOrgYqxB2OdBpstWQyq1y",
                "paymentMethodCode": "VI"
            },
            {
                "paymentMethodType": "CREDIT_CARD",
                "redirectUrl": "https://pay-stg.tupayonline.com/validate/Ng58VMecAM3BF5R3K8vJ5jQVH9HRoZKu",
                "paymentMethodCode": "MC"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="400 Deposit request failed due to field validation error" %}

```json
{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.document: Invalid document type and/or document"
    ],
    "type": "BEAN_VALIDATION_ERROR"
}
```

{% endtab %}

{% tab title="401 Invalid signature" %}

```json
{
    "code": 102,
    "description": "Invalid signature",
    "type": "INVALID_SIGNATURE"
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Body parameters marked with \* are required fields.
{% endhint %}

## Response Considerations

{% tabs %}
{% tab title="checkout\_type" %}

| ONE\_SHOT                                                                                                                                                                                                                            | HOSTED                                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| The deposit request was successfully completed in One Shot and the user will be directly presented with the information to complete the payment.                                                                                     | The information sent is missing details required to complete the request. Redirect the customer to our Hosted Checkout to collect those details. |
| Below you will find all the *Required fields* with a checkbox <img src="https://content.gitbook.com/content/9pqDQmo5HSlku7L1tVhp/blobs/9BAciXpgvf9qdWwdy6IJ/Screen%20Shot%202022-11-17%20at%2016.26.49.png" alt="" data-size="line"> | If required fields are missing, the `HOSTED` flow will take place :thumbsup:                                                                     |
| {% endtab %}                                                                                                                                                                                                                         |                                                                                                                                                  |

{% tab title="Iframe" %}
Our redirect\_url tag handles iframe so there is no need to redirect to another tab as it can be handled in the same view.

```
<!DOCTYPE html>
<html>
<head>
    <title>Iframe test</title>
</head>
<body>
    <iframe src=" https://payin.checkoutogate.com/validate/eyJhbGciOiJI
    UzM4NCJ9.eyJqdGkiOiI4NzY1ODgwODYiLCJpYXQiOjE3MDIzMDExODUsImV
    4cCI6MTcwNDg5MzE4NXfjh0.xUOFVMwKFXDFGHfROxTnG9znuI2MI4G6tRVjbso4y1
    PsREiEYL8WSCJ1HEEbi4fsr0Qsde435sdH" 
            width="1200" 
            height="800" 
            frameborder="0" 
            hspace="0"
            width: 100%>
    </iframe>
</body>
</html>
```

{% endtab %}
{% endtabs %}

## Example Request

```json
{
	"country": "PE",
	"currency": "PEN",
	"amount": "100",
	"payment_method": "XA",
	"invoice_id": "65b87bb498fd3002a270a7b3",
	"payer": 
	{
		"email": "client@tupaypagos.com",
		"document": "74586930",
		"document_type": "DNI",
		"last_name": "Gaming last name",
		"first_name": "Gaming",
		"address":{
			"street":"Calle 13",
			"city":"Peru",
			"zip_code":"12345"
			}
	 },
	"expiration": 10,
	"invoice_id": "ID-12394594",
	 "success_url": "https://tupay.2024/admin/page/tupay/pending",
	 "back_url": "https://tupay.2024/admin/page/tupay/pending",
	 "error_url": "https://tupay.2024/admin/page/tupay/fail",
	 "notification_url": "https://47e2a34561/fy/tupay",
	 "client_ip":"1.147.73.157",
	 "fee_on_payer":"false",
	 "device_id":"",
	 "test":"true",
	 "mobile":"false",
	 "request_payer_data_on_validation_failure":"false"
}
```

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

```java
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"country\": \"PE\",\n\t\"currency\": \"PEN\",\n\t\"amount\": \"100\",\n\t\"payment_method\": \"XA\",\n\t\"invoice_id\": \"65b87bb498fd3002a270a7b3\",\n\t\"payer\": \n\t{\n\t\t\"email\": \"client@tupaypagos.com\",\n\t\t\"document\": \"74586930\",\n\t\t\"document_type\": \"DNI\",\n\t\t\"last_name\": \"Gaming last name\",\n\t\t\"first_name\": \"Gaming\",\n\t\t\"address\":{\n\t\t\t\"street\":\"Calle 13\",\n\t\t\t\"city\":\"Peru\",\n\t\t\t\"zip_code\":\"12345\"\n\t\t\t}\n\t },\n\t \"success_url\": \"https://tupay.2024/admin/page/tupay/pending\",\n\t \"back_url\": \"https://tupay.2024/admin/page/tupay/pending\",\n\t \"error_url\": \"https://tupay.2024/admin/page/tupay/fail\",\n\t \"notification_url\": \"https://47e2a34561/fy/tupay\",\n\t \"client_ip\":\"1.147.73.157\",\n\t \"expiration\": 100,\n\t \"fee_on_payer\":\"false\",\n\t \"device_id\":\"\",\n\t \"test\":\"true\",\n\t \"mobile\":\"false\",\n\t \"request_payer_data_on_validation_failure\":\"false\"\n}");
Request request = new Request.Builder()
  .url("https://api-stg.tupayonline.com/v3/deposits")
  .method("POST", body)
  .addHeader("X-Login", "zkSSILAezeTUyIkPxQvS")
  .addHeader("X-Date", "2024-02-19T15:12:54Z")
  .addHeader("Authorization", "D24 210645f9b657ae1d342e4e8e5e8ca3c57e8ce3d067fd512f01d1e826488a593b")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "GCLB=CJ3O2uri78nfAQ")
  .build();
Response response = client.newCall(request).execute();
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const myHeaders = new Headers();
myHeaders.append("X-Login", "zkSSILAezeTUyIkPxQvS");
myHeaders.append("X-Date", "2024-02-19T15:12:54Z");
myHeaders.append("Authorization", "D24 210645f9b657ae1d342e4e8e5e8ca3c57e8ce3d067fd512f01d1e826488a593b");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Cookie", "GCLB=CJ3O2uri78nfAQ");

const raw = JSON.stringify({
  "country": "PE",
  "currency": "PEN",
  "amount": "100",
  "payment_method": "XA",
  "invoice_id": "65b87bb498fd3002a270a7b3",
  "payer": {
    "email": "client@tupaypagos.com",
    "document": "74586930",
    "document_type": "DNI",
    "last_name": "Gaming last name",
    "first_name": "Gaming",
    "address": {
      "street": "Calle 13",
      "city": "Peru",
      "zip_code": "12345"
    }
  },
  "success_url": "https://tupay.2024/admin/page/tupay/pending",
  "back_url": "https://tupay.2024/admin/page/tupay/pending",
  "error_url": "https://tupay.2024/admin/page/tupay/fail",
  "notification_url": "https://47e2a34561/fy/tupay",
  "client_ip": "1.147.73.157",
  "expiration": 100,
  "fee_on_payer": "false",
  "device_id": "",
  "test": "true",
  "mobile": "false",
  "request_payer_data_on_validation_failure": "false"
});

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

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

{% 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("X-Login", "zkSSILAezeTUyIkPxQvS");
request.AddHeader("X-Date", "2024-02-19T15:12:54Z");
request.AddHeader("Authorization", "D24 210645f9b657ae1d342e4e8e5e8ca3c57e8ce3d067fd512f01d1e826488a593b");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Cookie", "GCLB=CJ3O2uri78nfAQ");
var body = @"{" + "\n" +
@"	""country"": ""PE""," + "\n" +
@"	""currency"": ""PEN""," + "\n" +
@"	""amount"": ""100""," + "\n" +
@"	""payment_method"": ""XA""," + "\n" +
@"	""invoice_id"": ""65b87bb498fd3002a270a7b3""," + "\n" +
@"	""payer"": " + "\n" +
@"	{" + "\n" +
@"		""email"": ""client@tupaypagos.com""," + "\n" +
@"		""document"": ""74586930""," + "\n" +
@"		""document_type"": ""DNI""," + "\n" +
@"		""last_name"": ""Gaming last name""," + "\n" +
@"		""first_name"": ""Gaming""," + "\n" +
@"		""address"":{" + "\n" +
@"			""street"":""Calle 13""," + "\n" +
@"			""city"":""Peru""," + "\n" +
@"			""zip_code"":""12345""" + "\n" +
@"			}" + "\n" +
@"	 }," + "\n" +
@"	 ""success_url"": ""https://tupay.2024/admin/page/tupay/pending""," + "\n" +
@"	 ""back_url"": ""https://tupay.2024/admin/page/tupay/pending""," + "\n" +
@"	 ""error_url"": ""https://tupay.2024/admin/page/tupay/fail""," + "\n" +
@"	 ""notification_url"": ""https://47e2a34561/fy/tupay""," + "\n" +
@"	 ""client_ip"":""1.147.73.157""," + "\n" +
@"	 ""expiration"": 100," + "\n" +
@"	 ""fee_on_payer"":""false""," + "\n" +
@"	 ""device_id"":""""," + "\n" +
@"	 ""test"":""true""," + "\n" +
@"	 ""mobile"":""false""," + "\n" +
@"	 ""request_payer_data_on_validation_failure"":""false""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
```

{% 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 =>'{
	"country": "PE",
	"currency": "PEN",
	"amount": "100",
	"payment_method": "XA",
	"invoice_id": "65b87bb498fd3002a270a7b3",
	"payer": 
	{
		"email": "client@tupaypagos.com",
		"document": "74586930",
		"document_type": "DNI",
		"last_name": "Gaming last name",
		"first_name": "Gaming",
		"address":{
			"street":"Calle 13",
			"city":"Peru",
			"zip_code":"12345"
			}
	 },
	 "success_url": "https://tupay.2024/admin/page/tupay/pending",
	 "back_url": "https://tupay.2024/admin/page/tupay/pending",
	 "error_url": "https://tupay.2024/admin/page/tupay/fail",
	 "notification_url": "https://47e2a34561/fy/tupay",
	 "client_ip":"1.147.73.157",
	 "expiration": 100,
	 "fee_on_payer":"false",
	 "device_id":"",
	 "test":"true",
	 "mobile":"false",
	 "request_payer_data_on_validation_failure":"false"
}',
  CURLOPT_HTTPHEADER => array(
    'X-Login: zkSSILAezeTUyIkPxQvS',
    'X-Date: 2024-02-19T15:12:54Z',
    'Authorization: D24 210645f9b657ae1d342e4e8e5e8ca3c57e8ce3d067fd512f01d1e826488a593b',
    'Content-Type: application/json',
    'Cookie: GCLB=CJ3O2uri78nfAQ'
  ),
));

$response = curl_exec($curl);

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

{% endtab %}
{% endtabs %}

## <mark style="color:orange;">Payment methods</mark>

Within the Tupay API, it will be possible to find different payment methods, represented by different payment method codes, these are used to filter exactly which <mark style="color:orange;">**payment\_methods**</mark> they want to show to the end customer. <mark style="color:orange;">**"payment\_method":"XAQR" / "payment\_method":"XA"**</mark>

<table><thead><tr><th width="103.08203125">Log</th><th width="147">Value</th><th>Description</th></tr></thead><tbody><tr><td><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FVMKiqVkJGC7EGiQV531E%2Fimage.png?alt=media&#x26;token=6841d36e-b537-492b-b387-d19036f6d8c5" alt="" data-size="original"></td><td>XA</td><td>The payment method "XA" represents all Tupay payment methods, by using this code, the client will be offered with all the options we offer to make the final payment</td></tr><tr><td><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2Fqk5rQS9AlaT2Jp56o6Jm%2Fimage.png?alt=media&#x26;token=48396eb5-ada3-4853-ad0e-d694dc667c71" alt="" data-size="original"></td><td>XAQR</td><td>By using this code, the end client will be presented with all the options that offer a QR to scan and make the final payment, this is represented in the request as</td></tr><tr><td><img src="https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FMpGbIl799u5X9EMGHstk%252Fimage.png%3Falt%3Dmedia%26token%3D9ff579a2-6137-4ef2-80ea-0c9f44b90f20&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=1f0d4148&#x26;sv=1" alt="" data-size="original"></td><td>XABT</td><td>The ‘XABT’ payment method provides the end user with the payment code for use at all banks and agents.</td></tr><tr><td><img src="https://docs.d24.com/~gitbook/image?url=https%3A%2F%2F773174111-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-M792I7hN0PzC-Sx95CP-887967055%252Fuploads%252FUMgbWA9VFs5ZRfpQCkJH%252Fimage.png%3Falt%3Dmedia%26token%3D82d6951d-7363-4324-bc85-5f51a08edc17&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=6c70bc62&#x26;sv=1" alt="" data-size="original"></td><td>XACC</td><td>By using this code, the end user will be able to pay with visa and mastercard.</td></tr><tr><td><p></p><div><figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FZnrnTWKGWSC3fNS7CkI9%2FYape-Tupay_600x600-dark.svg?alt=media&#x26;token=1193c1f8-1a1e-452f-8d5d-7f3ebcda2ab6" alt=""><figcaption></figcaption></figure></div></td><td>XAYP</td><td>The "XAYP" payment method offers the end user to pay with the approval code from their Yape wallet.</td></tr></tbody></table>

<div><figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FN8h1Oy0Lhi6SvkzOyNxY%2FTupay_PurpleBackground.svg?alt=media&#x26;token=ab7237ab-54e7-4194-9548-bccbf7a3fafe" alt=""><figcaption></figcaption></figure> <figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2Ful513IlS6UHiXM9iLRHN%2FTupay_WhiteBackground.svg?alt=media&#x26;token=4233c504-a65d-47e5-8b62-e0e8c33f5d0a" alt="" width="375"><figcaption></figcaption></figure> <figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FR7PpuBBEd4Unb2y5edrB%2FIcon_Purple.svg?alt=media&#x26;token=2a0d182f-b3ec-4a02-a5b2-890a11a3093c" alt=""><figcaption></figcaption></figure> <figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FfZR7VbiwU6Bt3HHmjWF0%2FIcon_White.svg?alt=media&#x26;token=f3019006-96e6-4182-bd36-a4480382942a" alt=""><figcaption></figcaption></figure></div>

<div><figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FSMjId8hobDSK51ZOub1h%2FQRbytupay-1.svg?alt=media&#x26;token=b3a58e90-c5e5-4181-9827-bab6260dd27d" alt="" width="150"><figcaption></figcaption></figure> <figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FB4Sn2mYYH30Yqhu8X6Yk%2FQRbytupay.svg?alt=media&#x26;token=8a74f59a-60ea-416e-9ed0-0c8cc62f8245" alt="" width="188"><figcaption></figcaption></figure></div>

<div><figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FwzXdPiboHEwOKUwRLY4c%2FTupay%20Boton.svg?alt=media&#x26;token=3fc006a7-6f3a-485f-8680-b92219905028" alt="" width="188"><figcaption></figcaption></figure> <figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2F8a3g5kOq1jbZRcTtyb7f%2FTUPAY%20BOTON.svg?alt=media&#x26;token=6c381b63-5b64-4667-b783-b1f23939e6fb" alt="" width="188"><figcaption></figcaption></figure></div>

<figure><img src="https://3506309250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9pqDQmo5HSlku7L1tVhp%2Fuploads%2FXVVgnCuvBEseMlTR1odG%2FYape-Tupay_600x600-dark.svg?alt=media&#x26;token=30f98ed7-935e-4952-9a1c-408de4277833" alt="" width="150"><figcaption></figcaption></figure>

{% hint style="success" %}
[<mark style="color:green;">DOWNLOAD CASHIER LOGOS</mark>](https://drive.google.com/drive/folders/1cJn1nnULsBkp06Zk9kVH8-rTBfarq3Bx)
{% endhint %}

## <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. "document\_type":"DNI" ,"document":"86970864"

<table><thead><tr><th width="353">document_type (valores)</th><th>document (Longitud de caracteres)</th></tr></thead><tbody><tr><td>PASS</td><td>Min 9 Max 12 digits Alphanumeric</td></tr><tr><td>RUC</td><td>Numeric 11 digits</td></tr><tr><td>CE</td><td>Min 9 Max 12 digits</td></tr><tr><td>DNI</td><td>Numeric 8 digits</td></tr></tbody></table>

## <mark style="color:green;">Error Codes</mark>

We group the error codes into different categories for better understanding.

* `1xx` - Header errors
* `2xx` - Call or trade setup error
* `3xx` - User-specific errors
* `4xx` - Payment errors
* `5xx` - Other errors
* `7xx` -  Internal Errors

<table><thead><tr><th width="150" align="center">API Code</th><th width="150" align="center">HTTP Code</th><th width="264" align="center">Type</th><th width="257">Message</th><th width="321">Description</th></tr></thead><tbody><tr><td align="center">100</td><td align="center">401</td><td align="center"><code>INVALID_CREDENTIALS</code></td><td>Invalid Credentials</td><td>The <code>X-Login</code> you sent is incorrect or it is not yet active</td></tr><tr><td align="center">101</td><td align="center">400</td><td align="center"><code>MISSING_REQUIRED_HEADER</code></td><td>Missing or invalid format for required header {headerName}</td><td>Make sure all the headers are correct. <a href="../technical-aspects#headers">Click here for details</a></td></tr><tr><td align="center">102</td><td align="center">400</td><td align="center"><code>INVALID_SIGNATURE</code></td><td>Invalid signature</td><td>Invalid <code>Authorization</code> signature. <a href="../technical-aspects#authorization-signature">Click here for instructions</a></td></tr><tr><td align="center">103</td><td align="center">400</td><td align="center"><code>INVALID_DATE_RANGE</code></td><td>X-Date header value out of valid range</td><td>The <code>X-Date</code> value you sent in the header is outside the allowed time-frame. <a href="../technical-aspects#x-date">Click here for details</a></td></tr><tr><td align="center">104</td><td align="center">400</td><td align="center"><code>IDEMPOTENCY_KEY_ALREADY_USED</code></td><td>Idempotency key {key} has been already used</td><td>The X-Idempotency-Key you sent has already been used</td></tr><tr><td align="center">105</td><td align="center">400</td><td align="center"><code>EMPTY_HEADER_VALUE</code></td><td>Optional header {headerName} must not be blank</td><td>If an optional header is sent, it can't be blank</td></tr><tr><td align="center">201</td><td align="center">400</td><td align="center"><code>BEAN_VALIDATION_ERROR</code></td><td>Field validation error. Check details</td><td>One or more fields sent were incorrect</td></tr><tr><td align="center">202</td><td align="center">401</td><td align="center"><code>INVALID_IP</code></td><td>Unregistered IP address</td><td>You must whitelist your IP Address. <a href="../technical-aspects#ip-whitelisting">Click here for instructions</a></td></tr><tr><td align="center">203</td><td align="center">429</td><td align="center"><code>VELOCITY_CHECK</code></td><td>Too many consecutive attempts for user (Velocity Check)</td><td>The user has created many deposits in a short period of time</td></tr><tr><td align="center">204</td><td align="center">400</td><td align="center"><code>INVALID_MEDIA_TYPE</code></td><td>Invalid media type</td><td>The payload format is in an unsupported format. Make sure the header <code>Content-Type</code> is <code>application/json</code></td></tr><tr><td align="center">205</td><td align="center">400</td><td align="center"><code>MISSING_REQUEST_PARAMETER</code></td><td>Missing request parameter</td><td>The request is missing an important parameter</td></tr><tr><td align="center">206</td><td align="center">400</td><td align="center"><code>MISSING_PATH_VARIABLE</code></td><td>Missing path variable</td><td>The request is missing an important path variable</td></tr><tr><td align="center">207</td><td align="center">400</td><td align="center"><code>INVALID_REQUEST_PARAMETER_TYPE</code></td><td>Invalid request parameter type</td><td>A parameter type sent was incorrect</td></tr><tr><td align="center">208</td><td align="center">404</td><td align="center"><code>RESOURCE_NOT_FOUND</code></td><td>Resource not found</td><td>The <code>deposit_id</code> being used doesn't exist</td></tr><tr><td align="center">209</td><td align="center">400</td><td align="center"><code>INVALID_REQUEST_BODY</code></td><td>Invalid request body: {details}</td><td>There is a syntax error in the JSON payload</td></tr><tr><td align="center">217</td><td align="center">403</td><td align="center"><code>FORBIDDEN_MERCHANT</code></td><td>Merchant has no authorization to use this API</td><td>Your Merchant Account is not enabled to use this API. Contact your Account Manager for more information</td></tr><tr><td align="center">300</td><td align="center">400</td><td align="center"><code>USER_BLACKLISTED</code></td><td>User blacklisted</td><td>The user is known for committing fraud</td></tr><tr><td align="center">301</td><td align="center">400</td><td align="center"><code>USER_GREYLISTED</code></td><td>User greylisted</td><td>The user is banned because we detected suspicious behavior</td></tr><tr><td align="center">302</td><td align="center">400</td><td align="center"><code>USER_UNAUTHORIZED</code></td><td>User unauthorized</td><td>The user is blocked. For further information go to the "Clients" section on the Tupay Panel</td></tr><tr><td align="center">303</td><td align="center">400</td><td align="center"><code>USER_UNAUTHORIZED_REG_STATUS</code></td><td>User unauthorized due to cadastral situation</td><td>Check the user's cadastral situation</td></tr><tr><td align="center">304</td><td align="center">400</td><td align="center"><code>USER_LIMIT_EXCEEDED</code></td><td>The user limit has been exceeded: {TRANSACTION|DAILY|WEEKLY|MONTHLY}</td><td>Check the user's limit on the Tupay Panel under the "Clients" section</td></tr><tr><td align="center">305</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_RESTRICTED</code></td><td>Restricted payment method type</td><td>The payment type is disallowed for the payer</td></tr><tr><td align="center">400</td><td align="center">400</td><td align="center"><code>INVALID_AMOUNT</code></td><td>Invalid amount. The minimum is USD 2 or equivalent in local currency</td><td>The amount does not reach the minimum limit</td></tr><tr><td align="center">401</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_NOT_FOUND</code></td><td>Payment method not found</td><td>The <code>payment_method</code> code sent isn't correct.</td></tr><tr><td align="center">402</td><td align="center">400</td><td align="center"><code>INVOICE_ALREADY_USED</code></td><td>Invoice already used</td><td>The <code>invoice_id</code> sent has already been used</td></tr><tr><td align="center">404</td><td align="center">400</td><td align="center"><code>ERROR_CREATING_PAYMENT</code></td><td>Payment method provider unavailable</td><td>Our provider is temporarily unavailable. Use a different payment method or try again</td></tr><tr><td align="center">406</td><td align="center">400</td><td align="center"><code>INVALID_ADDRESS</code></td><td>Invalid address</td><td>The <code>address</code> sent is invalid</td></tr><tr><td align="center">407</td><td align="center">400</td><td align="center"><code>INVALID_CITY</code></td><td>Invalid city</td><td>The <code>city</code> sent is invalid</td></tr><tr><td align="center">408</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_LIMIT_EXCEEDED</code></td><td>Payment method limit exceeded</td><td>The <code>amount</code> sent exceeds the provider's payment method limit. Try with a smaller amount</td></tr><tr><td align="center">410</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_MINIMUM_REQUIRED</code></td><td>Payment method minimum required</td><td>The <code>amount</code> sent is smaller than the provider's payment method minimum limit. Try with a bigger amount</td></tr><tr><td align="center">411</td><td align="center">400</td><td align="center"><code>INVALID_USER_DOCUMENT</code></td><td>Invalid user document ID</td><td>The <code>document</code> specified was rejected by the provider itself. Check it is valid</td></tr><tr><td align="center">412</td><td align="center">400</td><td align="center"><code>PAYMENT_METHOD_UNAVAILABLE</code></td><td>Payment Method Unavailable</td><td>The payment method is temporarily unavailable, please try again later</td></tr><tr><td align="center">418</td><td align="center">400</td><td align="center"><code>MISSING_REQUIRED_FIELDS</code></td><td>Missing required fields in order to generate Deposit</td><td>The request is missing a required field. Please check here.</td></tr><tr><td align="center">419</td><td align="center">400</td><td align="center"><code>MISSING_PAYER_ID_OR_DOCUMENT</code></td><td>payer.id or payer.document field is missing</td><td>The request is missing the <code>payer.id</code> or <code>payer.document</code> field and at least one of them is mandatory to create the deposit</td></tr><tr><td align="center">500</td><td align="center">500</td><td align="center"><code>GENERIC_ERROR</code></td><td>Oh no! Something has gone wrong. Please contact a system administrator</td><td>Internal error, please contact support</td></tr><tr><td align="center">720</td><td align="center">400</td><td align="center"><code>MISSING_CONFIGURATION</code></td><td>Missing configuration for merchant account</td><td>Please contact your AM/TAM</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/deposit/deposit-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.