Authentication Process

Authentication Guide for Using Payelu APIs

This guide explains how to authenticate requests when interacting with our APIs. The authentication process ensures secure communication between your systems and our platform.

How Authentication Works

What We Provide

• auth_point_id: Your unique identifier as a merchant (merchant ID).Example:

• auth_api_token: A shared API key used to generate the hash securely.Example: "9SAhxl0NMIOmMMb2l2ToPf83urWDyM32Me26sWPLSK"

What You Need to Do

1. Generate a unique_key:
• Create a random number with less than 10 digits.
• Example: 1234567890

2. Generate the hash:
• Use the following algorithm to create a secure hash based on:
• auth_api_token (shared API key)
• auth_point_id (merchant ID)
• unique_key (random number)

Algorithm for Hash Generation

Python Example (in google colab)

import hmac
import hashlib

def generate_hash(auth_api_token: str, auth_point_id: str, unique_key: int) -> str:
part1 = str(unique_key).encode('utf-8')
part2 = str(auth_point_id).encode('utf-8')
message = part1 + part2
secret = auth_api_token.encode('utf-8')
return hmac.new(secret, message, hashlib.sha256).hexdigest()

auth_point_id = "315f6fa8-d5dc-2cc-9253-f74be351fd00" #sample
auth_api_token = "Ze9QjkaviSQf0171oQ1NttYOrehmeYUZqHv73RXY5ck"

unique_key = 1234567890  # Puedes usar cualquier valor de prueba


generated_hash = generate_hash(auth_api_token, auth_point_id, unique_key)
print("Generated Hash:", generated_hash)

PHP Example

function generate_hash($auth_api_token, $auth_point_id, $unique_key) {
    $part1 = strval($unique_key);
    $part2 = $auth_point_id;
    $message = $part1 . $part2;
    
    return hash_hmac('sha256', $message, $auth_api_token);
}

$auth_point_id = "915f6fa8-d7ac-4ffd-9253-f74be153fd00";
$auth_api_token = "Ze9QjkaviSQf0171oQ1NttYOrehmeYUZqHv73RXY5ck";
$unique_key = 1234567890;

$generated_hash = generate_hash($auth_api_token, $auth_point_id, $unique_key);
echo "Generated Hash: " . $generated_hash . "\n";

Java Example

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class HashGenerator {
    
    public static String generateHash(String authApiToken, String authPointId, long uniqueKey) {
        try {
            // Convertir unique_key y auth_point_id a bytes
            String part1 = String.valueOf(uniqueKey);
            String part2 = authPointId;
            String message = part1 + part2;
            
            // Crear el secret key
            SecretKeySpec secretKeySpec = new SecretKeySpec(
                authApiToken.getBytes(StandardCharsets.UTF_8), 
                "HmacSHA256"
            );
            
            // Inicializar el Mac con HmacSHA256
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKeySpec);
            
            // Generar el hash
            byte[] hashBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
            
            // Convertir a hexadecimal
            return bytesToHex(hashBytes);
            
        } catch (Exception e) {
            throw new RuntimeException("Error generating hash", e);
        }
    }
    
    private static String bytesToHex(byte[] bytes) {
        StringBuilder result = new StringBuilder();
        for (byte b : bytes) {
            result.append(String.format("%02x", b));
        }
        return result.toString();
    }
    
    public static void main(String[] args) {
        String authPointId = "915f6fa8-d7ac-4ffd-9253-f74be153fd00";
        String authApiToken = "Ze9QjkaviSQf0171oQ1NttYOrehmeYUZqHv73RXY5ck";
        long uniqueKey = 1234567890;
        
        String generatedHash = generateHash(authApiToken, authPointId, uniqueKey);
        System.out.println("Generated Hash: " + generatedHash);
    }
}

Ruby Example:

require "openssl"

def generate_hash(auth_api_token, auth_point_id, api_key)
  # api_key se usa como número (int) → elimina ceros iniciales
  api_key_int = api_key.to_i
  message = "#{api_key_int}#{auth_point_id}"

  digest = OpenSSL::Digest.new("sha256")
  hmac = OpenSSL::HMAC.hexdigest(digest, auth_api_token, message)
  return hmac
end

# ==== Valores de prueba ====
auth_api_token = "Ze9QjkaviSQf0171oQ1NttYOrehmeYUZqHv73RXY5ck"
auth_point_id  = "915f6fa8-d7ac-4ffd-9253-f74be153fd00"
api_key        = "1234567890"
expected       = "7d78acb46fc545449a25b86a4030fc04212e5408011eb5da927c82eb03516efe"
# ============================

generated = generate_hash(auth_api_token, auth_point_id, api_key)

puts "Original (expected): #{expected}"
puts "Generated (local):  #{generated}"
puts generated == expected ? "✅ Success: Hashes match!" : "❌ Error: Hashes do NOT match!"

Header Structure

Example Header:

json
Copiar código
{
    "auth_point_id": "dfr3s2c6-a45f-13e1-a2c5-3c58654b12s2",
    "unique_key": 1234567890,
    "hash": "fl498ff4f75f6925bede35ec706e09b693f2de25c81852dfd4b20d6af4e63se3"
}

How to Test

API Backend Validation

1. Retrieve the auth_api_token associated with your auth_point_id.

2. Recalculate the hash using the same algorithm and inputs (auth_api_token, auth_point_id, unique_key).

3. Compare the hashes:
• If the hash matches the one sent in the header, the authentication succeeds.
• If the hash does not match, the request is rejected.

Common Errors to Avoid

1. Incorrect Hash Calculation:
• Ensure the algorithm and input values match the documentation exactly.

2. Missing Header Fields:
• All three fields (auth_point_id, unique_key, hash) are required in every request.

3. Improper Field Types:
• auth_point_id: String (UUID format)
• unique_key: Integer (less than 10 digits)
• hash: String (SHA-256 hex digest)

Need Help?