Auth Login

Overview

The merchant login process authenticates your credentials and provides an access token that you'll use for all subsequent API requests. The login endpoint is specifically designed for merchants and differs from the admin login endpoint.

---

Login Endpoint

Base URL

POST /api/v2/auth/login

Full Endpoint Example

https://api.switchwallet.com/api/v2/auth/login

---

Request

Headers

Content-Type: application/json

Request Body

{
  "email": "[email protected]",
  "password": "YourPassword123!"
}

Field Descriptions

Field	Type	Required	Description
email	string	Yes	Your registered merchant email address
password	string	Yes	Your account password

---

Example Requests

cURL

curl -X POST "https://api.switchwallet.com/api/v2/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePassword123!"
  }'

JavaScript/Node.js

const login = async (email, password) => {
  const response = await fetch('https://api.switchwallet.com/api/v2/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: email,
      password: password
    })
  });
  
  return await response.json();
};

// Usage
const result = await login('[email protected]', 'SecurePassword123!');
console.log('Login Result:', result);

Python

import requests

def login(email, password):
    url = "https://api.switchwallet.com/api/v2/auth/login"
    payload = {
        "email": email,
        "password": password
    }
    headers = {
        "Content-Type": "application/json"
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# Usage
result = login("[email protected]", "SecurePassword123!")
print("Login Result:", result)

PHP

<?php
function login($email, $password) {
    $url = "https://api.switchwallet.com/api/v2/auth/login";
    $data = [
        "email" => $email,
        "password" => $password
    ];
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Usage
$result = login("[email protected]", "SecurePassword123!");
print_r($result);
?>

---

Success Response

HTTP Status: 200 OK

{
  "isSuccessful": true,
  "httpStatusCode": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
    "refreshToken": "refresh_token_here",
    "expiresAtTimestamp": 1704067200000,
    "email": "[email protected]",
    "businessName": "My Business Inc."
  },
  "roles": ["Merchant"]
}

Response Fields

Field	Type	Description
isSuccessful	boolean	Indicates if the login was successful
httpStatusCode	number	HTTP status code (200 for success)
message	string	Success message
data.token	string	Access token - Use this in the Authorization header for API requests
data.refreshToken	string	Token used to refresh your access token when it expires
data.expiresAtTimestamp	number	Unix timestamp (milliseconds) when the token expires
data.email	string	Your registered email address
data.businessName	string	Your business name
roles	array	Array of user roles (e.g., ["Merchant"])

---

Error Responses

Invalid Credentials

HTTP Status: 400 Bad Request

{
  "isSuccessful": false,
  "httpStatusCode": 400,
  "message": "Invalid Login Credentials"
}

Common Causes:

• Incorrect email address

• Incorrect password

• Email address not registered

---

---

Using Your Access Token

After successful login, include the token in all subsequent API requests using the Authorization header:

Format

Authorization: Bearer YOUR_TOKEN_HERE

Example Request with Token

curl -X GET "https://api.switchwallet.com/api/v2/merchant/wallets" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

JavaScript Example

const getWallets = async (token) => {
  const response = await fetch('https://api.switchwallet.com/api/v2/merchant/wallets', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  
  return await response.json();
};

// Usage
const loginResult = await login('[email protected]', 'password');
const wallets = await getWallets(loginResult.data.token);

---

Token Refresh

When your access token expires, use the refresh token to obtain a new access token.

Refresh Token Endpoint

GET /api/v2/auth/refreshToken?refreshToken=YOUR_REFRESH_TOKEN

Example

curl -X GET "https://api.switchwallet.com/api/v2/auth/refreshToken?refreshToken=your_refresh_token_here" \
  -H "Content-Type: application/json"

Response

{
  "isSuccessful": true,
  "httpStatusCode": 200,
  "data": {
    "token": "new_access_token_here",
    "refreshToken": "new_refresh_token_here",
    "expiresAtTimestamp": 1704153600000,
    "email": "[email protected]",
    "businessName": "My Business Inc."
  }
}

---

Complete Login Flow Example

JavaScript/Node.js

class SwitchWalletMerchant {
  constructor(baseUrl = 'https://api.switchwallet.com') {
    this.baseUrl = baseUrl;
    this.token = null;
    this.refreshToken = null;
  }

  async login(email, password) {
    try {
      const response = await fetch(`${this.baseUrl}/api/v2/auth/login`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ email, password })
      });

      const result = await response.json();

      if (result.isSuccessful) {
        this.token = result.data.token;
        this.refreshToken = result.data.refreshToken;
        console.log('Login successful!');
        console.log('Token expires at:', new Date(result.data.expiresAtTimestamp));
        return result;
      } else {
        throw new Error(result.message || 'Login failed');
      }
    } catch (error) {
      console.error('Login error:', error);
      throw error;
    }
  }

  async refreshAccessToken() {
    if (!this.refreshToken) {
      throw new Error('No refresh token available. Please login again.');
    }

    try {
      const response = await fetch(
        `${this.baseUrl}/api/v2/auth/refreshToken?refreshToken=${this.refreshToken}`,
        {
          method: 'GET',
          headers: {
            'Content-Type': 'application/json'
          }
        }
      );

      const result = await response.json();

      if (result.isSuccessful) {
        this.token = result.data.token;
        this.refreshToken = result.data.refreshToken;
        return result;
      } else {
        throw new Error('Token refresh failed');
      }
    } catch (error) {
      console.error('Token refresh error:', error);
      throw error;
    }
  }

  async makeAuthenticatedRequest(endpoint, options = {}) {
    if (!this.token) {
      throw new Error('Not logged in. Please call login() first.');
    }

    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    // If token expired, try to refresh and retry
    if (response.status === 401) {
      await this.refreshAccessToken();
      return this.makeAuthenticatedRequest(endpoint, options);
    }

    return await response.json();
  }
}

// Usage
const merchant = new SwitchWalletMerchant();

// Login
await merchant.login('[email protected]', 'SecurePassword123!');

// Make authenticated requests
const wallets = await merchant.makeAuthenticatedRequest('/api/v2/merchant/wallets');
const transactions = await merchant.makeAuthenticatedRequest('/api/v2/merchant/transactions');

---

Troubleshooting

Invalid Login Credentials

Problem: You're getting "Invalid Login Credentials" error.

Solutions:

• Verify your email address is correct (check for typos)

• Ensure your password is correct

• Make sure you're using the email you registered with

• Try resetting your password if you've forgotten it

Password Reset

If you've forgotten your password:

1. Request a password reset OTP: POST /api/v2/auth/password-reset/otp

2. Complete password reset: POST /api/v2/auth/password-reset

KYC/KYB Status Issues

Problem: Login is blocked due to KYC/KYB status.

Solutions:

• UnVerified: Complete your Know Your Business (KYB) verification

• Initiated/InProgress: Wait for verification to complete

• Rejected: Review the rejection reason and resubmit your KYB documents

Note: Sandbox accounts typically don't require KYC verification.

Token Expired

Problem: Your API requests are returning 401 Unauthorized.

Solutions:

• Use the refresh token endpoint to get a new access token

• If refresh token also expired, log in again to get new tokens

Email Not Found

Problem: Getting "Invalid Login Credentials" but email seems correct.

Solutions:

• Confirm you registered as a merchant (not admin)

• Check if you completed the registration process

• Contact support if you believe your account should exist

---

Security Best Practices

1. Never Share Your Credentials

   • Keep your email and password secure

   • Don't commit tokens to version control

   • Use environment variables for credentials

2. Token Storage

   • Store tokens securely (environment variables, secure storage)

   • Don't log tokens in console or files

   • Implement token refresh logic

3. HTTPS Only

   • Always use HTTPS endpoints

   • Never send credentials over unencrypted connections

4. Token Expiration

   • Monitor token expiration times

   • Implement automatic token refresh

   • Re-authenticate when refresh tokens expire

---

Merchant Login vs Admin Login

Important: This guide is for merchant login only.

• Merchant Login: POST /api/v2/auth/login (this guide)

• Admin Login: POST /api/v2/auth/admin/login (different endpoint, not covered here)

The merchant login endpoint:

• Requires a merchant account (not admin account)

• Validates merchant KYC/KYB status

• Returns merchant-specific data

• Has different authorization requirements

---

Next Steps After Login

Once you've successfully logged in:

1. Store Your Token - Save the access token for API requests

2. Check Wallet Status - Verify your wallet addresses are available

3. Review Account Settings - Check your merchant profile

4. Explore API Endpoints - Start making authenticated API calls

5. Set Up Webhooks - Configure payment notifications

---

API Reference Summary

Endpoint	Method	Description
/api/v2/auth/login	POST	Merchant login
/api/v2/auth/refreshToken	GET	Refresh access token
/api/v2/auth/password-reset/otp	POST	Request password reset OTP
/api/v2/auth/password-reset	POST	Complete password reset

---

Support

For additional help:

• Email: [email protected]

• Documentation: https://docs.switchwallet.com

• API Status: https://status.switchwallet.com

---

Last Updated: November 2025