Authentication

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

Combine credentials: Concatenate your client-id and client-secret with a colon separator
Encode: Base64 encode the combined string
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:

Extract the parameters from the response: MerchantRef, CurrencyCode, Amount
Concatenate the values in the exact order: MerchantRef + CurrencyCode + Amount
Calculate the HMAC using your merchant secret key
Compare the calculated hash with the received HMAC property
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

API Documentation

Endpoint Examples

Authentication

Key Types and Usage

Key Usage Examples

API Authentication

Required Headers

Authentication Process

Example Implementation

JavaScript/Node.js

PHP

Python

C#

Signature Validation

Overview

Verifying HMAC Property

HMAC Implementation Examples

C#

JavaScript/Node.js

Python

PHP

Java

Go

Ruby

Signature Validation Process

Security Notes

API Documentation

Endpoint Examples

Documentation Index

​Key Types and Usage

​Key Usage Examples

​API Authentication

​Required Headers

​Authentication Process

​Example Implementation

​JavaScript/Node.js

​PHP

​Python

​C#

​Signature Validation

​Overview

​Verifying HMAC Property

​HMAC Implementation Examples

​C#

​JavaScript/Node.js

​Python

​PHP

​Java

​Go

​Ruby

​Signature Validation Process

​Security Notes

Key Types and Usage

Key Usage Examples

API Authentication

Required Headers

Authentication Process

Example Implementation

JavaScript/Node.js

PHP

Python

C#

Signature Validation

Overview

Verifying HMAC Property

HMAC Implementation Examples

C#

JavaScript/Node.js

Python

PHP

Java

Go

Ruby

Signature Validation Process

Security Notes