Accept PaymentsStandard Checkout

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.

This default payment endpoint settles into the merchant’s default wallet. To settle a standard checkout payment into a specific NGN wallet, use POST https://backendapi.sayswitchgroup.com/api/v1/transaction/initialize/wallet.

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",
    "payment_options": ["card", "transfer"]
}'

Request Parameters

ParameterTypeRequiredDescription
emailstringYesCustomer’s email address
amountstringYesTransaction amount
callbackstringYesURL to redirect after payment completion
currencystringYesCurrency code (e.g., NGN for Nigerian Naira)
payment_optionsarray/stringNoPayment methods to offer on the checkout page for this transaction. See Payment Options

Payment Options

Use payment_options to control which payment methods the customer sees on the checkout page for a single transaction. When you omit it, the checkout shows the payment methods enabled on your business account.

Supported Values

ValuePayment method
cardDebit/credit card
transferBank transfer
ussdUSSD
momoMobile money
opayOPay
palmpayPalmPay
walletWallet

Accepted Formats

Send either an array or a comma/pipe delimited string. All three of these are equivalent:

{ "payment_options": ["card", "transfer"] }
{ "payment_options": "card,transfer" }
{ "payment_options": "card|transfer" }

Values are matched case-insensitively; spaces are ignored and hyphens are treated as underscores. The following aliases are also accepted:

AliasResolves to
cardscard
bank, banktransfer, bank_transfer, bank-transfertransfer
mobilemoney, mobile_money, mobile-moneymomo

Duplicates are removed, so ["card", "cards"] is stored as ["card"].

payment_options applies only to the transaction it is sent with. It does not change the payment methods enabled on your account.

Unsupported Values

If any value is not recognised, the request is rejected with 400 and the supported values are returned:

{
    "success": false,
    "message": "Unsupported payment option(s): crypto",
    "supported_payment_options": [
        "card",
        "transfer",
        "ussd",
        "momo",
        "opay",
        "palmpay",
        "wallet"
    ]
}

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,
        "payment_options": [
            "card",
            "transfer"
        ]
    }
}

Response Fields

FieldTypeDescription
successbooleanTransaction initialization status
messagestringResponse message
data.authorization_urlstringURL to redirect customer for payment
data.access_codestringAccess code for this transaction
data.referencestringUnique transaction reference
data.payer_idstring/nullPayer identifier (null for new transactions)
data.payment_optionsarray/nullPayment methods applied to this checkout (null when none were requested)

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',
        payment_options: ['card', 'transfer']
    })
});
 
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,
        "payment_options": [
            "card",
            "transfer"
        ]
    }
}

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

FieldTypeDescription
successbooleanVerification request status
messagestringVerification response message
data.statusstringTransaction status (success, pending, failed)
data.amountstringFinal transaction amount including fees
data.requested_amountstringOriginal requested amount
data.feesstringTransaction fees charged
data.currencystringTransaction currency
data.referencestringTransaction reference
data.transaction_datestringTransaction completion timestamp
data.channelstringPayment channel used (card)
customer.emailstringCustomer email address
customer.customer_codestringUnique customer identifier
card.first6DigitsstringFirst 6 digits of the card
card.last4DigitsstringLast 4 digits of the card
card.typestringCard type (e.g., verve, visa, mastercard)
card.tokenstringTokenized card reference for future use
log.historyarrayTransaction processing history

Transaction Status Values

StatusDescription
successTransaction completed successfully
pendingTransaction is still being processed
failedTransaction failed or was declined