Switch Wallet Merchant API Documentation

Becoming a Merchant

Welcome to the Switch Wallet Merchant API. Integrating with our powerful RESTful API and webhook service is the first step to leveraging our platform. The process begins with completing your business verification and setting up your account.

Onboarding Steps

Complete KYB: Finalize the "Know Your Business" (KYB) process with our team.
Provide Details: Submit your business account and SUPER admin profile information as structured below.

Merchant Data Structure

You will need to provide the following data. The table below illustrates the required fields and their validation rules.

Merchant Company

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier for the merchant company
name	string	Yes	Company name
tagline	string	Yes	Company tagline or slogan
companyEmail	string (email)	Yes	Company email address (lowercase)
countryCode	string (2 chars)	Yes	ISO country code (2 characters)
logoUrl	string (URI)	No	URL to company logo
websiteUrl	string (URI)	No	Company website URL

Merchant Account

Field	Type	Required	Description
email	string (email)	Yes	Account email address (lowercase)
firstName	string	Yes	First name of the account holder
lastName	string	Yes	Last name of the account holder
phoneNumber	string	Yes	Phone number
countryCode	string (2 chars)	Yes	ISO country code (2 characters)

General API Response

All API responses follow a standardized JSON structure. This ensures consistency and predictability when you interact with our endpoints.

Response Object Structure

{
  "data": {},
  "status": "success",
  "statusCode": 200,
  "message": "Action Completed",
  "action": null,
  "messageLanguageCode": "app_001",
  "details": null,
  "cacheTTL": 20
}

Field Descriptions

Field	Description
data	The main content returned by the API. Can be an object, array, or null.
status	Indicates the outcome of the request. Possible values are 'success' or 'failed'.
statusCode	The standard HTTP response status code.
message	A human-readable message to be displayed to the end-user (e.g., "Registration completed").
messageLanguageCode	A unique code for the message, which can be used by frontend clients for translations.
action	A specific action the frontend should take, e.g., 'load_2fa_screen'. See action documentation for details.
details	Contains detailed debug messages or error logs for the developer. This field is not returned in production environments.
cacheTTL	Time-To-Live in seconds. Indicates how long the response is cached on the server. You may use this to manage your own caching logic.

Account Setup & Configuration

[Registration & Activation] After KYB, we create your account and send an activation link to your `merchantAccount.email`. Follow it to access the Switch Wallet Dashboard, complete registration, and set up 2FA.

[Webhook URL] In the dashboard, set your webhook URL. We send notifications here and often require acknowledgements.

[RSA Public Key] For direct server-to-server API calls, you must generate an RSA key pair. In the Switch Wallet Dashboard, upload your public key. This allows our servers to verify requests signed with your corresponding private key.

API Authentication

Our API uses RSA signature authentication for all direct server-to-server communication. This is a stateless method ideal for automated operations that uses a public/private key pair and does not require a login session.

RSA Signature (For Direct Merchant API)

This is a stateless method ideal for automated, server-to-server communication. It uses a public/private key pair and does not require a login session. All direct Merchant API calls (e.g., transfers, queries) must use RSA signatures.

RSA Signature (Stateless Merchant API)

For direct server-to-server API calls, you must use RSA signing. This method is stateless and does not require a login session. It proves the request is from you and that the payload has not been tampered with.

Note: Your Merchant Company App Id can be found in your merchant dashboard under the API Keys section. This is the identifier you'll use in the Authorization header for all API requests.

RSA Authentication Flow

Get Your Merchant Company App Id and API Key: Navigate to your merchant dashboard and go to the API Keys section. Copy your Merchant Company App Id and your API Key (x-api-key).
Generate Key Pair: You must generate a standard RSA key pair. Keep your private key secret. See the section below for code samples.
Upload Public Key: Upload your public key to the Switch Wallet merchant dashboard.
Construct String-to-Sign: Create a canonical string by sorting the keys in your JSON request payload and joining them (e.g., `amount=5000&destinationAccount=...`).
Sign with Private Key: Use your private key to sign the string from the previous step using the `RSA-SHA256` algorithm.
Send Headers: Make your API request with the following headers:
- Authorization: `Bearer ` (Get this from your merchant dashboard API Keys section)
- x-api-key: Your global API key (Get this from your merchant dashboard API Keys section)
- x-rsa-signature: The Base64-encoded signature you just generated.
- x-request-timestamp: Current timestamp in milliseconds.
- x-nonce-string: A random 32-character string.

Generating Your RSA Key Pair

To get started with RSA authentication, you first need to generate a 2048-bit RSA key pair. Run one of the scripts below to create private_key.pem, public_key.pem, and bootstrap.env (containing base64-encoded keys). Keep the private key secure and upload the contents of the public key to your merchant dashboard.

// Save as generateKeys.js and run `node generateKeys.js`
const { generateKeyPair } = require('crypto');
const fs = require('fs');

generateKeyPair('rsa', {
  modulusLength: 2048,
  publicKeyEncoding: { type: 'spki', format: 'pem' },
  privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
}, (err, publicKey, privateKey) => {
  if (err) { return console.error(err); }
  
  // Write PEM files
  fs.writeFileSync('public_key.pem', publicKey);
  fs.writeFileSync('private_key.pem', privateKey);
  
  // Convert to base64 and create bootstrap.env
  const privateB64 = Buffer.from(privateKey).toString('base64').replace(/\n/g, '');
  const publicB64 = Buffer.from(publicKey).toString('base64').replace(/\n/g, '');
  
  const bootstrapEnv = `# Base64-encoded key material (generated ${new Date().toISOString()})
RSA_MERCHANT_PRIVATE_KEY_B64=\"${privateB64}\"
RSA_MERCHANT_PUBLIC_KEY_B64=\"${publicB64}\"
`;
  
  fs.writeFileSync('bootstrap.env', bootstrapEnv);
  
  console.log('✓ Public and private key files generated!');
  console.log('✓ bootstrap.env created with base64-encoded keys');
});

# Requires: pip install cryptography
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa
import base64
from datetime import datetime

private_key = rsa.generate_private_key(
    public_exponent=65537,
    key_size=2048,
)

pem_private = private_key.private_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PrivateFormat.PKCS8,
   encryption_algorithm=serialization.NoEncryption()
)

public_key = private_key.public_key()
pem_public = public_key.public_bytes(
   encoding=serialization.Encoding.PEM,
   format=serialization.PublicFormat.SubjectPublicKeyInfo
)

# Write PEM files
with open('private_key.pem', 'wb') as f:
    f.write(pem_private)
with open('public_key.pem', 'wb') as f:
    f.write(pem_public)

# Convert to base64 and create bootstrap.env
private_b64 = base64.b64encode(pem_private).decode('utf-8').replace('\n', '')
public_b64 = base64.b64encode(pem_public).decode('utf-8').replace('\n', '')

bootstrap_env = f"""# Base64-encoded key material (generated {datetime.utcnow().isoformat()}Z)
RSA_MERCHANT_PRIVATE_KEY_B64=\"{private_b64}\"
RSA_MERCHANT_PUBLIC_KEY_B64=\"{public_b64}\"
"""

with open('bootstrap.env', 'w') as f:
    f.write(bootstrap_env)

print('✓ Public and private key files generated!')
print('✓ bootstrap.env created with base64-encoded keys')

<?php
$config = [
    "private_key_bits" => 2048,
    "private_key_type" => OPENSSL_KEYTYPE_RSA,
];

// Create the private and public key
$res = openssl_pkey_new($config);

// Extract the private key
openssl_pkey_export($res, $private_key);
file_put_contents('private_key.pem', $private_key);

// Extract the public key
$public_key = openssl_pkey_get_details($res);
$public_key = $public_key["key"];
file_put_contents('public_key.pem', $public_key);

// Convert to base64 and create bootstrap.env
$private_b64 = base64_encode($private_key);
$private_b64 = str_replace("\n", '', $private_b64);
$public_b64 = base64_encode($public_key);
$public_b64 = str_replace("\n", '', $public_b64);

$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$bootstrap_env = "# Base64-encoded key material (generated {$timestamp})
RSA_MERCHANT_PRIVATE_KEY_B64=\"{$private_b64}\"
RSA_MERCHANT_PUBLIC_KEY_B64=\"{$public_b64}\"
";

file_put_contents('bootstrap.env', $bootstrap_env);

echo "✓ Public and private key files generated!\n";
echo "✓ bootstrap.env created with base64-encoded keys\n";
?>

// C# Example for RSA Key Generation
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;

public class RsaKeyGenerator
{
    public static void Main()
    {
        using (var rsa = RSA.Create(2048))
        {
            // Export the private key
            var privateKey = rsa.ExportRSAPrivateKeyPem();
            File.WriteAllText("private_key.pem", privateKey);

            // Export the public key
            var publicKey = rsa.ExportSubjectPublicKeyInfoPem();
            File.WriteAllText("public_key.pem", publicKey);

            // Convert to base64 and create bootstrap.env
            var privateB64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(privateKey)).Replace("\n", "").Replace("\r", "");
            var publicB64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(publicKey)).Replace("\n", "").Replace("\r", "");

            var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");
            var bootstrapEnv = $"# Base64-encoded key material (generated {timestamp})\n" +
                              $"RSA_MERCHANT_PRIVATE_KEY_B64=\"{privateB64}\"\n" +
                              $"RSA_MERCHANT_PUBLIC_KEY_B64=\"{publicB64}\"\n";

            File.WriteAllText("bootstrap.env", bootstrapEnv);

            Console.WriteLine("✓ Public and private key files generated!");
            Console.WriteLine("✓ bootstrap.env created with base64-encoded keys");
        }
    }
}

#!/usr/bin/env bash
# Generate RSA key pair for merchant API authentication
# Creates private_key.pem, public_key.pem, and bootstrap.env
#
# Usage:
#   chmod +x generateKeys.sh
#   ./generateKeys.sh

set -euo pipefail

# Check if openssl is installed
if ! command -v openssl > /dev/null 2>&1; then
    echo "Error: openssl is required but not installed or not on PATH." >&2
    exit 1
fi

echo "==> Generating RSA key pair for merchant API"

# Generate private key (2048-bit RSA)
openssl genpkey \
    -algorithm RSA \
    -pkeyopt rsa_keygen_bits:2048 \
    -out private_key.pem.tmp

# Strip passphrase (if any) and ensure traditional PKCS #1 format
openssl rsa -in private_key.pem.tmp -out private_key.pem
rm -f private_key.pem.tmp

# Generate public key
openssl rsa -in private_key.pem -pubout -out public_key.pem

# Set proper permissions
chmod 600 private_key.pem
chmod 644 public_key.pem

# Convert to base64 and create bootstrap.env
private_b64="$(base64 < private_key.pem | tr -d '\n')"
public_b64="$(base64 < public_key.pem | tr -d '\n')"

timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"

cat > bootstrap.env <<EOF
# Base64-encoded key material (generated ${timestamp})
RSA_MERCHANT_PRIVATE_KEY_B64="${private_b64}"
RSA_MERCHANT_PUBLIC_KEY_B64="${public_b64}"
EOF

echo ""
echo "✓ Public and private key files generated!"
echo "✓ bootstrap.env created with base64-encoded keys"
echo ""
echo "Files created:"
echo "  - private_key.pem (keep this secure!)"
echo "  - public_key.pem (upload this to your merchant dashboard)"
echo "  - bootstrap.env (contains base64-encoded keys for .env file)"

RSA Signature Generation

⚠️ Important: Nested Object Handling

When your payload contains nested objects (like proxyKYCDetails), you must convert them to JSON strings during signature generation. The server expects the exact same string format for verification. See the examples below for proper implementation.

💡 Pro Tip: Include All Fields

Always include all required fields in your payload (even if they're false or null). The server may add default values during validation, which will cause signature verification to fail if not included in your original payload.

💡 Using Base64 Keys from .env

You can load your private key from base64 format stored in your .env file (from bootstrap.env). This is more secure and convenient for production environments.

// Node.js Example for RSA Signature
const crypto = require('crypto');
const fs = require('fs');
require('dotenv').config(); // Load .env file

// Load private key from base64 in .env file
const privateKeyB64 = process.env.RSA_MERCHANT_PRIVATE_KEY_B64;
const privateKey = Buffer.from(privateKeyB64, 'base64').toString('utf-8');

// Alternative: Load from PEM file (if not using .env)
// const privateKey = fs.readFileSync('path/to/your_private_key.pem', 'utf-8');

function generateRsaSignature(privateKey, payload) {
  // Create the exact same sorted string from the payload.
  // Filter out null/undefined values and handle nested objects.
  const stringToSign = Object.keys(payload)
    .filter(key => payload[key] != null && payload[key] !== '')
    .sort()
    .map(key => {
      const value = payload[key];
      // Handle nested objects by converting them to JSON strings
      if (typeof value === 'object' && value !== null) {
        return `${key}=${JSON.stringify(value)}`;
      }
      return `${key}=${value}`;
    })
    .join('&');

  // Sign the string with your private key.
  const signature = crypto
    .createSign('RSA-SHA256')
    .update(stringToSign)
    .sign(privateKey, 'base64');

  return signature;
}

// Example Usage:
const requestPayload = {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    countryCode: 'NG',
    phoneNumber: '08012345678',
    proxyKYCDetails: {
        idCardType: 'PASSPORT',
        idCardNumber: 'A12345678',
        countryOfIssue: 'NG'
    }
};

// Generate nonce for header
const nonceStr = crypto.randomBytes(16).toString('hex');

const rsaSignature = generateRsaSignature(privateKey, requestPayload);
// Send this rsaSignature in the 'x-rsa-signature' header.

# Python Example for RSA Signature
import time
import os
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_rsa_signature(private_key_pem, payload):
    # Create the exact same sorted string from the payload.
    string_to_sign = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])

    private_key = serialization.load_pem_private_key(
        private_key_pem.encode(),
        password=None,
    )

    signature = private_key.sign(
        string_to_sign.encode('utf-8'),
        padding.PKCS1v15(),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode('utf-8')

# Example Usage:
request_payload = {
    'firstName': 'John',
    'lastName': 'Doe',
    'email': '[email protected]',
    'countryCode': 'NG',
    'phoneNumber': '08012345678',
    'proxyKYCDetails': {
        'idCardType': 'PASSPORT',
        'idCardNumber': 'A12345678',
        'countryOfIssue': 'NG'
    }
}

# Generate nonce for header
nonce_str = os.urandom(16).hex()

rsa_signature = generate_rsa_signature(private_key_pem, request_payload)
# Send this rsa_signature in the 'x-rsa-signature' header.

💡 Using Base64 Keys from .env

You can load your private key from base64 format stored in your .env file (from bootstrap.env). This is more secure and convenient for production environments.

<?php
// Load .env file (using vlucas/phpdotenv: composer require vlucas/phpdotenv)
require 'vendor/autoload.php';
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

// Load private key from base64 in .env file
$privateKeyB64 = $_ENV['RSA_MERCHANT_PRIVATE_KEY_B64'];
$privateKey = base64_decode($privateKeyB64);

// Alternative: Load from PEM file (if not using .env)
// $privateKey = file_get_contents('path/to/your_private_key.pem');

function generateRsaSignature($privateKey, $payload) {
    // Create the exact same sorted string from the payload.
    ksort($payload);
    $stringToSign = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            $stringToSign .= $key . '=' . $value . '&';
        }
    }
    $stringToSign = rtrim($stringToSign, '&');

    openssl_sign($stringToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256);
    
    return base64_encode($signature);
}

// Example Usage:
$requestPayload = [
    'requestTime' => round(microtime(true) * 1000),
    'amount' => 5000,
    'destinationAccount' => '0123456789'
];

// Generate nonce for header
$nonceStr = bin2hex(random_bytes(16));

$rsaSignature = generateRsaSignature($privateKey, $requestPayload);
// Send this $rsaSignature in the 'x-rsa-signature' header.
?>

💡 Using Base64 Keys from .env

You can load your private key from base64 format stored in your .env file (from bootstrap.env). This is more secure and convenient for production environments. Use DotNetEnv package: dotnet add package DotNetEnv

// C# Example for RSA Signature
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using DotNetEnv;  // Load .env file

// Load .env file
Env.Load();

// Load private key from base64 in .env file
var privateKeyB64 = Environment.GetEnvironmentVariable("RSA_MERCHANT_PRIVATE_KEY_B64");
var privateKeyBytes = Convert.FromBase64String(privateKeyB64);
var privateKeyPem = Encoding.UTF8.GetString(privateKeyBytes);

// Alternative: Load from PEM file (if not using .env)
// var privateKeyPem = File.ReadAllText(@"path\to\your_private_key.pem");

public class RsaGenerator
{
    public static string GenerateRsaSignature(string privateKeyPem, Dictionary<string, object> payload)
    {
        // Create the exact same sorted string from the payload.
        var stringToSign = string.Join("&", payload
            .Where(kvp => kvp.Value != null && kvp.Value.ToString() != "")
            .OrderBy(kvp => kvp.Key)
            .Select(kvp => $"{kvp.Key}={kvp.Value}"));

        using (var rsa = new RSACryptoServiceProvider())
        {
            // Import the private key.
            rsa.ImportFromPem(privateKeyPem);

            var dataBytes = Encoding.UTF8.GetBytes(stringToSign);
            var signatureBytes = rsa.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

            return Convert.ToBase64String(signatureBytes);
        }
    }

    public static void Main()
    {
        var requestPayload = new Dictionary<string, object>
        {
            { "requestTime", new DateTimeOffset(DateTime.UtcNow).ToUnixTimeMilliseconds() },
            { "amount", 5000 },
            { "destinationAccount", "0123456789" }
        };

        // Generate nonce for header
        var nonceStr = Guid.NewGuid().ToString("N");

        var rsaSignature = GenerateRsaSignature(privateKeyPem, requestPayload);
        // Send this rsaSignature in the 'x-rsa-signature' header.
    }
}

Verifying Webhooks

To ensure the security and integrity of data sent to your webhook URL, all outgoing requests from Switch Wallet are signed. We include the X-Webhook-Secret and X-Webhook-Signature headers on every webhook request. You must verify this signature using the Switch Wallet Public Key, which is available for you to copy from your merchant dashboard.

This process guarantees that the webhook was sent by Switch Wallet and that its content has not been altered. The secret header allows you to quickly reject any request that does not match the value configured in your dashboard.

Webhook Verification Flow

Get Public Key: Copy the Switch Wallet Public Key from your merchant dashboard.
Receive Webhook: Your server receives a POST request at your configured webhook URL with JSON body and headers X-Webhook-Secret, X-Webhook-Signature, X-Webhook-Event-Type, and X-Webhook-Timestamp.
Validate Secret: Compare the X-Webhook-Secret header with the webhook secret configured in your dashboard. If it does not match, immediately reject the request.
Extract Signature & Body: Read the raw request body bytes (before JSON parsing) and get the base64-encoded signature from the X-Webhook-Signature header.
Verify Signature: Use the Switch Wallet Public Key to verify that the signature matches the raw request body using RSA-SHA256. If it's valid, process the webhook. Otherwise, discard the request.

Important: Use Raw Body for Verification

⚠️ Critical for Webhook Verification:

When validating the RSA signature, you must verify against the exact raw request body bytes that Switch Wallet sent, not a re-serialized JSON string. Most frameworks provide a way to access the raw body (e.g. request.rawBody, request.get_data(), or php://input).

Switch Wallet signs the raw JSON payload with RSA-SHA256 using our private key; you should verify that signature with the public key exposed in your dashboard.

Webhook Verification Examples

// Node.js Example for Webhook Verification
const crypto = require('crypto');

function verifyWebhookSignature(publicKey, payload) {
  const { signature, ...dataToVerify } = payload;
  if (!signature) return false;

  const stringToVerify = Object.keys(dataToVerify)
    .filter(key => dataToVerify[key] != null && dataToVerify[key] !== '')
    .sort()
    .map(key => {
      const value = dataToVerify[key];
      if (typeof value === 'object' && value !== null) {
        return `${key}=${JSON.stringify(value)}`;
      }
      return `${key}=${value}`;
    })
    .join('&');

  const isVerified = crypto
    .createVerify('RSA-SHA256')
    .update(stringToVerify)
    .verify(publicKey, signature, 'base64');

  return isVerified;
}

// Example Usage in an Express.js route
app.post('/webhook', (req, res) => {
  const switchPublicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'; // From your dashboard
  const isValid = verifyWebhookSignature(switchPublicKey, req.body);

  if (isValid) {
    console.log('Webhook verified successfully.');
    res.status(200).send('OK');
  } else {
    console.error('Webhook verification failed.');
    res.status(400).send('Invalid signature');
  }
});

# Python Example for Webhook Verification
import base64
import json
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

def verify_webhook_signature(public_key_pem, payload):
    signature_b64 = payload.pop('signature', None)
    if signature_b64 is None:
        return False

    string_to_verify = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])
    
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    signature = base64.b64decode(signature_b64)

    try:
        public_key.verify(
            signature,
            string_to_verify.encode(),
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except InvalidSignature:
        return False

# Example Usage in a Flask route
@app.route('/webhook', methods=['POST'])
def webhook_handler():
    switch_public_key = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----' # From your dashboard
    payload = request.get_json()
    is_valid = verify_webhook_signature(switch_public_key, payload)
    if is_valid:
        return 'OK', 200
    else:
        return 'Invalid signature', 400

<?php

function verifyWebhookSignature($publicKey, $payload) {
    if (!isset($payload['signature'])) {
        return false;
    }
    $signature = base64_decode($payload['signature']);
    unset($payload['signature']);

    ksort($payload);
    $stringToVerify = '';
    foreach ($payload as $key => $value) {
        if ($value !== null && $value !== '') {
            if (is_array($value) || is_object($value)) {
                $stringToVerify .= $key . '=' . json_encode($value) . '&';
            } else {
                $stringToVerify .= $key . '=' . $value . '&';
            }
        }
    }
    $stringToVerify = rtrim($stringToVerify, '&');

    $result = openssl_verify($stringToVerify, $signature, $publicKey, OPENSSL_ALGO_SHA256);

    return $result === 1;
}

// Example Usage
$switchPublicKey = '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'; // From your dashboard
$payload = json_decode(file_get_contents('php://input'), true);
$isValid = verifyWebhookSignature($switchPublicKey, $payload);

if ($isValid) {
    http_response_code(200);
    echo 'OK';
} else {
    http_response_code(400);
    echo 'Invalid signature';
}
?>

// C# Example for Webhook Verification
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json.Linq;

public class WebhookVerifier
{
    public static bool VerifyWebhookSignature(string publicKeyPem, string jsonPayload)
    {
        var payload = JObject.Parse(jsonPayload);
        var signatureToken = payload.GetValue("signature", StringComparison.OrdinalIgnoreCase);
        if (signatureToken == null) return false;

        var signature = Convert.FromBase64String(signatureToken.ToString());
        payload.Remove("signature");

        var stringToVerify = string.Join("&", payload
            .Properties()
            .Where(p => p.Value.Type != JTokenType.Null && p.Value.ToString() != "")
            .OrderBy(p => p.Name)
            .Select(p => {
                var value = p.Value;
                if (value.Type == JTokenType.Object || value.Type == JTokenType.Array) {
                    return $"{p.Name}={JsonConvert.SerializeObject(value)}";
                }
                return $"{p.Name}={value}";
            }));

        using (var rsa = new RSACryptoServiceProvider())
        {
            rsa.ImportFromPem(publicKeyPem);
            var dataBytes = Encoding.UTF8.GetBytes(stringToVerify);
            return rsa.VerifyData(dataBytes, signature, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
        }
    }
}

Webhook Events

Switch Wallet sends webhooks to your configured webhook URL for various events. All webhooks are signed with RSA-SHA256 and include authentication headers. Below are all the webhook events you can expect to receive.

Wallet.ManualRemittanceSweepCreated

Sent when a manual remittance sweep request is created. This occurs when an admin or merchant creates a sweep list item with a transaction hash.

When it's sent:

When a sweep list item is created with a valid transaction hash
Only if notifyMerchant is set to true
After successful validation of the transaction hash

Wallet.RemittanceSweepStatusUpdated

Sent when a remittance sweep status is updated (e.g., when a sweep is completed or fails). This webhook is sent automatically by AsoRock when processing sweeps.

When it's sent:

When a sweep is completed successfully (status: COMPLETED)
When a sweep fails (status: FAILED)
Includes detailed error information if the sweep failed

HTTPS Request Samples

Below are sample code examples showing how to make authenticated HTTPS requests to the Merchant API. These examples demonstrate the proper headers and authentication flow required for all merchant endpoints using RSA signatures.

Required Headers

All merchant API requests require the following headers for authentication and security:

Header	Type	Description	Example
Accept	string	Content type for the response	`application/json`
x-api-key	string	API key for general authorization	`your_api_key_here`
Authorization	string	Bearer token containing your Merchant Company App Id (found in merchant dashboard API Keys section)	`Bearer YOUR_MERCHANT_COMPANY_APP_ID`
x-rsa-signature	string	Base64-encoded RSA signature for request integrity	`generated_rsa_signature`

Request Sample Code

Here's a complete example of how to make authenticated requests to the Merchant API using RSA signatures:

// Node.js Example - Merchant API Request with RSA Signature
const crypto = require('crypto');
const fs = require('fs');
const axios = require('axios');

const generateRsaSignature = (privateKey, payload) => {
  // Create the exact same sorted string from the payload
  const stringToSign = Object.keys(payload)
    .filter(key => payload[key] != null && payload[key] !== '')
    .sort()
    .map(key => `${key}=${payload[key]}`)
    .join('&');

  // Sign the string with your private key
  const signature = crypto
    .createSign('RSA-SHA256')
    .update(stringToSign)
    .sign(privateKey, 'base64');

  return signature;
};

const makeMerchantRequest = async (
  baseUrl,
  method,
  url,
  payload,
  merchantCompanyAppId,
  apiKey,
  privateKey
) => {
  try {
    const rsaSignature = generateRsaSignature(privateKey, payload);
    
    const headers = {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
      'Authorization': `Bearer ${merchantCompanyAppId}`,
      'x-rsa-signature': rsaSignature,
    };

    const config = {
      method: method.toLowerCase(),
      url: `${baseUrl}${url}`,
      headers: headers,
      data: method.toLowerCase() !== 'get' ? payload : undefined
    };

    const response = await axios(config);
    return response.data;
  } catch (error) {
    console.error(`Error during request to ${url}:`, error.response?.data || error.message);
    throw error;
  }
};

// Example usage
const exampleRequest = async () => {
  const privateKey = fs.readFileSync('path/to/your_private_key.pem', 'utf-8');
  const merchantId = 'your_merchant_id';
  const apiKey = 'your_api_key';
  const baseUrl = 'https://api-solid-staging.switchwallet.io';
  
  // Example: Get merchant profile
  const payload = {
    requestTime: Date.now()
  };
  
  // Generate nonce for header
  const nonceStr = crypto.randomBytes(16).toString('hex');
  
  const response = await makeMerchantRequest(
    baseUrl,
    'GET',
    '/api/Merchant/profile',
    payload,
    merchantId,
    apiKey,
    privateKey,
    'NG'
  );
  
  console.log('Response:', response);
};

import requests
import time
import os
import base64
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives import serialization

def generate_rsa_signature(private_key_pem, payload):
    # Create the exact same sorted string from the payload
    string_to_sign = '&'.join([f"{k}={json.dumps(v) if isinstance(v, (dict, list)) else v}" for k, v in sorted(payload.items()) if v is not None and v != ''])

    private_key = serialization.load_pem_private_key(
        private_key_pem.encode(),
        password=None,
    )

    signature = private_key.sign(
        string_to_sign.encode('utf-8'),
        padding.PKCS1v15(),
        hashes.SHA256()
    )
    return base64.b64encode(signature).decode('utf-8')

def make_merchant_request(base_url, method, url, payload, merchant_company_app_id, api_key, private_key):
    try:
        rsa_signature = generate_rsa_signature(private_key, payload)
        
        headers = {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'x-api-key': api_key,
            'Authorization': f'Bearer {merchant_company_app_id}',
            'x-rsa-signature': rsa_signature,
        }
        
        full_url = f"{base_url}{url}"
        
        if method.lower() == 'get':
            response = requests.get(full_url, headers=headers)
        elif method.lower() == 'post':
            response = requests.post(full_url, headers=headers, json=payload)
        elif method.lower() == 'put':
            response = requests.put(full_url, headers=headers, json=payload)
        elif method.lower() == 'delete':
            response = requests.delete(full_url, headers=headers)
        else:
            raise ValueError(f"Unsupported method: {method}")
        
        return response.json()
        
    except Exception as error:
        print(f"Error during request to {url}: {error}")
        raise error

# Example usage
def example_request():
    with open('path/to/your_private_key.pem', 'r') as f:
        private_key_data = f.read()

    merchant_id = "your_merchant_id"
    api_key = "your_api_key"
    base_url = "https://api-solid-staging.switchwallet.io"
    
    # Example: Get merchant profile
    payload = {
        'requestTime': int(time.time() * 1000)
    }
    
    # Generate nonce for header
    nonce_str = os.urandom(16).hex()
    
    response = make_merchant_request(
        base_url,
        "GET",
        "/api/Merchant/profile",
        payload,
        merchant_id,
        api_key,
        private_key_data,
        "NG"
    )
    
    print("Response:", response)

# cURL Example - Merchant API Request with RSA Signature
# Replace the following variables with your actual values:
# - YOUR_API_KEY: Your API key
# - YOUR_MERCHANT_ID: Your merchant ID
# - YOUR_PRIVATE_KEY_PATH: Path to your private key file
# - TIMESTAMP: Current timestamp in milliseconds
# - NONCE_STRING: Random 32-character string
# - RSA_SIGNATURE: Generated RSA signature

# Step 1: Generate timestamp and nonce
TIMESTAMP=$(date +%s)000
NONCE_STRING=$(openssl rand -hex 16)

# Step 2: Prepare payload (for POST/PUT requests)
PAYLOAD='{"requestTime":"'$TIMESTAMP'"}'

# Step 3: Generate RSA signature
# Note: You'll need to implement this in your shell or use a tool
# RSA_SIGNATURE=$(echo -n "nonceStr=$NONCE_STRING&requestTime=$TIMESTAMP" | openssl dgst -sha256 -sign YOUR_PRIVATE_KEY_PATH | base64 -w 0)

# Step 4: Make the request
curl -X GET "https://api-solid-staging.switchwallet.io/api/Merchant/profile" \
  -H "Accept: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_MERCHANT_COMPANY_APP_ID" \
  -H "x-rsa-signature: RSA_SIGNATURE" \
  -H "x-request-timestamp: $TIMESTAMP" \
  -H "x-nonce-string: $NONCE_STRING" \

# Example POST request with payload
curl -X POST "https://api-solid-staging.switchwallet.io/api/Merchant/proxyfunds/transfer" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_MERCHANT_COMPANY_APP_ID" \
  -H "x-rsa-signature: RSA_SIGNATURE" \
  -H "x-request-timestamp: $TIMESTAMP" \
  -H "x-nonce-string: $NONCE_STRING" \
 \
  -d "$PAYLOAD"

Header Explanations

Authentication Headers

x-api-key: General API authorization key required for all requests
Authorization: Bearer token containing your Merchant Company App Id (found in merchant dashboard API Keys section)
x-rsa-signature: Base64-encoded RSA signature for request integrity verification
x-request-timestamp: Current timestamp in milliseconds for request freshness
x-nonce-string: Unique random string for each request to prevent replay attacks

Security & Context Headers

Accept: Specifies the expected response format (application/json)
Content-Type: Specifies the request body format (application/json)

Pagination

Endpoints that return a list of items are paginated. You can control the pagination using the following parameters in your request payload.

Parameter	Type	Description
pageId	number	The page number you want to retrieve. Starts at 1.
perPage	number	The number of items to return per page.
sort	string	The sort order. Accepts `ASC` for ascending or `DESC` for descending.

API Documentation

For a complete and interactive API reference, including all endpoints, request/response models, and the ability to try out API calls directly, please visit our API documentation.

for swagger lovers (link to the swagger docs)

Merchant API Documentation

Complete API reference for merchant operations and endpoints.