Authentication

Authentication Overview

Key Types and Usage

SwwipePay uses different types of keys for different purposes. Understanding when and how to use each key is crucial for proper integration:

Key Type	Purpose	Usage Location	Security Level
Client ID	Username for API authentication	Server-side API requests	Sensitive - Server only
Client Secret	Password for API authentication	Server-side API requests	Highly Sensitive - Server only
Merchant Key	Loading payment modal popup	Client-side JavaScript	Public - Can be exposed

Key Usage Examples

Client ID & Client Secret:

• Used for server-to-server API calls
• Required for transaction verification
• Must be kept secure on your backend

Merchant Key:

• Used in your frontend JavaScript code
• Required to initialize the SwwipePay payment modal
• Can be safely included in client-side code

API Authentication

This endpoint uses HTTP Basic Authentication for server-side API requests.

Required Headers

Authorization: Basic <base64(client-id:client-secret)>
Content-Type: application/json

Authentication Process

1. Combine credentials: Concatenate your client-id and client-secret with a colon separator
2. Encode: Base64 encode the combined string
3. Include in header: Add the encoded string to the Authorization header

Example Implementation

JavaScript/Node.js

const clientId = 'your_client_id';
const clientSecret = 'your_client_secret';

// Create base64 encoded credentials
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

// Make authenticated API request
const response = await fetch('https://api.paywithswwipe.com/verify-transaction', {
    method: 'POST',
    headers: {
        'Authorization': `Basic ${credentials}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        reference: 'txn_reference_here'
    })
});

PHP

$clientId = 'your_client_id';
$clientSecret = 'your_client_secret';

// Create base64 encoded credentials
$credentials = base64_encode($clientId . ':' . $clientSecret);

$headers = [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json'
];

$data = json_encode(['reference' => 'txn_reference_here']);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.paywithswwipe.com/verify-transaction');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

Python

import requests
import base64

client_id = 'your_client_id'
client_secret = 'your_client_secret'

# Create base64 encoded credentials
credentials = base64.b64encode(f'{client_id}:{client_secret}'.encode()).decode()

headers = {
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/json'
}

data = {
    'reference': 'txn_reference_here'
}

response = requests.post(
    'https://api.paywithswwipe.com/verify-transaction',
    headers=headers,
    json=data
)

C#

using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

public class SwwipeAuth
{
    private static readonly HttpClient client = new HttpClient();
    
    public static async Task<string> MakeAuthenticatedRequest()
    {
        string clientId = "your_client_id";
        string clientSecret = "your_client_secret";
        
        // Create base64 encoded credentials
        string credentials = Convert.ToBase64String(
            Encoding.UTF8.GetBytes($"{clientId}:{clientSecret}")
        );
        
        client.DefaultRequestHeaders.Authorization = 
            new System.Net.Http.Headers.AuthenticationHeaderValue("Basic", credentials);
        
        var content = new StringContent(
            "{\"reference\":\"txn_reference_here\"}", 
            Encoding.UTF8, 
            "application/json"
        );
        
        var response = await client.PostAsync(
            "https://api.paywithswwipe.com/verify-transaction", 
            content
        );
        
        return await response.Content.ReadAsStringAsync();
    }
}

txn_reference_here is your transaction reference.

Signature Validation

Overview

Signature validation is a crucial step in processing events or responses received from Swwipe. These entities carry a payload that includes an HMAC (Hash-based Message Authentication Code) property. The purpose of this property is to ensure the integrity and authenticity of the data transmitted. The HMAC property is generated as a Hexadecimal HMAC256 hash, computed based on a combination of parameters, including MerchantRef, CurrencyCode, and Amount, using the MerchantSecret as the secret key.

Verifying HMAC Property

Before proceeding with the processing of any transaction, it is imperative to validate the HMAC property to confirm the data’s integrity and origin. The following section provides a sample function that can be used to obtain the HMAC value for verification.

Sample Function: HexHMACHash256

TheHexHMACHash256 function is used to calculate the HMAC256 hash for a given input value using the provided MerchantSecret key. It is crucial to construct the input value as the concatenation of MerchantRef, CurrencyCode, and Amount.

HMAC Implementation Examples

The following examples show how to implement HMAC256 signature validation in different programming languages:

C#

public static string HexHMACHash256(string value, string maggi) {
    // Convert the MerchantSecret key to bytes
    byte[] keyByte = Encoding.UTF8.GetBytes(maggi);
    
    // Convert the input value to bytes
    byte[] messageBytes = Encoding.UTF8.GetBytes(value);
    
    // Initialize an HMACSHA256 hasher with the key
    using (var hasher = new HMACSHA256(keyByte)) {
        // Compute the hash
        byte[] hashMessage = hasher.ComputeHash(messageBytes);
        
        // Convert the hash to a Hexadecimal string format
        return BitConverter.ToString(hashMessage).Replace("-", "").ToLower();
    }
}

JavaScript/Node.js

const crypto = require('crypto');

function hexHMACHash256(value, merchantSecret) {
    // Create HMAC using SHA256
    const hmac = crypto.createHmac('sha256', merchantSecret);
    
    // Update with the input value
    hmac.update(value);
    
    // Return the hash in hexadecimal format
    return hmac.digest('hex');
}

// Usage example
const merchantRef = "REF123456";
const currencyCode = "NGN";
const amount = "5000";
const merchantSecret = "your_merchant_secret";

const inputValue = merchantRef + currencyCode + amount;
const signature = hexHMACHash256(inputValue, merchantSecret);
console.log(signature);

Python

import hmac
import hashlib

def hex_hmac_hash256(value, merchant_secret):
    """
    Calculate HMAC256 hash for signature validation
    
    Args:
        value (str): Concatenated string of MerchantRef + CurrencyCode + Amount
        merchant_secret (str): Your merchant secret key
    
    Returns:
        str: Hexadecimal HMAC256 hash
    """
    # Convert strings to bytes
    key_bytes = merchant_secret.encode('utf-8')
    message_bytes = value.encode('utf-8')
    
    # Create HMAC object
    hmac_obj = hmac.new(key_bytes, message_bytes, hashlib.sha256)
    
    # Return hexadecimal digest
    return hmac_obj.hexdigest()

# Usage example
merchant_ref = "REF123456"
currency_code = "NGN"
amount = "5000"
merchant_secret = "your_merchant_secret"

input_value = merchant_ref + currency_code + amount
signature = hex_hmac_hash256(input_value, merchant_secret)
print(signature)

PHP

<?php
function hexHMACHash256($value, $merchantSecret) {
    /**
     * Calculate HMAC256 hash for signature validation
     * 
     * @param string $value Concatenated string of MerchantRef + CurrencyCode + Amount
     * @param string $merchantSecret Your merchant secret key
     * @return string Hexadecimal HMAC256 hash
     */
    return hash_hmac('sha256', $value, $merchantSecret);
}

// Usage example
$merchantRef = "REF123456";
$currencyCode = "NGN";
$amount = "5000";
$merchantSecret = "your_merchant_secret";

$inputValue = $merchantRef . $currencyCode . $amount;
$signature = hexHMACHash256($inputValue, $merchantSecret);
echo $signature;
?>

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class SwwipeSignature {
    
    public static String hexHMACHash256(String value, String merchantSecret) 
            throws NoSuchAlgorithmException, InvalidKeyException {
        
        // Create SecretKeySpec with merchant secret
        SecretKeySpec secretKeySpec = new SecretKeySpec(
            merchantSecret.getBytes(), "HmacSHA256"
        );
        
        // Get Mac instance
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKeySpec);
        
        // Compute hash
        byte[] hashBytes = mac.doFinal(value.getBytes());
        
        // Convert to hexadecimal string
        StringBuilder hexString = new StringBuilder();
        for (byte b : hashBytes) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                hexString.append('0');
            }
            hexString.append(hex);
        }
        
        return hexString.toString();
    }
    
    // Usage example
    public static void main(String[] args) {
        try {
            String merchantRef = "REF123456";
            String currencyCode = "NGN";
            String amount = "5000";
            String merchantSecret = "your_merchant_secret";
            
            String inputValue = merchantRef + currencyCode + amount;
            String signature = hexHMACHash256(inputValue, merchantSecret);
            System.out.println(signature);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
)

// HexHMACHash256 calculates HMAC256 hash for signature validation
func HexHMACHash256(value, merchantSecret string) string {
    // Create HMAC hasher
    h := hmac.New(sha256.New, []byte(merchantSecret))
    
    // Write the input value
    h.Write([]byte(value))
    
    // Get the hash and convert to hex string
    return hex.EncodeToString(h.Sum(nil))
}

func main() {
    merchantRef := "REF123456"
    currencyCode := "NGN"
    amount := "5000"
    merchantSecret := "your_merchant_secret"
    
    inputValue := merchantRef + currencyCode + amount
    signature := HexHMACHash256(inputValue, merchantSecret)
    fmt.Println(signature)
}

Ruby

require 'openssl'

def hex_hmac_hash256(value, merchant_secret)
  # Calculate HMAC256 hash for signature validation
  #
  # @param value [String] Concatenated string of MerchantRef + CurrencyCode + Amount
  # @param merchant_secret [String] Your merchant secret key
  # @return [String] Hexadecimal HMAC256 hash
  
  OpenSSL::HMAC.hexdigest('SHA256', merchant_secret, value)
end

# Usage example
merchant_ref = "REF123456"
currency_code = "NGN"
amount = "5000"
merchant_secret = "your_merchant_secret"

input_value = merchant_ref + currency_code + amount
signature = hex_hmac_hash256(input_value, merchant_secret)
puts signature

Signature Validation Process

To validate a signature received from SwwipePay:

1. Extract the parameters from the response: MerchantRef, CurrencyCode, Amount
2. Concatenate the values in the exact order: MerchantRef + CurrencyCode + Amount
3. Calculate the HMAC using your merchant secret key
4. Compare the calculated hash with the received HMAC property
5. Process the transaction only if the signatures match

// Example validation in Node.js
function validateSignature(receivedHMAC, merchantRef, currencyCode, amount, merchantSecret) {
    const inputValue = merchantRef + currencyCode + amount;
    const calculatedHMAC = hexHMACHash256(inputValue, merchantSecret);
    
    return receivedHMAC === calculatedHMAC;
}


// Usage
const isValid = validateSignature(
    receivedResponse.hmac,
    receivedResponse.merchantRef,
    receivedResponse.currencyCode,
    receivedResponse.amount,
    process.env.MERCHANT_SECRET
);

if (isValid) {
    // Process the transaction
    console.log("Signature is valid, processing transaction...");
} else {
    // Reject the transaction
    console.log("Invalid signature, rejecting transaction");
}

In the provided function, value should be constructed as the concatenation ofMerchantRef, CurrencyCode, and Amount, while maggi represents the MerchantSecret key. By calling this function and comparing the result with the HMAC property received from SwwipePay, you can ensure the authenticity and integrity of the data before proceeding with transaction processing.

Security Notes

• Always keep your merchant secret secure and never expose it in client-side code
• Validate signatures for all responses
• Use constant-time comparison when validating signatures to prevent timing attacks
• Store your merchant secret in environment variables or secure configuration