Deposit Creation Endpoint

Deposit creation

POST 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	ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ
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*	string	(PE) Country of deposit
amount*	number	Amount of the deposit
invoice_id*	string	(max length: 128) (random: ^[A-Za-z0-9-_]*$ ) Unique deposit ID by the merchant.
currency*	string	(PEN / USD) Currency of the deposit
request_payer_data_on_validation_failure	boolean	(default:false) Flag used to specify whether to ignore error for invalid phone, zip_code and/or state.
payer{}*	object	Object containing details of the payer.
client_ip	string	Valid IPv4/v6 Address of the customer
device_id	string	(max length: 100) Unique customer's device ID created using our JS library
back_url*	string	HTTPS URL used to redirect the customer in case of cancelling the deposit
success_url*	string	HTTPS URL used to redirect the customer in case of success
error_url*	string	HTTPS URL used to redirect the customer in case of error while generating the payment
notification_url*	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	(default: false) 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.
payment_method*	string	It must be sent with the value XA/XAQR (Payment Method)
prayer.last_name	string	(max length: 128) Customer's last_name
prayer.first_name	string	(max length: 128) Customer's first name
prayer.email	string	(max length: 255) Valid customer's email address
prayer.document_type	string	(max length: 10) Client document type. Optional, if sent it must be a valid value. (Type of document of identy)
prayer.document	string	(max length: 30) Make sure it is correct and that the user cannot change it every time they want to generate a new deposit.
prayer.id	string	(max length: 128) Customer identifier generated at your end, used to identify customer transactions in the Tupay Panel. If you do not send, we will autogenerate it
prayer.address.zip_code	string	(max length: 16) Customer's zip code
prayer.address.city	string	(max length: 128) Customer's city
prayer.address.street	string	(max length: 255) Customer's street
prayer.address{}	object	Object containing customer's address details
prayer.phone	string	(max length: 32) Valid customer's phone number
fee_on_payer	boolean	(default: false) Choose whether the deposit fee will be paid by the client or debited from their balance

201 Deposit request created successfully with ONE_SHOT Experience

{
    "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"
            }
        ]
    }
}

400 Deposit request failed due to field validation error

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

401 Invalid signature

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

Body parameters marked with * are required fields.

Response Considerations

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	If required fields are missing, the HOSTED flow will take place 👍

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>

Example Request

{
	"country": "PE",
	"currency": "PEN",
	"amount": "100",
	"payment_method": "XA",
	"invoice_id": "65b87bb498fd3002a270a7b3",
	"payer": 
	{
		"email": "[e-mail]",
		"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",
	 "fee_on_payer":"false",
	 "device_id":"",
	 "test":"true",
	 "mobile":"false",
	 "request_payer_data_on_validation_failure":"false"
}

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\": \"[e-mail]\",\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();

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": "[e-mail]",
    "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));

C#

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"": ""[e-mail]""," + "\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);

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": "[e-mail]",
		"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;

Payment methods

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 payment_methods they want to show to the end customer. "payment_method":"XAQR" / "payment_method":"XA"

Value	Description
XA	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
XAQR	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
XABT	The ‘XABT’ payment method provides the end user with the payment code for use at all banks and agents.
XACC	By using this code, the end user will be able to pay with visa and mastercard.

DOWNLOAD CASHIER LOGOS

Identity Document Type Validation

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"

document_type (valores)	document (Longitud de caracteres)
PASS	Min 9 Max 12 digits Alphanumeric
RUC	Numeric 11 digits
CE	Min 9 Max 12 digits
DNI	Numeric 8 digits

Error Codes

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

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