> ## Documentation Index
> Fetch the complete documentation index at: https://swwipefinancialserviceslimited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```javascript theme={null}
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

```php theme={null}
$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

```python theme={null}
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\#

```csharp theme={null}
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`

The`HexHMACHash256` 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\#

```csharp theme={null}
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

```javascript theme={null}
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

```python theme={null}
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 theme={null}
<?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

```java theme={null}
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

```go theme={null}
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

```ruby theme={null}
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

```javascript theme={null}
// 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 of`MerchantRef`, `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

<Warning>
  * 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
</Warning>