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	"D24" 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 "D24 " más el hash generado, en el siguiente formato:

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

Ejemplo:

Authorization: D24 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.

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 D24_AUTHORIZATION_SCHEME = "D24 ";
	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::D24_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 D24_AUTHORIZATION_SCHEME = "D24 ";

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 D24_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 D24_AUTHORIZATION_SCHEME = "D24 ";
        
        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 D24_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);
        }
    }
}