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
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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) |
| payment_options | array/string | No | Payment 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
| Value | Payment method |
|---|---|
card | Debit/credit card |
transfer | Bank transfer |
ussd | USSD |
momo | Mobile money |
opay | OPay |
palmpay | PalmPay |
wallet | Wallet |
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:
| Alias | Resolves to |
|---|---|
cards | card |
bank, banktransfer, bank_transfer, bank-transfer | transfer |
mobilemoney, mobile_money, mobile-money | momo |
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
| 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) |
| data.payment_options | array/null | Payment 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
| 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 |