Recurring Payments

SaySwitch Recurring Payments lets you bill a customer automatically on a schedule after the customer authorizes their card and gives recurring-payment consent.

This documentation covers the server-to-server (S2S) API. Dashboard support is planned, but subscription management is not currently available from the merchant dashboard.

How It Works

Create or retrieve the customer through the Customers API.
Create a recurring payment plan.
Initialize a subscription with the customer’s code or email and the plan code.
Receive an authorization_url from SaySwitch.
Redirect the customer to the SaySwitch-hosted checkout.
The customer authorizes their card and gives recurring-payment consent.
SaySwitch activates the subscription after successful authorization.
SaySwitch processes later charges according to the plan schedule.
Your configured endpoint receives webhook notifications for subscription and charge events.

The customer and plan must already exist in the same test or live environment before you initialize a subscription.

Hosted Card Authorization

SaySwitch hosts the card authorization page. Redirect the customer to the exact authorization_url returned by the API.

Do not collect or send card numbers, CVVs, PINs, or other sensitive card information through your own server for this flow.

Base URL

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

Authentication

Recurring Payments endpoints require your secret key in the Authorization header:

Authorization: Bearer YOUR_SECRET_KEY

Use a test secret key for sandbox requests and a live secret key for production requests. Keep secret keys on your server and never expose them in frontend code.

Quick Start

1. Create a Plan

curl --request POST \
  --url https://backendapi.sayswitchgroup.com/api/v1/plan \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Email Monthly",
    "description": "Monthly access to the email service",
    "amount": 15000,
    "currency": "NGN",
    "interval": "monthly",
    "invoice_limit": 12
  }'

// Run secret-key requests on your server.
const response = await fetch("https://backendapi.sayswitchgroup.com/api/v1/plan", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Email Monthly",
    "description": "Monthly access to the email service",
    "amount": 15000,
    "currency": "NGN",
    "interval": "monthly",
    "invoice_limit": 12
  })
});
 
const responseBody = await response.text();
console.log(response.status, responseBody);

<?php
$request = curl_init('https://backendapi.sayswitchgroup.com/api/v1/plan');
 
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
    "name": "Email Monthly",
    "description": "Monthly access to the email service",
    "amount": 15000,
    "currency": "NGN",
    "interval": "monthly",
    "invoice_limit": 12
  }',
]);
 
$responseBody = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
 
echo $status . PHP_EOL;
echo $responseBody;

from urllib.request import Request, urlopen
 
payload = "{\n    \"name\": \"Email Monthly\",\n    \"description\": \"Monthly access to the email service\",\n    \"amount\": 15000,\n    \"currency\": \"NGN\",\n    \"interval\": \"monthly\",\n    \"invoice_limit\": 12\n  }".encode()
 
request = Request(
    "https://backendapi.sayswitchgroup.com/api/v1/plan",
    data=payload,
    method="POST",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
)
 
with urlopen(request) as response:
    response_body = response.read().decode()
    print(response.status, response_body)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
var body = """
    {
        "name": "Email Monthly",
        "description": "Monthly access to the email service",
        "amount": 15000,
        "currency": "NGN",
        "interval": "monthly",
        "invoice_limit": 12
      }
    """;
 
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://backendapi.sayswitchgroup.com/api/v1/plan"))
    .header("Authorization", "Bearer YOUR_SECRET_KEY")
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
 
var response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
 
System.out.println(response.statusCode());
System.out.println(response.body());

Save the returned plan_code.

2. Initialize a Subscription

curl --request POST \
  --url https://backendapi.sayswitchgroup.com/api/v1/subscription \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Idempotency-Key: email-subscription-test-001" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": "CUS_customer_code",
    "plan_code": "PLN_plan_code",
    "start_date": "2026-10-01T00:00:00+01:00",
    "return_url": "https://merchant.example/subscription/complete",
    "metadata": {
      "merchant_order_id": "EMAIL-ORDER-001"
    }
  }'

// Run secret-key requests on your server.
const response = await fetch("https://backendapi.sayswitchgroup.com/api/v1/subscription", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Idempotency-Key": "email-subscription-test-001",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "customer": "CUS_customer_code",
    "plan_code": "PLN_plan_code",
    "start_date": "2026-10-01T00:00:00+01:00",
    "return_url": "https://merchant.example/subscription/complete",
    "metadata": {
      "merchant_order_id": "EMAIL-ORDER-001"
    }
  })
});
 
const responseBody = await response.text();
console.log(response.status, responseBody);

<?php
$request = curl_init('https://backendapi.sayswitchgroup.com/api/v1/subscription');
 
curl_setopt_array($request, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_SECRET_KEY',
        'Idempotency-Key: email-subscription-test-001',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => '{
    "customer": "CUS_customer_code",
    "plan_code": "PLN_plan_code",
    "start_date": "2026-10-01T00:00:00+01:00",
    "return_url": "https://merchant.example/subscription/complete",
    "metadata": {
      "merchant_order_id": "EMAIL-ORDER-001"
    }
  }',
]);
 
$responseBody = curl_exec($request);
$status = curl_getinfo($request, CURLINFO_HTTP_CODE);
curl_close($request);
 
echo $status . PHP_EOL;
echo $responseBody;

from urllib.request import Request, urlopen
 
payload = "{\n    \"customer\": \"CUS_customer_code\",\n    \"plan_code\": \"PLN_plan_code\",\n    \"start_date\": \"2026-10-01T00:00:00+01:00\",\n    \"return_url\": \"https://merchant.example/subscription/complete\",\n    \"metadata\": {\n      \"merchant_order_id\": \"EMAIL-ORDER-001\"\n    }\n  }".encode()
 
request = Request(
    "https://backendapi.sayswitchgroup.com/api/v1/subscription",
    data=payload,
    method="POST",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Idempotency-Key": "email-subscription-test-001",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
)
 
with urlopen(request) as response:
    response_body = response.read().decode()
    print(response.status, response_body)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
var body = """
    {
        "customer": "CUS_customer_code",
        "plan_code": "PLN_plan_code",
        "start_date": "2026-10-01T00:00:00+01:00",
        "return_url": "https://merchant.example/subscription/complete",
        "metadata": {
          "merchant_order_id": "EMAIL-ORDER-001"
        }
      }
    """;
 
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://backendapi.sayswitchgroup.com/api/v1/subscription"))
    .header("Authorization", "Bearer YOUR_SECRET_KEY")
    .header("Idempotency-Key", "email-subscription-test-001")
    .header("Accept", "application/json")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString(body))
    .build();
 
var response = HttpClient.newHttpClient().send(
    request,
    HttpResponse.BodyHandlers.ofString()
);
 
System.out.println(response.statusCode());
System.out.println(response.body());

Redirect the customer to data.authorization_url. Treat the browser redirect as a convenience only; confirm the final subscription state through the API and webhooks.

Subscription Statuses

Status	Meaning
`pending_authorization`	The subscription was initialized and is waiting for the customer to open checkout.
`authorizing`	Card authorization is currently in progress.
`active`	Authorization succeeded and the subscription is eligible for scheduled billing.
`past_due`	The latest recurring charge failed or the subscription cannot currently be charged.
`cancelled`	The subscription was cancelled and no future charges will be scheduled.
`completed`	The plan’s `invoice_limit` was reached successfully.
`expired`	The hosted authorization session expired before authorization was completed.

Common API Errors

Missing authentication returns HTTP 401:

{
  "status": false,
  "message": "Merchant Authorization is required"
}

An invalid plain secret key also returns HTTP 401:

{
  "status": false,
  "message": "Invalid Secret Key"
}

Endpoint-specific validation errors return HTTP 422. A plan or subscription that cannot be found for the authenticated merchant and environment returns HTTP 404.

Next Steps

Sandbox Test Mode Create Plan