Endpoint Creación de Depósito

Endpoint Creación de Depósitos

POST https://api-stg.tupayonline.com/v3/deposits

Headers

Name	Type	Description
Content-Type	string	application/json
X-Date*	string	Fecha según el estándar ISO8601 formato: yyyy-MM-dd'T'HH:mm:ssZ
X-Login*	string	X-Login API Key del Comercio
Authorization	string	Hash de control de autorización
X-Idempotency-Key	string	Idempotency key única

Request Body

Name	Type	Description
country*	string	(PE) País del depósito
currency*	string	(PEN / USD) Tipo de Moneda
amount*	number	Monto de depósito
request_payer_data_on_validation_failure	boolean	(default:false) Marca utilizada para especificar si desea ignorar error por phone, zip_code y/o state inválidos.
client_ip	string	Dirección IPv4/v6 válida del cliente
device_id	string	(max length: 100) Identificador único del cliente
back_url	string	HTTPS URL válida usada para redireccionar al usuario.
success_url*	string	HTTPS URL usada para redireccionar al cliente en caso de completarse el depósito
error_url	string	HTTPS URL válida usada para redireccionar al cliente en caso de que ocurra un error a la hora de generar el pago
payment_method*	string	Debe ser enviado con el valor XA/XAQR (Método de Pago)
notification_url*	string	HTTPS URL válida usada para enviar notificaciones sobre los cambios de estado del depósito
test	boolean	Etiqueta para indicar que es un depósito de prueba. Si es enviado como true, no afectará el balance del comercio.
mobile	boolean	(default: false) La marca mobile es un booleano y tiene que ser enviado con el valor true si el cliente genera el deposito desde un dispositivo móvil. Si no es enviado el valor por default es false.
payer{}*	object	Objeto que contiene los detalles del pagador.
prayer.first_name*	string	(max length: 128) Nombre del cliente.
prayer.last_name*	string	(max length: 128) Apellido del cliente.
prayer.phone	string	string (max length: 32) Número de teléfono válido del cliente.
prayer.document*	string	(max length: 30) Asegúrese de que sea correcto y que el usuario no pueda cambiarlo cada vez que desea generar un nuevo depósito.
prayer.email*	string	(max length: 255) Dirección de email válida del cliente.
prayer.document_type	string	(max length: 10) Tipo de documento del cliente. Opcional, en caso de enviar debe ser un valor válido. (Tipo de documento de identidad)
prayer.address{}	object	Objeto conteniendo detalles de la dirección.
prayer.address.zip_code	string	(max length: 16) Código postal del cliente.
prayer.address.city	string	(max length: 128) Ciudad del cliente.
prayer.address.street	string	(max length: 255) Calle del cliente.
fee_on_payer	boolean	(default: false) Elija si la tarifa del depósito será pagada por el cliente o debitada de su saldo
invoice_id*	string	(max length: 128) (random: ^[A-Za-z0-9-_]*$ ) ID de depósito único por parte del merchant.
expiration	number	(max: 2880) Tiempo de expiracion del voucher minutos minimo 1440 y maximo 2880

201 Solicitud de depósito creada exitosamente

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

401: Unauthorized Invalid signature

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

400: Bad Request La solictud de deposito fallo

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

Los parámetros del body que se encuentren con marcas * son campos obligatorios.

Consideraciones de la Respuesta

checkout_type

ONE_SHOT	HOSTED
La creación del depósito fue completada con éxito a partir de su petición, y el usuario verá directamente la información para completar el pago.	La información enviada no es suficiente para crear el depósito, y los datos faltantes deben ser pedidos al usuario. Redirija al usuario a nuestro Hosted Checkout para que solicitemos la información en cuestión.
Debajo encontrarás los campos requeridos con un Checkbox	Si faltan datos para crear el pago, el flujo HOSTED se hará presente 👍

Iframe

Nuestra etiqueta redirect_url maneja iframe por lo tanto no es necesario direccionar a otra pestaña ya que se puede manejar en la misma vista.

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

Request de Ejemplo

{
	"country": "PE",
	"currency": "PEN",
	"amount": "100",
	"payment_method": "XA",
	"payer": 
	{
		"email": "[e-mail]",
		"document": "74586930",
		"document_type": "DNI",
		"last_name": "Gaming last name",
		"first_name": "Gaming"
	 },
	 "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"
}

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-stg.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;

Métodos de Pago

Dentro de la API de Tupay, será posible encontrar distintos métodos de pago, representados por distintos códigos de payment_method, estos son utilizados para filtrar exactamente que métodos de pago quieren mostrarle al cliente final . "payment_method":"XAQR" / "payment_method":"XA"

Valor	Descripción
XA	El método de pago "XA" representa todos los metodos de pago de Tupay,al utilizar este codigo, el cliente sera ofrecido con todas las opciones que ofrecemos para realizar el pago final
XAQR	Al utilizar este codigo, el cliente final sera presentado con todas las opciones que ofrecen un QR para escanear y realizar el pago final, esto es representado en el request como
XABT	El método de pago "XABT" ofrece al usuario final el codigo de pago para utilizar en todas las entidades bancarias y agentes.
XACC	Al utilizar este codigo, el usuario final podrá realizar su pago con tarjeta visa y mastercard.

Validación de Tipo de Documento de Identidad

Dentro de la API de Tupay, será posible encontrar distintos tipo de documento de identidad, para ello se tiene una validación por la cantidad de dígitos. ,"document":"86970864"

document_type (valores)	document (Longitud de caracteres)
PASS	Min 9 Max 12 dígitos Alfanumerico
RUC	Numérico 11 dígitos
CE	Min 9 Max 12 dígitos Alfanumerico
DNI	Numérico 8 dígitos

Códigos de Errores

Agrupamos los códigos de error en diferentes categorías para un mejor entendimiento.

• 1xx - Errores de encabezado

• 2xx - Error en la llamada o de configuración del comercio

• 3xx - Errores del usuario

• 4xx - Errores en la creación del depósito

• 5xx - Otros errores

• 7xx - Errores internos

Código	Código HTTP	Tipo	Mensaje	Descripción
100	401	INVALID_CREDENTIALS	Invalid Credentials	El X-Login enviado es incorrecto o no está activo aún.
101	400	MISSING_REQUIRED_HEADER	Missing or invalid format for required header {headerName}	Asegúrese de que todos los encabezados sean correctos.​
102	400	INVALID_SIGNATURE	Invalid signature	Invalid Authorization signature. Click here for instructions Firma de Authorization inválida​. Revise aquí.
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 El valor X-Date ​enviado en el encabezado está por fuera del marco temporal permitido. Revise aquí.
104	400	IDEMPOTENCY_KEY_ALREADY_USED	Idempotency key {key} has been already used	La X-Idempotency-Key enviada ya ha sido usada.
105	400	EMPTY_HEADER_VALUE	Optional header {headerName} must not be blank	Si un encabezado opcional es enviado, puede venir vacío.
201	400	BEAN_VALIDATION_ERROR	Field validation error. Check details	Uno o más campos son incorrectos.
202	401	INVALID_IP	Unregistered IP address	Debes whitelistear la dirección IP. Revise aquí.​
203	429	VELOCITY_CHECK	Too many consecutive attempts for user (Velocity Check)	El usuario ha creado muchos depósitos en un corto periodo de tiempo.
204	400	INVALID_MEDIA_TYPE	Invalid media type	El formato de la llamada no es soportado. Asegúrse de que el encabezado Content-Type sea application/json
205	400	MISSING_REQUEST_PARAMETER	Missing request parameter	La llamada carece de un parámetro importante.
206	400	MISSING_PATH_VARIABLE	Missing path variable	La llamada carece de una variable importante en la ruta.
207	400	INVALID_REQUEST_PARAMETER_TYPE	Invalid request parameter type	Se ha enviado un tipo de parametro incorrecto.
208	404	RESOURCE_NOT_FOUND	Resource not found	El deposit_id no existe.
209	400	INVALID_REQUEST_BODY	Invalid request body: {details}	Hay un error de sintaxis en el JSON.
217	403	FORBIDDEN_MERCHANT	Merchant has no authorization to use this API	Su comercio no está habilitado a utilizar esa API. Póngase en contacto con su Account Manager.
300	400	USER_BLACKLISTED	User blacklisted	El usuario ha cometido fraude previamente y el depósito fue declinado.
301	400	USER_GREYLISTED	User greylisted	Se ha detectado actividad inusual y hemos bloqueado al usuario.
302	400	USER_UNAUTHORIZED	User unauthorized	El usuario está bloqueado. Para más información acceda a la sección Clients del Tupay Panel.
303	400	USER_UNAUTHORIZED_REG_STATUS	User unauthorized due to cadastral situation	Revise la situación cadastral del usuario.
304	400	USER_LIMIT_EXCEEDED	The user limit has been exceeded: {TRANSACTION|DAILY|WEEKLY|MONTHLY}	Revise los limites del usuario en el Tupay Panel bajo la sección Clients.
305	400	PAYMENT_METHOD_RESTRICTED	Restricted payment method type	El tipo de pago se ha deshabilitado al usuario.
400	400	INVALID_AMOUNT	Invalid amount. The minimum is USD 2 or equivalent in local currency	El monto no ha a alcanzado el mínimo.
401	400	PAYMENT_METHOD_NOT_FOUND	Payment method not found	El payment_method enviado es incorrecto.
402	400	INVOICE_ALREADY_USED	Invoice already used	El invoice_id enviado ya ha sido usado previamente.
404	400	ERROR_CREATING_PAYMENT	Payment method provider unavailable	Nuestro proveedor no está disponible temporalmente, por favor intente nuevamente.
406	400	INVALID_ADDRESS	Invalid address	El valor address enviado es inválido.
407	400	INVALID_CITY	Invalid city	El valor city enviado es inválido.
408	400	PAYMENT_METHOD_LIMIT_EXCEEDED	Payment method limit exceeded	El amount excede el máximo permitido por nuestro proveedor. Intente nuevamente con un monto inferior.
410	400	PAYMENT_METHOD_MINIMUM_REQUIRED	Payment method minimum required	El amount es menor al mínimo permitido por nuestro proveedor. Intente nuevamente con un monto superior.
411	400	INVALID_USER_DOCUMENT	Invalid user document ID	El document enviado fue rechazado por nuestro proveedor. Por favor verifique su validez.
412	400	PAYMENT_METHOD_UNAVAILABLE	Payment Method Unavailable	El método de pago no está disponible temporalmente
418	400	MISSING_REQUIRED_FIELDS	Missing required fields in order to generate Deposit	La llamada carece de un campo requerido.
419	400	MISSING_PAYER_ID_OR_DOCUMENT	payer.id or payer.document field is missing	La llamada carece de payer.id o de payer.document.
500	500	GENERIC_ERROR	Oh no! Something has gone wrong. Please contact a system administrator	Error interno, por favor contacte a soporte.
720	400	MISSING_CONFIGURATION	Missing configuration for merchant account	Hay una configuración faltante, póngase en contacto con su Account Manager.

Descargar Postman Collection