Autorización y cálculo de Signature

Credenciales de la API

Nuestra API de Depósitos usa las Credenciales para autenticar todas las llamadas. Podrán encontrar sus credenciales en el Panel Tupay, desde Settings -> API Access.

• Las Credenciales de los ambientes de STG y Producción son diferentes.

Básicamente, hay dos juegos de credenciales:

• Un juego de Credenciales para llamadas del tipo POST, que contiene una API Key y una API Signature.

• Un juego de Credenciales read-only, que contiene una API Key.

La Autenticación para la API es hecha vía HTTP Basic Auth. Se debe enviar la API Key en todos las llamadas como autenticación básica del valor username. No se requiere proveer una contraseña.

La API Key debe ser enviada en todas las llamadas a la API usando el campo X-Login en los encabezados del request.

Encabezados

Encabezado	Formato	Obligatorio	Descripción
Authorization	String	Si	"TUPAY" más un hash HMAC256 para verificar la integridad de las llamadas.
X-Login	String	Si	Su API Key
X-Date	String	Si	Fecha según el estándar ISO 8601 en el siguiente formato: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z
Content-Type	String	Si	application/json
X-Idempotency-Key	String	Si	Valor único generado por el cliente que usa el servidor para reconocer reintentos subsecuentes de la misma llamada.

Cálculo de Signature

Todas las llamadas a nuestra API de Depósitos debe contener el campo Authorization en el encabezado para asegurar la integridad de la llamada y autenticar las credenciales del Comercio, ya que usaran su propia secret key (también llamada API Signature).

Tiene que ser creada usando codificación HMAC-SHA-256 (RFC 2104) y el contenido debe incluir los siguientes detalles:

X-Date + X-Login + JSONPayload

Usa tu API Signature para generar el valor Authorization.

El campo Authorization en el encabezado de la llamada debe contener el string "TUPAY " más el hash generado, en el siguiente formato:

Authorization: "TUPAY " + HMAC256(X-Date + X-Login + JSONPayload)

Ejemplo:

Authorization: TUPAY 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf

Notas

• Él X-Login es su API Key, puede ser encontrada en el Tupay Panel, yendo a Settings -> API Access -> Deposit credentials -> API Key.
• El X-Date es la fecha en ISO8601 Datetime con huso horario. El formato esperado es: ISO8601 Datetime con huso horario: yyyy-MM-dd'T'HH:mm:ssZ. Ejemplo: .
• El JSONPayload debe ser convertido a UTF-8 antes del hashing para prevenir el error Invalid Signature cuando se envían caracteres con distinta codificación.

Llamadas Idempotencia

Nuestra API soporta Idempotencia para reintentar llamadas de forma segura, evitando realizar la misma operación de forma duplicada por error. Esto resulta útil cuando una llamada a la API es corrompida en tránsito y la respuesta no es recibida. Por ejemplo, si una llamada al Endpoint de Creación de Depósitos no tiene respuesta debido a un error en la conexión de red, puedes reintentar la llamada con la misma Idempotency key para garantizar que no se genere más de un depósito.

Para poder crear una llamada Idempotente se precisa enviar el encabezado X-Idempotency-Key: <key> con un String generado aleatoriamente.

La Idempotencia funciona guardando el código de estatus y el cuerpo de la primer llamada hecha para cierta Idempotency key, sin importar si falló o tuvo éxito. Llamadas subsecuentes con una misma Idempotency key devolverán el mismo resultado, inclusive errores de HTTP 500.

Una idempotency key es un valor único generado por un cliente el cual el servidor usa para reconocer llamadas con reintentos subsecuentes de la misma. Cómo se crean las claves únicas depende de usted, pero nosotros sugerimos usar V4 UUIDs, o cualquier otro string aleatorio con entropía suficiente para evitar colisiones.

Todas las llamadas POST aceptan idempotency keys. Enviar idempotency keys en llamadas GET y DELETE no tiene efecto alguno y deberían ser evitadas, ya que estas llamadas son idempotentes por definición.

Content-Type

Nuestra API de Depósitos está diseñada para recibir y responder la información en formato JSON.

Este encabezado no cambiará a lo largo de las llamadas, y siempre será: application/json

IP Whitelisting

Por motivos de seguridad, necesitarán hacer whitelist de sus IPs desde las cuales van a estar haciendo las llamada a nuestras APIs. Para hacer este proceso lo más eficiente y rápido posible, deben entrar al Tupay Panel e ir a Settings -> API Access y agregar la lista de IPs de las cuales podrían usar bajo la sección Deposit IP Address.

Buenas Practicas

• Asegúrese siempre de verificar las Signatures control string enviados en las notificaciones para validar la veracidad.

• Toda la información que recibimos es convertida a UTF-8. Asegúrese de convertirla también a UTF-8 para garantizar que ambas partes tengan los mismos detalles.

• Siempre valide que un depósito no se libere más de una vez según el deposit_id (Las notificaciones se pueden enviar varias veces). Asegúrese de que un depósito no es liberado más de una vez basándonos en el deposit_id, ya que la notificación puede ser enviada más de una vez.

Ejemplos

Revisa cómo calcular la Signature en los diferentes lenguajes.

PHP

<?php
class TupayExample {
	const TUPAY_AUTHORIZATION_SCHEME = "TUPAY ";
	const HMAC_SHA256 = 'sha256';
	
	public static function build_deposit_key_signature($api_signature, $x_date, $deposits_api_key, $json_payload) {
		// Concatenate the content of the header X-Date, your deposits API Key (X-Login) and 
		// the whole JSON payload of the body of the request
		
		$string = $x_date . $deposits_api_key . $json_payload;
		
		// Generate the HASH by using yur own deposits API Signature and 
		// concatenate "D24 " in front of the hash
		return  self::TUPAY_AUTHORIZATION_SCHEME . hash_hmac(self::HMAC_SHA256, $string, $api_signature);
	}
}

Java

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static final String TUPAY_AUTHORIZATION_SCHEME = "TUPAY ";

private static final String HMAC_SHA256 = "HmacSHA256";

public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String JSONPayload)
      throws NoSuchAlgorithmException, InvalidKeyException, IOException {
   byte[] hmacSha256 = null;
   Mac mac = Mac.getInstance(HMAC_SHA256);
   SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
   mac.init(secretKeySpec);
   hmacSha256 = mac.doFinal(buildByteArray(xDate, apiKey, JSONPayload));
   return TUPAY_AUTHORIZATION_SCHEME + toHexString(hmacSha256);
}

private static byte[] buildByteArray(String xDate, String apiKey, String JSONPayload) throws IOException {
   ByteArrayOutputStream bos = new ByteArrayOutputStream();
   bos.write(xDate.getBytes(StandardCharsets.UTF_8));
   bos.write(apiKey.getBytes(StandardCharsets.UTF_8));
   if (JSONPayload != null) {
      bos.write(payload.getBytes(StandardCharsets.UTF_8));
   }
   return bos.toByteArray();
}

private static String toHexString(byte[] bytes) {
   Formatter formatter = new Formatter();
   for (byte b : bytes) {
      formatter.format("%02x", b);
   }
   return formatter.toString();
}

C#

using System;
using System.Text;
using System.IO;
using System.Security.Cryptography;

namespace Application 
{

    class Directa24Example 
    {
    
        public readonly static string TUPAY_AUTHORIZATION_SCHEME = "TUPAY ";
        
        private readonly static string HMAC_SHA256 = "HmacSHA256";
        
        public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String jsonPayload)
        {
            byte[] hmacSha256 = null;
            var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature);
            var hash = new HMACSHA256(apiSignatureEncod);
            hmacSha256 = hash.ComputeHash(buildByteArray(xDate, depositKey, jsonPayload));  
            return TUPAY_AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower();
        }
        
        private static byte[] buildByteArray(String xDate, String apiKey, String jsonPayload)
        {
            try
            {
                MemoryStream stream = new MemoryStream();
                var xDateEncod = Encoding.UTF8.GetBytes(xDate);
                var apiKeyEncod = Encoding.UTF8.GetBytes(apiKey);
                stream.Write(xDateEncod, 0, xDateEncod.Length);
                stream.Write(apiKeyEncod, 0, apiKeyEncod.Length);
                if (!string.IsNullOrWhiteSpace(jsonPayload))
                {
                    var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload);
                    stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length);
                }
                return stream.ToArray();
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
        
        private static string toHexString(byte[] bytes)
        {
            return BitConverter.ToString(bytes).Replace("-", string.Empty);
        }
    }
}