Industry Use Case & Integration Guide

Verticals Covered: Retail · Hospitality · Education

Use Cases: Payment Processing · Recurring Billing & Subscriptions

About This Guide

This document provides developer-focused use cases for integrating the SeerBit API across three key industry verticals. Each section describes a real-world scenario, outlines the recommended API flow, and provides sample request/response payloads to accelerate your integration.

1. Retail

Online Payments

Accept one-time or recurring payments on any channel with our API

Integration Checklist Integrations API Explorer

Plugins

Connect your existing commerce systems to our platform

WooCommerce Wix

Platforms

Accept payments on your platform or marketplace

Payout Payment Links Virtual Account Tokenization

In-Person Payments

Accelerate your in-store payments with our terminals and its API

The retail sector demands fast, reliable payment experiences, whether at the point of sale, on an e-commerce storefront, or through a mobile shopping app. SeerBit's API equips retail developers with the tools to accept payments, manage checkout flows, and run recurring billing for loyalty or subscription programs.

Use Case 1: E-Commerce Checkout Payment

Scenario

A customer adds items to their cart on an online retail platform and proceeds to checkout. The platform uses SeerBit's Standard Checkout API to collect card details, process the payment, and return a real-time transaction status to confirm the order.

When to Use This

Use this flow for one-time purchases on web or mobile storefronts where the customer pays per transaction, no subscription or installment plan involved.

API Flow

Action

Step

Customer initiates checkout, frontend collects card details or opens SeerBit's hosted payment page.

Backend calls POST /payments to initiate the transaction with order amount, currency, and customer details.

SeerBit processes the payment and returns a paymentStatus of SUCCESS, FAILED, or PENDING.

Backend updates the order status and notifies the customer via webhook or UI redirect.

Sample API Request

POST

/payments

POST https://seerbitapi.com/api/v2/payments 
Content-Type: application/json 
Authorization: Bearer <YOUR_SECRET_KEY> 
{ 
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx", 
  "amount": "15000.00", 
  "currency": "NGN", 
  "country": "NG", 
  "paymentReference": "RETAIL-ORD-20240201-0041", 
  "email": "customer@example.com", 
  "productId": "FASHION-STORE-001", 
  "productDescription": "Blue Denim Jacket (XL)", 
  "firstName": "Amaka", 
  "lastName": "Okonkwo", 
  "pocketReference": "", 
  "tokenize": false 
}

Sample API Response

200 OK — PAYMENT SUCCESFUL

{
  "status": "SUCCESS", 
  "data": { 
    "code": "00", 
    "payments": { 
      "paymentStatus": "SUCCESS", 
      "paymentReference": "RETAIL-ORD-20240201-0041", 
      "amount": "15000.00", 
      "currency": "NGN", 
      "gatewayMessage": "Approved", 
      "transactionId": "TXN_8823HY19201", 
      "linkingReference": "SB_LNK_0041291", 
      "maskedPan": "****4444", 
      "cardType": "VISA" 
    } 
  } 
}

Developer Notes

Always store linkingReference for reconciliation and refund operations.
Handle PENDING status with a webhook listener on your /webhook endpoint.
Set a unique paymentReference per transaction to prevent duplicate charges

Use Case 2: Retail Subscription & Loyalty Billing

Scenario

A retail brand offers a monthly VIP membership that gives subscribers exclusive discounts, early access to sales, and free shipping. After the customer's initial signup payment, the platform uses SeerBit's tokenization and subscription APIs to auto-charge the customer's card every 30 days without requiring them to re-enter their payment details.

When to Use This

Use this flow for any retail subscription product, premium memberships, monthly box services, or loyalty programs, where the customer's card must be charged on a recurring schedule.

API Flow

Action

Step

During the customer's first payment, include tokenize: true in the payment request to save their card.

SeerBit returns a cardToken tied to the customer's masked card details.

Store the cardToken and the customer's email securely in your database.

On each billing date, call POST /payments/charge with the stored cardToken to trigger the recurring charge.

Handle the webhook event payment.success or payment.failed to update the subscription status.

Step 1: Initial Payment with Tokenization

POST

/payments

POST https://seerbitapi.com/api/v2/payments 
Content-Type: application/json 
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "2500.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "VIP-SUB-SIGNUP-10029",
  "email": "customer@example.com",
  "productId": "VIP-MEMBERSHIP-MONTHLY",
  "productDescription": "VIP Monthly Membership - First Charge",
  "firstName": "Tunde",
  "lastName": "Adeyemi",
  "tokenize": true
}

RESPONSE - TOKEN RETURNED

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "paymentStatus": "SUCCESS",
      "paymentReference": "VIP-SUB-SIGNUP-10029",
      "cardToken": "TOK_7x9f3mNq2PKwR",
      "maskedPan": "****7891",
      "cardType": "MASTERCARD"
    }
  }
}

Step 2: Recurring Charge on Billing Date

POST

/payments/charge

POST https://seerbitapi.com/api/v2/payments/charge
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "2500.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "VIP-SUB-RENEW-10030",
  "email": "customer@example.com",
  "cardToken": "TOK_7x9f3mNq2PKwR",
  "productId": "VIP-MEMBERSHIP-MONTHLY",
  "productDescription": "VIP Monthly Membership - Renewal"
}

Developer Notes

Schedule recurring charges using a cron job or a task queue (e.g., Celery, Bull, or AWS EventBridge).
Always generate a new unique paymentReference for each renewal cycle.
If a charge fails, retry with exponential backoff and notify the customer to update their card.
Offer a customer portal to cancel subscriptions, this reduces disputes and chargebacks.

2. Hospitality

Online Payments

Accept one-time or recurring payments on any channel with our API

Integration Checklist Integrations API Explorer

Plugins

Connect your existing commerce systems to our platform

WooCommerce Wix

Platforms

Accept payments on your platform or marketplace

Payout Payment Links Virtual Account Tokenization

In-Person Payments

Accelerate your in-store payments with our terminals and its API

Hotels, restaurants, travel agencies, and event venues operate in an industry where guest experience is paramount. SeerBit's API helps hospitality businesses accept deposits, process bookings, manage split payments, and automate recurring charges for loyalty memberships and reservation platforms.

Use Case 1: Hotel Booking & Deposit Payment

Scenario

A hotel booking platform allows guests to reserve rooms online. To confirm a reservation, the guest pays a deposit upfront. The platform uses SeerBit's API to initiate the deposit payment, validate it in real-time, and store the booking record. Any outstanding balance is then settled at checkout.

When to Use This

Use this flow for any hospitality platform processing upfront booking payments, reservation deposits, or full prepaid stays through a web or mobile interface.

API Flow

Action

Step

Guest selects a room and check-in/check-out dates on the booking platform.

Backend calculates the deposit amount (e.g., 30% of total stay) and calls POST /payments.

SeerBit processes the deposit and returns a transactionId and paymentStatus.

Platform saves the booking record with the transactionId for reconciliation at checkout.

On checkout, the platform charges the remaining balance using the stored card token (if tokenized).

Sample API Request: Booking Deposit

POST

/payments

POST https://seerbitapi.com/api/v2/payments
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "45000.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "HTL-BOOK-20240315-BKG881",
  "email": "guest@example.com",
  "productId": "HOTEL-DELUXE-DBL-101",
  "productDescription": "Deluxe Double Room - Deposit (3 Nights)",
  "firstName": "Chioma",
  "lastName": "Eze",
  "pocketReference": "",
  "tokenize": true
}

Sample API Response

200 OK — DEPOSIT CONFIRMED

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "paymentStatus": "SUCCESS",
      "paymentReference": "HTL-BOOK-20240315-BKG881",
      "amount": "45000.00",
      "currency": "NGN",
      "transactionId": "TXN_HT99128821",
      "linkingReference": "SB_LNK_HTL_0039281",
      "cardToken": "TOK_cH2k8rPw5Lx",
      "maskedPan": "****2290",
      "cardType": "VISA"
    }
  }
}

Developer Notes

Store transactionId and cardToken against the booking record in your database.
Use the cardToken to charge the outstanding balance at guest checkout.
Implement a webhook listener to handle payment.pending for 3DS-authenticated transactions.
For refundable deposits, use the SeerBit Refund API (POST /payments/refund) upon cancellation.

Use Case 2: Hotel Loyalty Programme Subscription

Scenario

A hotel chain runs a tiered loyalty programme. Members pay a monthly subscription fee to maintain their loyalty tier — which unlocks perks like room upgrades, late checkouts, and complimentary breakfast. The hotel platform uses SeerBit's recurring billing flow to charge members automatically each month.

When to Use This

Use this for subscription-based loyalty or membership programs in the hospitality sector where the customer's card must be charged on a defined recurring interval (monthly, quarterly, or annually).

API Flow

Action

Step

Customer signs up for the loyalty plan and completes their first payment with tokenize: true.

Platform receives and stores the cardToken linked to the customer's loyalty account.

Billing scheduler (cron job) triggers POST /payments/charge on each renewal date.

SeerBit returns paymentStatus, platform updates the member's tier accordingly.

Webhook events (payment.success / payment.failed) drive automated email notifications.

Step 1: Enrolment & First Charge

POST

/payments

POST https://seerbitapi.com/api/v2/payments
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "5000.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "LOYALTY-ENROL-GOLD-77102",
  "email": "member@example.com",
  "productId": "LOYALTY-GOLD-MONTHLY",
  "productDescription": "Gold Tier Loyalty Membership - First Month",
  "firstName": "Emeka",
  "lastName": "Nwosu",
  "tokenize": true
}

Step 2: Monthly Renewal Charge

POST

/payments/charge

POST https://seerbitapi.com/api/v2/payments/charge
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "5000.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "LOYALTY-RENEW-GOLD-77103",
  "email": "member@example.com",
  "cardToken": "TOK_gK3m1pNr8Qv",
  "productId": "LOYALTY-GOLD-MONTHLY",
  "productDescription": "Gold Tier Loyalty Membership - Monthly Renewal"
}

Developer Notes

Downgrade the customer's tier gracefully if a renewal charge fails (e.g., move to free tier).
Send reminder emails 3 days before each billing date to reduce failed charges from expired cards.
Use SeerBit's webhook to trigger real-time tier status updates in your CRM.
Store a billing_history array per customer for transparency and dispute resolution.

3. Education

Online Payments

Accept one-time or recurring payments on any channel with our API

Integration Checklist Integrations API Explorer

Plugins

Connect your existing commerce systems to our platform

WooCommerce Wix

Platforms

Accept payments on your platform or marketplace

Payout Payment Links Virtual Account Tokenization

In-Person Payments

Accelerate your in-store payments with our terminals and its API

EdTech platforms, universities, online learning providers, and private schools require flexible payment solutions — from accepting one-time tuition payments to managing recurring course subscriptions. SeerBit's API enables education platforms to deliver seamless, secure payment experiences for students and institutions alike.

Use Case 1: School Fees & Tuition Payment

Scenario

A private secondary school uses an online payment portal to collect tuition fees each term. Parents or guardians log in, select their ward's class and term, and pay via card or bank transfer. The platform integrates SeerBit's API to process the payment and automatically update the student's payment record in the school management system.

When to Use This

Use this flow for one-time tuition or fee payments on education portals, including exam registration fees, school supply charges, extracurricular activity fees, or any single-instance payment tied to a student record.

API Flow

Action

Step

Parent logs in, selects the term/class, and is presented with the fee amount and payment options.

Backend calls POST /payments with the student's ID embedded in paymentReference for traceability.

SeerBit processes the payment and returns paymentStatus and transactionId.

Backend marks the student's fee record as PAID in the school management system via the webhook event.

A digital receipt is generated and emailed to the parent.

Sample API Request: Tuition Payment

POST

/payments

POST https://seerbitapi.com/api/v2/payments
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "120000.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "SCH-FEE-STD00291-TERM2-2024",
  "email": "parent@example.com",
  "productId": "TERM-FEE-JSS3",
  "productDescription": "JSS3 Second Term Tuition Fee - 2024",
  "firstName": "Ngozi",
  "lastName": "Obiora",
  "pocketReference": "",
  "tokenize": false
}

Sample API Response

200 OK — FEE PAYMENT CONFIRMED

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "paymentStatus": "SUCCESS",
      "paymentReference": "SCH-FEE-STD00291-TERM2-2024",
      "amount": "120000.00",
      "currency": "NGN",
      "transactionId": "TXN_EDU88227711",
      "linkingReference": "SB_LNK_EDU_0019203",
      "gatewayMessage": "Approved"
    }
  }
}

Developer Notes

Encode the studentId and term in paymentReference (e.g., SCH-FEE-{studentId}-TERM{n}-{year}) for easy reconciliation.
Trigger a webhook to your school management system to auto-update fee records in real-time.
For partial payments (instalments), track cumulative payments per term against the fee total.
Use SeerBit's dashboard to generate payment reports per class, grade, or term.

Use Case 2: Online Learning Platform Subscription

Scenario

An EdTech platform offers monthly and annual subscription plans for access to its library of video courses, quizzes, and certificates. After a student signs up and completes their first payment, the platform auto-renews the subscription using SeerBit's card tokenization, ensuring uninterrupted access to learning content.

When to Use This

Use this flow for EdTech subscription models, monthly or annual course access, tutoring session bundles, premium account plans, or any recurring digital education service.

API Flow

Action

Step

Student selects a subscription plan (monthly/annual) and completes the first payment with tokenize: true.

Platform stores the returned cardToken against the student's account.

Billing scheduler triggers POST /payments/charge on each renewal date (monthly or annually).

On success, student's subscription is extended; on failure, access is paused and the student is notified.

Webhook events update subscription status in real-time across your platform.

Step 1: Subscription Signup & First Payment

POST

/payments

POST https://seerbitapi.com/api/v2/payments
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "3500.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "EDTECH-SUB-MONTHLY-USR44821",
  "email": "student@example.com",
  "productId": "EDTECH-MONTHLY-PLAN",
  "productDescription": "Monthly Learning Subscription - All-Access Plan",
  "firstName": "Bola",
  "lastName": "Fashola",
  "tokenize": true
}

RESPONSE - SUBSCRIPTION CREATED

{
  "status": "SUCCESS",
  "data": {
    "code": "00",
    "payments": {
      "paymentStatus": "SUCCESS",
      "paymentReference": "EDTECH-SUB-MONTHLY-USR44821",
      "cardToken": "TOK_eL5n2wYt7Zr",
      "maskedPan": "****5566",
      "cardType": "MASTERCARD",
      "transactionId": "TXN_EDTECH_7710293"
    }
  }
}

Step 2: Auto-Renewal Charge

POST

/payments/charge

POST https://seerbitapi.com/api/v2/payments/charge
Content-Type: application/json
Authorization: Bearer <YOUR_SECRET_KEY>
{
  "publicKey": "SBTESTPUBK_xxxxxxxxxxxxxxxxxxxx",
  "amount": "3500.00",
  "currency": "NGN",
  "country": "NG",
  "paymentReference": "EDTECH-RENEW-MONTHLY-USR44821-2",
  "email": "student@example.com",
  "cardToken": "TOK_eL5n2wYt7Zr",
  "productId": "EDTECH-MONTHLY-PLAN",
  "productDescription": "Monthly Learning Subscription - Renewal"
}

Developer Notes

Offer a free trial by delaying the first renewal charge, still tokenize on signup.
For annual plans, generate a unique paymentReference with the plan year (e.g., EDTECH-ANNUAL-USR44821-2025).
Pause access immediately upon failed payment but give a 3-day grace period with retry logic.
Provide students with a self-service page to update their card or cancel subscriptions.

SeerBit API Documentation · For developer support visit: https://seerbitteam.freshdesk.com/support/home.