Sayswitch - Developer Documentation

SaySwitch Standard Checkout Integration Guide

The Standard Checkout API allows you to initialize payment transactions and redirect customers to a secure SaySwitch checkout page to complete their payments.

Endpoint

POST https://backendapi.sayswitchgroup.com/api/v1/transaction/initialize

cURL Request

curl -X POST https://backendapi.sayswitchgroup.com/api/v1/transaction/initialize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -d '{
    "email": "test@gmail.com",
    "amount": "10",
    "callback": "https://google.com",
    "currency": "NGN"
}'

Request Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Customer’s email address
`amount`	string	Yes	Transaction amount
`callback`	string	Yes	URL to redirect after payment completion
`currency`	string	Yes	Currency code (e.g., NGN for Nigerian Naira)

Response Format

{
    "success": true,
    "message": "Authorization URL created",
    "data": {
        "authorization_url": "https://checkout.sayswitchgroup.com/pay/SSW_17482463876876919",
        "access_code": "cy2mfzkwqbl9",
        "reference": "SSW_17482463876876919",
        "payer_id": null
    }
}

Response Fields

Field	Type	Description
`success`	boolean	Transaction initialization status
`message`	string	Response message
`data.authorization_url`	string	URL to redirect customer for payment
`data.access_code`	string	Access code for this transaction
`data.reference`	string	Unique transaction reference
`data.payer_id`	string/null	Payer identifier (null for new transactions)

Transaction Flow

Initialize Transaction: Send a POST request to the Initialize Transaction endpoint with customer details and transaction amount
Get Authorization URL: The API returns a secure checkout URL in the authorization_url field
Redirect Customer: Direct the customer to the authorization URL(Sayswitch check out page) where they can complete their payment
Payment Processing: Customer completes payment on the SaySwitch secure checkout page
Callback Redirect: After payment completion, the customer is automatically redirected to your specified callback URL

Integration Steps

Step 1: Initialize the Transaction

Make a POST request to initialize the transaction:

const response = await fetch('https://backendapi.sayswitchgroup.com/api/v1/transaction/initialize', {
    method: 'POST',
   headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SECRET_API_KEY' // Replace with your actual API key 
  },
    body: JSON.stringify({
        email: 'customer@example.com',
        amount: '100.00',
        callback: 'https://yoursite.com/payment-callback',
        currency: 'NGN'
    })
});
 
const result = await response.json();

Step 2: Redirect to Checkout

Use the returned authorization URL to redirect your customer:

{
    "success": true,
    "message": "Authorization URL created",
    "data": {
        "authorization_url": "https://checkout.sayswitchgroup.com/pay/SSW_17485283875909552",
        "access_code": "bvgpovv29dc5",
        "reference": "SSW_17485283875909552",
        "payer_id": null
    }
}

Step 3 Verify Transaction

Endpoint

GET https://backendapi.sayswitchgroup.com/api/v1/your_referenceId

Verification of transaction is done by adding the reference of a specific transaction as URL path parameter

Example cURL Request

curl -X GET https://backendapi.sayswitchgroup.com/api/v1/SSW_17482573443162479 \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Response

{
    "success": true,
    "message": "Verification successful",
    "data": {
        "amount": "10.12",
        "currency": "NGN",
        "status": "success",
        "transaction_date": "2025-05-26 12:04:40",
        "reference": "SSW_17482573443162479",
        "domain": "live",
        "gateway_response": null,
        "channel": "card",
        "ip_address": null,
        "originator_name": "",
        "originator_account_number": "",
        "fees": "0.12",
        "plan": null,
        "requested_amount": "10"
    },
    "customer": {
        "id": 1340,
        "customer_code": "CUS_7ewvq2vt6zlqyij",
        "first_name": "",
        "last_name": "",
        "email": "johndoe@gmail.com"
    },
    "card": {
        "first6Digits": "506105",
        "last4Digits": "7163",
        "expiry": "0827",
        "type": "verve",
        "token": "ss-tkn-uoekyzfdvnttyqscdkemrhq9"
    },
    "log": {
        "time_spent": null,
        "attempts": null,
        "authentication": null,
        "errors": 2,
        "success": true,
        "channel": "card",
        "history": [
            {
                "id": 8133,
                "type": "PURCHASES",
                "message": "{\"transactionRef\":\"SSW_17482573443162479\",\"paymentId\":\"1933911626\",\"bankCode\":\"011\",\"message\":\"Kindly enter the OTP sent to 234706***9927\",\"amount\":\"10.12\",\"responseCode\":\"T0\",\"plainTextSuppo",
                "time": null,
                "reference": "SSW_17482573443162479",
                "channel": "interswitch",
                "ip_address": "102.89.83.206",
                "device": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
            },
            
        ]
    }
}

Verification Response Fields

Field	Type	Description
`success`	boolean	Verification request status
`message`	string	Verification response message
`data.status`	string	Transaction status (`success`, `pending`, `failed`)
`data.amount`	string	Final transaction amount including fees
`data.requested_amount`	string	Original requested amount
`data.fees`	string	Transaction fees charged
`data.currency`	string	Transaction currency
`data.reference`	string	Transaction reference
`data.transaction_date`	string	Transaction completion timestamp
`data.channel`	string	Payment channel used (card)
`customer.email`	string	Customer email address
`customer.customer_code`	string	Unique customer identifier
`card.first6Digits`	string	First 6 digits of the card
`card.last4Digits`	string	Last 4 digits of the card
`card.type`	string	Card type (e.g., verve, visa, mastercard)
`card.token`	string	Tokenized card reference for future use
`log.history`	array	Transaction processing history

Transaction Status Values

Status	Description
`success`	Transaction completed successfully
`pending`	Transaction is still being processed
`failed`	Transaction failed or was declined

Overview Overview