Payout - SeerBit Documentation

The SeerBit Pocket Payout API enables merchants to initiate single or bulk bank transfers directly from their SeerBit Pocket. This page covers all the steps required to authenticate, sign, initiate, and confirm a payout — along with error handling references and a supported bank list endpoint.

Payouts are live only. Payouts are sent from your Pocket, and Pocket has no test mode — no test keys and no sandbox. Every payout sends real money to a real bank account, so use small amounts to an account you control while you integrate.

Prerequisites — Please read before integrating

Request Signature Verification: All requests must include a valid X-Seerbit-Signature header. This signature is generated using an HMAC-SHA256 hash of the raw HTTP request body, signed with your API Secret Key. Your Private Key is available under Settings on your SeerBit Dashboard — store it securely and never expose it publicly.

Payout Authorization: Every payout must be authorized with a second factor before it is processed — an email OTP by default, or an authenticator app code or transaction PIN if your pocket requires one. See Two-factor authentication.

Process Flow

Authenticate

Get Bearer Token

Generate Signature

HMAC-SHA256

Initiate Payout

Single or Bulk

Confirm Payout

OTP, Authenticator or PIN

Step 1 — Authenticate

POST

https://pocket.seerbitapi.com/pocket/authenticate

Generates a Bearer Token required to authenticate all subsequent API calls. Submit your merchant email and password to receive a time-limited token.

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/authenticate' \
--header 'Content-Type: application/json' \
--data-raw '{
  "email": "johndoe@email.com",
  "password": "Password1"
}'

Response Sample

{
  "responseCode": "00",
  "message": "Success",
  "data": {
    "bearerToken": "{{bearerToken}}",
    "expiryTime": "2025-02-26T01:38:37",
    "requirePasswordChange": false
  }
}

Step 2 — Generate X-Seerbit-Signature

Before initiating a payout, generate an X-Seerbit-Signature using the exact raw request body and your SeerBit Private Key. Pass the resulting hash as a header on every payout request.

Note: The signature is unique to each request. Always regenerate it using the exact body of each new request before sending.

Signature Formula

signature = HMAC_SHA256(raw_request_body, private_key)

const CryptoJS = require('crypto-js');

const rawBody = JSON.stringify(requestPayload);
const privateKey = 'your_private_key_here';

const signature = CryptoJS.HmacSHA256(rawBody, privateKey).toString(CryptoJS.enc.Hex);

const crypto = require('crypto');

const rawBody = JSON.stringify(requestPayload);
const privateKey = 'your_private_key_here';

const signature = crypto.createHmac('sha256', privateKey).update(rawBody).digest('hex');

$rawBody = json_encode($requestPayload);
$privateKey = "your_private_key_here";

$signature = hash_hmac("sha256", $rawBody, $privateKey);

import hmac
import hashlib
import json

raw_body = json.dumps(request_payload, separators=(',', ':'))
private_key = "your_private_key_here"

signature = hmac.new(
    private_key.encode("utf-8"),
    raw_body.encode("utf-8"),
    hashlib.sha256
).hexdigest()

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

String rawBody = objectMapper.writeValueAsString(requestPayload);
String privateKey = "your_private_key_here";

Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(privateKey.getBytes("UTF-8"), "HmacSHA256");
mac.init(secretKey);

byte[] rawHmac = mac.doFinal(rawBody.getBytes("UTF-8"));

StringBuilder signature = new StringBuilder();
for (byte b : rawHmac) {
    signature.append(String.format("%02x", b));
}

using System.Security.Cryptography;
using System.Text;

string rawBody = JsonSerializer.Serialize(requestPayload);
string privateKey = "your_private_key_here";

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(privateKey));
byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));

string signature = Convert.ToHexString(hash).ToLower();

Variables Reference

Variable	Description
`rawBody`	The exact request payload serialized as a raw JSON string. Must match the body sent in the request byte-for-byte.
`privateKey`	Your SeerBit Private Key from the dashboard under Settings.
`signature`	The generated lowercase hex string. Pass this as the value of the `X-Seerbit-Signature` header.

Step 3 — Initiate Payout

POST

https://pocket.seerbitapi.com/pocket/v2/payouts

Initiates a payout from your SeerBit Pocket. Supports both single and bulk transfer modes. All requests must include the Bearer Token, Public Key, and X-Seerbit-Signature headers.

Required Headers

Header	Value
Authorization	Bearer `{{bearerToken}}`
Public-Key	`{{publicKey}}`
X-Seerbit-Signature	`{{signature}}`

Single Payout

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/v2/payouts' \
--header 'Content-Type: application/json' \
--header 'Public-Key: {{publicKey}}' \
--header 'X-Seerbit-Signature: {{signature}}' \
--header 'Authorization: Bearer {{bearerToken}}' \
--data '{
  "pocketId": "SBP0000123",
  "reference": "uniqueTransferReference",
  "currency": "NGN",
  "amount": 50.00,
  "description": "Payout Sample",
  "accountNumber": "0123456789",
  "bankCode": "000014",
  "accountName": "John Doe"
}'

Response Sample

{
  "payoutId": "PV2-y3j1m0kohbueTy",
  "status": "PENDING_OTP",
  "channel": "EMAIL",
  "message": "OTP sent to registered email. Please confirm to proceed."
}

channel tells you which code to ask the user for when you confirm the payout: EMAIL, TOTP, PIN, REQUIRED_TOTP or REQUIRED_PIN. An email is sent only on EMAIL. See How payout authorization works. Sending the same reference again while the payout is still PENDING_OTP returns the existing payoutId without creating a second payout or sending a new code.

Request Fields

Field	Description
`pocketId`	Identifier of the merchant pocket initiating the payout
`reference`	Unique transaction reference for idempotency
`currency`	Currency code (e.g., NGN)
`amount`	Payout amount
`description`	Narration for the transaction
`accountNumber`	Beneficiary bank account number
`bankCode`	Six-digit NIP code of the receiving bank — see Bank codes
`accountName`	Optional. Name of the account holder. SeerBit always runs a bank name enquiry; if you send `accountName`, at least two of its words must match the enquiry result (case-insensitive), or the transfer fails with `SM_06`. If you omit it, the enquiry result is used.

Bulk Payout

Bulk payouts allow multiple transfer instructions to be processed in a single request. Each transfer is validated and executed under a single batchReference.

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/v2/payouts' \
--header 'Content-Type: application/json' \
--header 'Public-Key: {{publicKey}}' \
--header 'X-Seerbit-Signature: {{signature}}' \
--header 'Authorization: Bearer {{bearerToken}}' \
--data '{
  "pocketId": "SBP0018786",
  "batchReference": "bulkreferencesalaryjuly202y",
  "transfers": [
    {
      "reference": "111111111",
      "currency": "NGN",
      "amount": 50.00,
      "description": "Payment to vendor A",
      "accountNumber": "0123456789",
      "bankCode": "000014",
      "accountName": "John Doe"
    },
    {
      "reference": "22222222",
      "currency": "NGN",
      "amount": 50.00,
      "description": "Payment to vendor B",
      "accountNumber": "0123456798",
      "bankCode": "000014",
      "accountName": "Thomas Doe"
    },
    {
      "reference": "22222223",
      "currency": "NGN",
      "amount": 50.00,
      "description": "Payment to vendor C",
      "accountNumber": "0123456987",
      "bankCode": "100004",
      "accountName": "Linda Doe"
    }
  ]
}'

Response Sample

{
  "payoutId": "PV2-y3j1m0kohbue",
  "status": "PENDING_OTP",
  "channel": "EMAIL",
  "message": "OTP sent to registered email. Please confirm to proceed."
}

Sending the same batchReference again while the batch is still PENDING_OTP returns the existing payoutId.

Request Fields

Field	Description
`pocketId`	Identifier of the merchant pocket initiating the payout
`batchReference`	Unique identifier for the entire bulk batch (used for idempotency)
`transfers`	Array of individual payout instructions

Each transfers object contains:

Field	Description
`reference`	Unique transaction reference per transfer
`currency`	Currency code (e.g., NGN)
`amount`	Transfer amount
`description`	Transaction narration
`accountNumber`	Beneficiary bank account number
`bankCode`	Six-digit NIP code of the receiving bank — see Bank codes
`accountName`	Optional. Name of the account holder. SeerBit always runs a bank name enquiry; if you send `accountName`, at least two of its words must match the enquiry result (case-insensitive), or the transfer fails with `SM_06`. If you omit it, the enquiry result is used.

Step 4 — Confirm Payout

POST

https://pocket.seerbitapi.com/pocket/v2/payouts/{{payoutId}}/confirm

After a payout is initiated, authorize it by submitting a code. The initiation response’s channel field tells you which code to ask the user for — see How payout authorization works:

Email OTP (channel: "EMAIL", the default) — sent to the pocket owner’s email and primary signatories when you initiate the payout. It is valid for 5 minutes.
Authenticator code — the 6-digit code from the user’s authenticator app (channel: "TOTP" or "REQUIRED_TOTP"). No email is sent.
Transaction PIN — the user’s PIN (channel: "PIN" or "REQUIRED_PIN"). No email is sent.
Recovery code — accepted in place of an authenticator code or PIN.

To set up an authenticator app or PIN, see Two-factor authentication.

Required Headers

Header	Value
Authorization	Bearer `{{bearerToken}}`
Public-Key	`{{publicKey}}`
X-Seerbit-Signature	`{{signature}}`

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/v2/payouts/{{payoutId}}/confirm' \
--header 'Content-Type: application/json' \
--header 'Public-Key: {{publicKey}}' \
--header 'X-Seerbit-Signature: {{signature}}' \
--header 'Authorization: Bearer {{bearerToken}}' \
--data '{
  "code": "740714"
}'

Response Sample

{
  "payoutId": "PV2-y3j1m0kohbue",
  "status": "QUEUED",
  "message": "Payout confirmed and queued for processing",
  "batchId": null
}

{
  "payoutId": "PV2-y3j1m0kohbue",
  "status": "QUEUED",
  "message": "Payout confirmed and queued for processing",
  "batchId": "iytgfr7"
}

QUEUED means the payout has been authorized and handed off for processing; it moves to PROCESSING next.

Request Fields

Field	Description
`payoutId`	The unique identifier returned from the payout initiation response
`code`	The authorization code: an email OTP, authenticator code, transaction PIN or recovery code, matching the `channel` in the initiation response. `otp` is still accepted for older integrations.

Bank List

GET

https://pocket.seerbitapi.com/pocket/banks/category/NIP

Returns a list of supported Nigerian banks and their corresponding bank codes. Use this to look up the correct bankCode before initiating a payout. For a quick lookup while you build, see Bank codes.

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/banks/category/NIP' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN_HERE' \
--header 'Public-Key: your_public_key_here'

Account Name Enquiry

POST

https://pocket.seerbitapi.com/pocket/authenticate/name-enquiry

Looks up the name on a bank account before you pay it. Use it to show the user who they are about to pay, so they can catch a wrong account number before the money moves.

Request Sample

cURL

curl --location 'https://pocket.seerbitapi.com/pocket/authenticate/name-enquiry' \
--header 'Content-Type: application/json' \
--data '{
  "bankcode": "000013",
  "accountnumber": "0123456789"
}'

Request Fields

Field	Description
`bankcode`	Six-digit NIP code of the bank — see Bank codes or the bank list
`accountnumber`	The account number to look up

Note: The field names here are all lowercase (bankcode, accountnumber), unlike the camelCase bankCode and accountNumber in payout requests.

SeerBit also runs a name enquiry on every payout. If you send accountName in the payout request, it must match the enquiry result — so looking the name up first and passing it through avoids a mismatch.

Error Scenarios

The following error responses may occur during payout initiation or confirmation flows.

1. Missing Signature Header

Occurs when the X-Seerbit-Signature header is absent from the request.

{
  "payoutId": null,
  "status": "FAILED",
  "message": "Incorrect Signature, cannot process payout"
}

2. Invalid Signature

Occurs when the provided signature fails HMAC validation.

{
  "payoutId": null,
  "status": "FAILED",
  "message": "Incorrect Signature, cannot process payout"
}

3. Missing Public Key Header

Occurs when the Public-Key header is not included in the request.

{
  "responseCode": "SM_06",
  "message": "Public key is required",
  "debugMessage": "Public key is required",
  "error": "PROCESSING",
  "timestamp": "2026-05-30T00:34:38"
}

4. Invalid Code

The code is wrong, or the wrong factor for the challenge (for example, a PIN on a TOTP challenge). The payout stays PENDING_OTP — ask the user to re-enter the code and confirm the same payoutId again.

{
  "payoutId": "PV2-zfijs7wd42hq",
  "status": "FAILED",
  "message": "Invalid TOTP code",
  "batchId": null
}

5. Too Many Failed Attempts

Five consecutive wrong codes lock authorization for 15 minutes. A correct code resets the count.

Account locked due to too many failed attempts. Try again later.

6. Expired Email OTP

An email OTP is valid for 5 minutes. After that the payout can’t be confirmed — initiate a new payout.

OTP has expired. Please initiate a new payout request.

7. Insufficient Balance at Confirmation

If the pocket balance is too low when you confirm, the payout fails permanently. It can’t be confirmed again; fund the pocket and initiate a new payout with a new reference.

{
  "payoutId": "PV2-oysfdz48nivm",
  "status": "FAILED",
  "message": "Insufficient pocket balance for payout",
  "batchId": null
}

8. Authenticator or PIN Required but Not Set Up

On a REQUIRED_TOTP or REQUIRED_PIN pocket, initiating a payout fails with SM_06 until the user has set up that factor.

MFA required. Please enroll in <factor> first.

9. Account Name Mismatch

The accountName you sent doesn’t match the bank name enquiry. A single payout fails at initiation; in a bulk payout, only the mismatched transfer fails, when it is processed.

{
  "code": "SM_06",
  "message": "Account name mismatch: provided 'Acme Corp Ltd' does not match bank enquiry '...'"
}

Prerequisites — Please read before integrating

Process Flow

Authenticate

Generate Signature

Initiate Payout

Confirm Payout

​Step 1 — Authenticate

​Request Sample

​Response Sample

​Step 2 — Generate X-Seerbit-Signature

​Signature Formula

​Variables Reference

​Step 3 — Initiate Payout

Required Headers

​Single Payout

​Request Sample

​Response Sample

Request Fields

​Bulk Payout

​Request Sample

​Response Sample

Request Fields

Each transfers object contains:

​Step 4 — Confirm Payout

Required Headers

​Request Sample

​Response Sample

Request Fields

​Bank List

​Request Sample

​Account Name Enquiry

​Request Sample

Request Fields

​Error Scenarios

1. Missing Signature Header

2. Invalid Signature

3. Missing Public Key Header

4. Invalid Code

5. Too Many Failed Attempts

6. Expired Email OTP

7. Insufficient Balance at Confirmation

8. Authenticator or PIN Required but Not Set Up

9. Account Name Mismatch

Step 1 — Authenticate

Request Sample

Response Sample

Step 2 — Generate X-Seerbit-Signature

Signature Formula

Variables Reference

Step 3 — Initiate Payout

Single Payout

Request Sample

Response Sample

Bulk Payout

Request Sample

Response Sample

Step 4 — Confirm Payout

Request Sample

Response Sample

Bank List

Request Sample

Account Name Enquiry

Request Sample

Error Scenarios