Accept PaymentsServer to ServerCard

Card Payments (S2S)

Overview

Process secure card payments using Sayswitch’s Server-to-Server (S2S) API. This integration allows you to handle card transactions directly from your backend while keeping sensitive card data secure.

Quick Start Guide

Card payments with Sayswitch follow a simple 4-step process:

  1. Encrypt card details → Get a secure card token
  2. Initialize payment → Start the transaction
  3. Handle OTP verification → Customer completes 3DS authentication
  4. Verify transaction → Confirm payment status

Step 1: Encrypt Card Details

Before processing any payment, you must first encrypt the card details to ensure security.

Endpoint

POST https://backendapi.sayswitchgroup.com/api/s2s/test/encryption

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer sk_test_your_secret_key_here"
}

Request Body

{
    "data": {
        "number": "4111111111111111",
        "expiryMonth": "12",
        "expiryYear": "28",
        "cvv": "123"
    },
    "reference": "TEST_REF_2025_001"
}

cURL Example

curl --location 'https://backendapi.sayswitchgroup.com/api/s2s/test/encryption' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_test_your_secret_key_here' \
--data '{
    "data": {
        "number": "4111111111111111",
        "expiryMonth": "12",
        "expiryYear": "28",
        "cvv": "123"
    },
    "reference": "TEST_REF_2025_001"
}'

Response

{
    "status": true,
    "message": "Card encrypted successfully",
    "data": {
        "encryptedCard": "mock_encrypted_card_token_1234567890abcdef",
        "reference": "TEST_REF_2025_001"
    }
}

💡 Important: Save the encryptedCard value - you’ll need it for the next step.

Step 2: Initialize Payment

Use the encrypted card token to start the payment process.

Endpoint

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

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer sk_test_your_secret_key_here"
}

Request Body

{
    "amount": "10.00",
    "card": "mock_encrypted_card_token_1234567890abcdef",
    "currency": "NGN",
    "email": "test@example.com",
    "pin": "1234",
    "reference": "TEST_TXN_REF_001"
}

Response

{
    "status": true,
    "message": "Kindly enter the OTP sent to 234706***9927",
    "data": {
        "paymentid": "1933565739",
        "supportMessage": "Didn't get the OTP? Dial *322*0# on your phone",
        "_links": {
            "url": "https://backendapi.sayswitchgroup.com/api/i5678930tyuhjns-cardotp",
            "method": "POST",
            "payload": ["otp", "ref", "payid"]
        }
    }
}

📱 Next Step: Customer receives an OTP on their phone and needs to complete verification.

Step 3: Handle OTP Verification

After Step 2, redirect your customer to complete OTP verification on Sayswitch’s secure page.

What Happens:

  1. Customer receives OTP on their registered phone number
  2. Customer is redirected to: https://backendapi.sayswitchgroup.com/api/i5678930tyuhjns
  3. Customer enters OTP on the secure page
  4. Sayswitch processes the verification automatically

OTP Verification Parameters

The verification page handles these parameters automatically:

ParameterDescription
otpOne-time password sent to customer
refYour transaction reference (TEST_TXN_REF_001)
payidPayment ID from Step 2 response (1933565739)

Step 4: Verify Transaction Status

After OTP verification, check the final transaction status.

Endpoint

GET https://backendapi.sayswitchgroup.com/api/s2s/{reference}

Headers

{
  "Authorization": "Bearer sk_test_your_secret_key_here",
  "Content-Type": "application/json"
}

Example Request

GET https://backendapi.sayswitchgroup.com/api/s2s/TEST_TXN_REF_001

Success Response

{
    "success": true,
    "message": "Verification successful",
    "data": {
        "amount": "10.12",
        "currency": "NGN",
        "status": "success",
        "transaction_date": "2025-10-01 08:52:23",
        "reference": "TEST_TXN_REF_001",
        "channel": "card",
        "fees": "0.12",
        "requested_amount": "10.00"
    },
    "customer": {
        "email": "test@example.com",
        "customer_code": "CUS_7ewvq2vt6zlqyij"
    },
    "card": {
        "first6Digits": "411111",
        "last4Digits": "1111",
        "type": "visa",
        "token": "ss-tkn-fin1refv13noydilm77dhske"
    }
}

Transaction Statuses

StatusDescription
successPayment completed successfully
pendingPayment is still processing
failedPayment failed or was declined

Complete Integration Example

Here’s how all the steps work together:

// Step 1: Encrypt card details
const encryptResponse = await fetch('https://backendapi.sayswitchgroup.com/api/s2s/test/encryption', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_test_your_secret_key_here'
  },
  body: JSON.stringify({
    data: {
      number: "4111111111111111",
      expiryMonth: "12",
      expiryYear: "28",
      cvv: "123"
    },
    reference: "TEST_REF_2025_001"
  })
});
 
const { data: { encryptedCard } } = await encryptResponse.json();
 
// Step 2: Initialize payment
const paymentResponse = await fetch('https://backendapi.sayswitchgroup.com/api/s2s/transaction/initialize', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_test_your_secret_key_here'
  },
  body: JSON.stringify({
    amount: "10.00",
    card: encryptedCard,
    currency: "NGN",
    email: "test@example.com",
    pin: "1234",
    reference: "TEST_TXN_REF_001"
  })
});
 
const paymentData = await paymentResponse.json();
 
// Step 3: Redirect customer to OTP page
window.location.href = paymentData.data._links.url;
 
// Step 4: Verify transaction (after customer completes OTP)
const verifyResponse = await fetch('https://backendapi.sayswitchgroup.com/api/s2s/TEST_TXN_REF_001', {
  headers: {
    'Authorization': 'Bearer sk_test_your_secret_key_here'
  }
});
 
const verification = await verifyResponse.json();
console.log('Payment status:', verification.data.status);

Request Parameters Reference

Card Encryption Parameters

ParameterTypeRequiredDescription
data.numberstringYesCard number (16 digits)
data.expiryMonthstringYesExpiry month (MM format)
data.expiryYearstringYesExpiry year (YY format)
data.cvvstringYesCard security code
referencestringYesUnique encryption reference

Payment Initialization Parameters

ParameterTypeRequiredDescription
amountstringYesPayment amount
cardstringYesEncrypted card token from Step 1
currencystringYesCurrency code (NGN, USD, etc.)
emailstringYesCustomer email address
pinstringYesCard PIN
referencestringYesUnique transaction reference

Need Help?

🔒 Security Note: Never store or log actual card details. Always use the encryption endpoint first.

OverviewBank Transfer