REST API · v2.4.0 · Live

API Reference

Everything your team needs to integrate, test & ship.

Base URL https://securepay-staging-api.getsecurepay.ai

Format application/json

Auth APIKEY

Rate Limit 1000 req / min

🔗

Base Url

securepay-staging-api.getsecurepay.ai

🔒

TLS Required

HTTPS only · TLS 1.2+

⚡

SLA Uptime

99.95% · Avg 45ms

📦

Pagination

cursor-based

Authentication

All API requests must be authenticated. The SecurePay API supports only API Key authentication. Include the appropriate credentials in the request headers on every request.

API Key

Pass your public API key in the x-api-key request header. Your API key can be found in the Developer Console under Settings → API Keys. Keep your key secure and never expose it in client-side code.

HTTP Header

X-Api-Key: YOUR_API_KEY_HERE
Content-Type:  application/json
X-Request-ID:  uuid-v4-trace-id

cURL Example

curl -X POST https://securepay-staging-api.getsecurepay.ai/api/Transfer/initiate/v2 \
  -H "accept: application/json" \
  -H "Content-Type: application/json"

Key Management

Generate and manage API keys for authenticating requests to the SecurePay platform.

GET /api/KeyManager/generateKey Generate a public API key for a merchant

Parameters

Request

Response

Field	Type	Required	Description
merchantEmail	string	required	The email address of the merchant account for which the API key will be generated. Passed as a query parameter.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/KeyManager/generateKey?merchantEmail=maxstor%40yopmail.com

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/KeyManager/generateKey?merchantEmail=maxstor%40yopmail.com' \
  -H 'accept: application/json'

200 OK — JSON

{
  "success": true,
  "statusCode": "OK",
  "message": "Key generated successfully",
  "data": {
    "publicKeyEncrypted": "SP-PK-CU8T20GnkWmlshwSMDbREGOuwXGOcMAvKuRb2th1gsjAGvrT"
  }
}

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: application/json; charset=utf-8
date: Fri, 13 Mar 2026 13:34:27 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200 Success — Example Schema

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Key generated successfully. Returns the encrypted public key for the merchant

400

Bad Request — Missing or invalid merchantEmail query parameter

404

Not Found — No merchant account found for the provided email address

500

Server Error — Internal server error

Transfer

Initiate and manage secure payment transfers between accounts.

POST /api/Transfer/initiate/v2 Initiate a new payment transfer

Body

Request

Response

Field	Type	Required	Description
amount	number	required	Transfer amount (minimum 0)
invoiceId	string	required	Unique invoice identifier (UUID format)

JSON Body

{
  "amount": 0,
  "invoiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/Transfer/initiate/v2' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 0,
  "invoiceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Request processed successfully

400

Bad Request — Invalid request parameters or insufficient funds

401

Unauthorized — Missing or invalid API key

500

Server Error — Internal server error

POST /api/Transfer/payment-link Create a payment link for transactions

Body

Request

Response

Field	Type	Required	Description
description	string	required	Description of the payment link
amount	number	required	Payment amount (minimum 0)
customerDetail	object	required	Customer information details
customerDetail.emailAddress	string	required	Customer's email address
customerDetail.phoneNumber	string	required	Customer's phone number
redirectUrl	string	required	URL to redirect after payment completion
transactionRef	string	required	Unique transaction reference identifier
subAccountSplits	array	optional	Array of sub-account split configurations
subAccountSplits[].settlementConfigId	string	required	Settlement configuration ID (UUID format)
subAccountSplits[].transactionSplitRatio	number	required	Split ratio for the transaction

JSON Body

{
  "description": "string",
  "amount": 0,
  "customerDetail": {
    "emailAddress": "string",
    "phoneNumber": "string"
  },
  "redirectUrl": "string",
  "transactionRef": "string",
  "subAccountSplits": [
    {
      "settlementConfigId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transactionSplitRatio": 0
    }
  ]
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/Transfer/payment-link' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "string",
  "amount": 0,
  "customerDetail": {
    "emailAddress": "string",
    "phoneNumber": "string"
  },
  "redirectUrl": "string",
  "transactionRef": "string",
  "subAccountSplits": [
    {
      "settlementConfigId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transactionSplitRatio": 0
    }
  ]
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Payment link created successfully

400

Bad Request — Invalid request parameters or missing public key

500

Server Error — Internal server error

POST /api/Transfer/test?transactionId={transactionId}&invoiceId={invoiceId} Simulate transaction status

Parameters

Request

Response

Parameter	Type	Required	Description
transactionId	string	required	Unique transaction identifier (UUID format)
invoiceId	string	required	Unique invoice identifier (UUID format)

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/Transfer/test?transactionId=6d6c4c3a-8f4c-4f6e-bb74-8c59c0f3e0b1&invoiceId=a41d2c7f-6e7b-4f5a-bb9e-1c6d93f1d8a2' \
  -H 'accept: application/json' \
  -d ''

200 OK — JSON

{
  "success": false,
  "statusCode": "BadRequest",
  "message": "not found",
  "data": null
}

200

Success — Transaction test completed. Returns status and details

400

Bad Request — Invalid transaction or invoice ID

500

Server Error — Internal server error

GET /api/Transfer/requery?transactionRef={transactionRef} Requery transaction status by reference

Parameters

Request

Response

Parameter	Type	Required	Description
transactionRef	string	required	Unique transaction reference identifier. Passed as a query parameter.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/Transfer/requery?transactionRef={transactionRef}

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/Transfer/requery?transactionRef={transactionRef}' \
  -H 'accept: application/json'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Transaction status retrieved successfully. Returns current transaction details and status

400

Bad Request — Invalid or missing transaction reference

404

Not Found — No transaction found for the provided reference

500

Server Error — Internal server error

POST /api/Transfer/webhook Configure webhook URL for transaction notifications

Body

Request

Response

Field	Type	Required	Description
webhookUrl	string	required	URL endpoint to receive transaction webhook notifications

JSON Body

{
  "webhookUrl": "string"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/Transfer/webhook' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "webhookUrl": "string"
}'

200 OK — JSON

{
  "success": false,
  "statusCode": "NotFound",
  "message": "Merchant not found",
  "data": null
}

200

Success — Webhook configuration processed. Returns status and details

400

Bad Request — Invalid webhook URL or malformed request

404

Not Found — Merchant not found or not authorized

500

Server Error — Internal server error

Direct Debit

Endpoints for managing Direct Debit billers and mandates on the SecurePay platform.

POST /api/DirectDebit/createBiller Register a new NIBSS Direct Debit biller

Body

Request

Response

Field	Type	Required	Description
rcNumber	string	required	RC (Registration Certificate) number of the biller's business
name	string	required	Legal business name of the biller
address	string	required	Registered address of the biller
email	string	required	Contact email address of the biller
phoneNumber	string	required	Contact phone number of the biller
accountNumber	string	required	Settlement bank account number for the biller
accountName	string	required	Name on the settlement bank account
bankCode	string	required	CBN bank code for the biller's settlement bank
mandateStatusNotificationUrl	string	required	Webhook URL to receive mandate status change notifications
merchantId	uuid	required	Unique identifier (UUID) of the SecurePay merchant account

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/createBiller

JSON Body

{
  "rcNumber": "string",
  "name": "string",
  "address": "string",
  "email": "string",
  "phoneNumber": "string",
  "accountNumber": "string",
  "accountName": "string",
  "bankCode": "string",
  "mandateStatusNotificationUrl": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/createBiller' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "rcNumber": "string",
  "name": "string",
  "address": "string",
  "email": "string",
  "phoneNumber": "string",
  "accountNumber": "string",
  "accountName": "string",
  "bankCode": "string",
  "mandateStatusNotificationUrl": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

access-control-allow-origin: *
api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 14:33:51 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

500 Server Error — Example Schema

{
  "success": false,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Biller created successfully. Returns status and biller details

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

POST /api/DirectDebit/createProduct Create a product under an existing NIBSS Direct Debit biller

Body

Request

Response

Field	Type	Required	Description
billerId	string	required	Unique identifier of the biller to associate this product with
productName	string	required	Name of the direct debit product being created
merchantId	uuid	required	Unique identifier (UUID) of the SecurePay merchant account

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/createProduct

JSON Body

{
  "billerId": "string",
  "productName": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/createProduct' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "billerId": "string",
  "productName": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

access-control-allow-origin: *
api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 15:13:05 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

400 Bad Request — Example Schema

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

500 Server Error — Example Schema

{
  "success": false,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Product created successfully. Returns status and product details

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

GET /api/DirectDebit/nipBanks Retrieve a list of all supported NIP banks

Parameters

Request

Response

This endpoint takes no parameters. Authentication via APIKey is required.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/nipBanks

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/nipBanks' \
  -H 'accept: text/plain'

200 OK — Server Response (JSON)

[
  {
    "bankCode": "044",
    "bankName": "Access-Diamond Bank",
    "nipCode": "000014",
    "id": "4b678d0c-fcef-4e44-9adb-7036b07da1b5",
    "dateCreated": "2026-02-06T09:55:07.072086",
    "dateModified": "2026-02-06T09:55:07.072079"
  },
  {
    "bankCode": "023",
    "bankName": "Citi Bank",
    "nipCode": "000009",
    "id": "745e29ad-69df-4fa0-8b39-e4e535f9697f",
    "dateCreated": "2026-02-06T09:55:07.0721",
    "dateModified": "2026-02-06T09:55:07.072095"
  },
  {
    "bankCode": "058",
    "bankName": "Guaranty Trust Bank",
    "nipCode": "000013",
    "id": "31f47480-a1c7-4c45-a56d-4d2105cf1df2",
    "dateCreated": "2026-02-06T09:55:07.072152",
    "dateModified": "2026-02-06T09:55:07.072148"
  },
  // ... 33 more banks
]

200 Success — Example Schema

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 15:16:55 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

500 Server Error — Example Schema

{
  "success": false,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

All 36 Banks Returned

Bank Name	Bank Code	NIP Code
Access-Diamond Bank	044	000014
Citi Bank	023	000009
Coronation Merchant Bank	559	060001
EcoBank	050	000010
FBN Merchant Bank	911	060002
FBNQuest Merchant Bank	560	060002
Fidelity Bank	070	000007
First Bank of Nigeria	011	000016
First City Monument Bank	214	000003
FSDH	501	400001
Globus Bank	103	000027
Greenwich Bank	562	060004
Guaranty Trust Bank	058	000013
Heritage Bank	030	000020
Jaiz Bank	301	000006
Keystone Bank	082	000002
Lotus Bank	303	000029
Nova Merchant Bank	561	060003
Optimus Bank	107	000036
Parallex Bank	104	000030
Polaris Bank	076	000008
Premium Trust Bank	105	000031
Providus Bank	101	000023
Rand Merchant Bank	502	000024
Signature Bank	106	000034
Stanbic IBTC	221	000012
Standard Chartered Bank	068	000021
Sterling Bank	232	000001
Suntrust Bank	100	000022
TAJ Bank	302	000026
Titan Trust Bank	102	000025
Union Bank	032	000018
United Bank of Africa	033	000004
Unity Bank	215	000011
Wema Bank	035	000017
Zenith Bank	057	000015

200

Success — Returns an array of all supported NIP banks with bank codes and NIP codes

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

POST /api/DirectDebit/create-e-mandate Create an electronic mandate for NIBSS Direct Debit

Body

Request

Response

Field	Type	Required	Description
productId	integer	required	Numeric ID of the direct debit product to attach the mandate to
billerId	string	required	Unique identifier of the registered NIBSS biller
accountNumber	string	required	Payer's bank account number to be debited
bankCode	string	required	CBN bank code for the payer's bank (see Get NIP Banks)
payerName	string	required	Full name of the account holder authorising the mandate
payerAddress	string	required	Residential or business address of the payer
accountName	string	required	Name on the bank account to be debited
amount	number	required	Amount to be debited per mandate cycle (in Naira)
narration	string	required	Brief description or reference for the mandate debit
phoneNumber	string	required	Payer's contact phone number
subscriberCode	string	required	Unique code identifying the subscriber within the biller's system
startDate	string (ISO 8601)	required	Mandate activation date and time in ISO 8601 format
endDate	string (ISO 8601)	required	Mandate expiry date and time in ISO 8601 format
payerEmail	string	required	Payer's email address for mandate notifications
merchantId	uuid	required	Unique identifier (UUID) of the SecurePay merchant account

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/create-e-mandate

JSON Body

{
  "productId": 0,
  "billerId": "string",
  "accountNumber": "string",
  "bankCode": "string",
  "payerName": "string",
  "payerAddress": "string",
  "accountName": "string",
  "amount": 0,
  "narration": "string",
  "phoneNumber": "string",
  "subscriberCode": "string",
  "startDate": "2026-03-12T14:31:59.523Z",
  "endDate": "2026-03-12T14:31:59.523Z",
  "payerEmail": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/create-e-mandate' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": 0,
  "billerId": "string",
  "accountNumber": "string",
  "bankCode": "string",
  "payerName": "string",
  "payerAddress": "string",
  "accountName": "string",
  "amount": 0,
  "narration": "string",
  "phoneNumber": "string",
  "subscriberCode": "string",
  "startDate": "2026-03-12T14:31:59.523Z",
  "endDate": "2026-03-12T14:31:59.523Z",
  "payerEmail": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

access-control-allow-origin: *
api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 14:32:05 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — E-mandate created successfully. Returns mandate status and details

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

GET /api/DirectDebit/mandate-status/{mandateCode} Get the status of an electronic mandate for NIBSS Direct Debit

Parameters

Request

Response

Field	Type	Required	Description
mandateCode	string	required	Mandate code identifier encoded in the URL path

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/mandate-status/4561639%2F20379%2F2169113565

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/NibssDirectDebit/mandate-status/4561639%2F20379%2F2169113565' \
  -H 'accept: text/plain'

200 OK — JSON

{
  "success": true,
  "statusCode": "200",
  "message": "Success",
  "data": {
    "mandateCode": "4561639/20379/2169113565",
    "accountName": "ADENIYI CHINEDU MUSA",
    "accountNumber": "3001248102",
    "mandateStatus": "Active",
    "workflowStatus": "Biller Initiated",
    "rejectionReason": null,
    "rejectionComment": null,
    "mandateAdviceStatus": "Advise not sent",
    "mandateAdviceSent": 0
  }
}

200

Success — Returns the current mandate status and workflow details

400

Bad Request — Invalid or missing mandate code in the request URL

500

Server Error — Internal server error

POST /api/DirectDebit/create-e-mandate/v2 Create an electronic mandate for NIBSS Direct Debit

Body

Request

Response

Field	Type	Required	Description
productId	integer	required	Numeric ID of the direct debit product to attach the mandate to
billerId	string	required	Unique identifier of the registered NIBSS biller
accountNumber	string	required	Payer's bank account number to be debited
bankCode	string	required	CBN bank code for the payer's bank (see Get NIP Banks)
payerName	string	required	Full name of the account holder authorising the mandate
payerAddress	string	required	Residential or business address of the payer
accountName	string	required	Name on the bank account to be debited
amount	number	required	Amount to be debited per mandate cycle (in Naira)
narration	string	required	Brief description or reference for the mandate debit
phoneNumber	string	required	Payer's contact phone number
subscriberCode	string	required	Unique code identifying the subscriber within the biller's system
startDate	string (ISO 8601)	required	Mandate activation date and time in ISO 8601 format
endDate	string (ISO 8601)	required	Mandate expiry date and time in ISO 8601 format
payerEmail	string	required	Payer's email address for mandate notifications
merchantId	uuid	required	Unique identifier (UUID) of the SecurePay merchant account

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/create-e-mandate/v2

JSON Body

{
  "productId": 0,
  "billerId": "string",
  "accountNumber": "string",
  "bankCode": "string",
  "payerName": "string",
  "payerAddress": "string",
  "accountName": "string",
  "amount": 0,
  "narration": "string",
  "phoneNumber": "string",
  "subscriberCode": "string",
  "startDate": "2026-03-12T14:31:59.523Z",
  "endDate": "2026-03-12T14:31:59.523Z",
  "payerEmail": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/create-e-mandate/v2' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "productId": 0,
  "billerId": "string",
  "accountNumber": "string",
  "bankCode": "string",
  "payerName": "string",
  "payerAddress": "string",
  "accountName": "string",
  "amount": 0,
  "narration": "string",
  "phoneNumber": "string",
  "subscriberCode": "string",
  "startDate": "2026-03-12T14:31:59.523Z",
  "endDate": "2026-03-12T14:31:59.523Z",
  "payerEmail": "string",
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

access-control-allow-origin: *
api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 14:32:05 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — E-mandate created successfully. Returns mandate status and details

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

POST /api/DirectDebit/name-inquiry Look up the account name for a given account number and bank

Body

Request

Response

Field	Type	Required	Description
accountNumber	string	required	The account number to look up
channelCode	integer	required	Numeric code identifying the channel through which the inquiry is initiated
destinationInstitutionCode	string	required	NIP or bank code of the destination institution (see Get NIP Banks)
transactionId	string	required	Unique transaction reference ID for tracking the inquiry request

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/name-inquiry

JSON Body

{
  "accountNumber": "string",
  "channelCode": 0,
  "destinationInstitutionCode": "string",
  "transactionId": "string"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/name-inquiry' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "accountNumber": "string",
  "channelCode": 0,
  "destinationInstitutionCode": "string",
  "transactionId": "string"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

access-control-allow-origin: *
api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 16:19:04 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

500 Server Error — Example Schema

{
  "success": false,
  "statusCode": "string",
  "message": "string",
  "data": "string"
}

200

Success — Account name resolved successfully. Returns account holder details

400

Bad Request — Public key is missing or invalid. Ensure your API public key is included in the request headers

500

Server Error — Internal server error

GET /api/DirectDebit/get-financial-institution Retrieve a list of financial institutions

Parameters

Request

Response

This endpoint takes no parameters. Authentication via public key is required.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/get-financial-institution

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/get-financial-institution' \
  -H 'accept: text/plain' \
  -H 'public-Key: SP-PK-cpdPpGkhFUqndiPKuWvxA2Lw3UTiyGpCz4MpQH0m005jDDM3'

200 OK — JSON

{
  "success": true,
  "statusCode": "OK",
  "message": "Financial institutions retrieved successfully",
  "data": [
    {
      "id": "string",
      "name": "string",
      "code": "string"
    }
  ]
}

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: application/json; charset=utf-8
date: Thu, 12 Mar 2026 16:19:04 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — Returns a list of financial institutions

400

Bad Request — Public key is missing or invalid

500

Server Error — Internal server error

POST /api/DirectDebit/fund-transfer Initiate a fund transfer via Direct Debit

Body

Request

Response

Field	Type	Required	Description
sourceInstitutionCode	string	required	The code of the source financial institution
amount	number	required	The amount to transfer
beneficiaryAccountName	string	required	The name of the beneficiary account holder
beneficiaryAccountNumber	string	required	The beneficiary account number
beneficiaryBankVerificationNumber	string	required	The beneficiary's bank verification number
beneficiaryKYCLevel	integer	required	The KYC level of the beneficiary
channelCode	integer	required	The channel code for the transfer
originatorAccountName	string	required	The name of the originator account holder
originatorAccountNumber	string	required	The originator account number
originatorBankVerificationNumber	string	required	The originator's bank verification number
originatorKYCLevel	integer	required	The KYC level of the originator
destinationInstitutionCode	string	required	The code of the destination financial institution
mandateReferenceNumber	string	required	The reference number of the mandate
nameEnquiryRef	string	required	The reference from the name enquiry
originatorNarration	string	required	Narration for the originator
paymentReference	string	required	The payment reference
transactionId	string	required	Unique transaction ID
transactionLocation	string	required	The location of the transaction
beneficiaryNarration	string	required	Narration for the beneficiary
billerId	string	required	The ID of the biller
initiatorAccountNumber	string	required	The account number of the initiator
initiatorAccountName	string	required	The name of the initiator account holder

Request URL

https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/fund-transfer

JSON Body

{
  "sourceInstitutionCode": "string",
  "amount": 0,
  "beneficiaryAccountName": "string",
  "beneficiaryAccountNumber": "string",
  "beneficiaryBankVerificationNumber": "string",
  "beneficiaryKYCLevel": 0,
  "channelCode": 0,
  "originatorAccountName": "string",
  "originatorAccountNumber": "string",
  "originatorBankVerificationNumber": "string",
  "originatorKYCLevel": 0,
  "destinationInstitutionCode": "string",
  "mandateReferenceNumber": "string",
  "nameEnquiryRef": "string",
  "originatorNarration": "string",
  "paymentReference": "string",
  "transactionId": "string",
  "transactionLocation": "string",
  "beneficiaryNarration": "string",
  "billerId": "string",
  "initiatorAccountNumber": "string",
  "initiatorAccountName": "string"
}

cURL

curl -X 'POST' \
  'https://securepay-staging-api.getsecurepay.ai/api/DirectDebit/fund-transfer' \
  -H 'accept: text/plain' \
  -H 'public-Key: SP-PK-cpdPpGkhFUqndiPKuWvxA2Lw3UTiyGpCz4MpQH0m005jDDM3' \
  -H 'Content-Type: application/json' \
  -d '{
  "sourceInstitutionCode": "string",
  "amount": 0,
  "beneficiaryAccountName": "string",
  "beneficiaryAccountNumber": "string",
  "beneficiaryBankVerificationNumber": "string",
  "beneficiaryKYCLevel": 0,
  "channelCode": 0,
  "originatorAccountName": "string",
  "originatorAccountNumber": "string",
  "originatorBankVerificationNumber": "string",
  "originatorKYCLevel": 0,
  "destinationInstitutionCode": "string",
  "mandateReferenceNumber": "string",
  "nameEnquiryRef": "string",
  "originatorNarration": "string",
  "paymentReference": "string",
  "transactionId": "string",
  "transactionLocation": "string",
  "beneficiaryNarration": "string",
  "billerId": "string",
  "initiatorAccountNumber": "string",
  "initiatorAccountName": "string"
}'

200 OK — JSON

{
  "success": true,
  "statusCode": "OK",
  "message": "Fund transfer initiated successfully",
  "data": "string"
}

400 Bad Request — Server Response

Public key is required.

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: text/plain; charset=utf-8
date: Thu, 12 Mar 2026 16:19:04 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — Fund transfer initiated successfully

400

Bad Request — Public key is missing or invalid, or invalid request body

500

Server Error — Internal server error

Checkout

Endpoints for managing checkout sessions and retrieving available payment channels for a given invoice.

GET /api/checkout/{invoiceId}/available-channels Retrieve available payment channels for a checkout invoice

Parameters

Request

Response

Field	Type	Required	Description
invoiceId	string (uuid)	required	The unique invoice ID (UUID) of the checkout session. Passed as a path parameter.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/available-channels

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/available-channels' \
  -H 'accept: */*'

200 OK — JSON

{
  "success": true,
  "statusCode": "OK",
  "message": "Available payment channels retrieved successfully",
  "data": {
    "defaultChannel": 0,
    "channels": [
      {
        "channel": 0,
        "isDisabled": false,
        "reason": null,
        "maxLimit": 9000000
      }
    ]
  }
}

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: application/json; charset=utf-8
date: Fri, 13 Mar 2026 13:43:00 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — Returns the default channel and a list of available payment channels with limits and status

404

Not Found — No checkout session found for the provided invoiceId

500

Server Error — Internal server error

GET /api/checkout/{invoiceId}/channel/{channel}/breakdown Get fee and price breakdown for a specific payment channel

Parameters

Request

Response

Field	Type	Required	Description
invoiceId	string (uuid)	required	The unique invoice ID (UUID) of the checkout session. Passed as a path parameter.
channel	integer	required	The channel code for which to retrieve the fee breakdown. Passed as a path parameter (e.g. `0`).

Request URL

https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/channel/0/breakdown

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/channel/0/breakdown' \
  -H 'accept: */*'

200 OK — JSON

{
  "channel": 0,
  "showFeeBreakdown": false,
  "basePrice": 0,
  "channelFee": 0,
  "channelFeeExpression": null,
  "vatOnFee": 0,
  "vatAmount": 0,
  "vatExpression": null,
  "vatApplicable": false,
  "subtotal": 0,
  "totalPayable": 0
}

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: application/json; charset=utf-8
date: Fri, 13 Mar 2026 13:45:12 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — Returns a full fee and price breakdown for the specified channel including base price, channel fee, VAT, and total payable

404

Not Found — No checkout session found for the provided invoiceId, or the specified channel does not exist

500

Server Error — Internal server error

GET /api/checkout/{invoiceId}/preview Generate a full pricing preview for a checkout session

Parameters

Request

Response

Field	Type	Required	Description
invoiceId	string (uuid)	required	The unique invoice ID (UUID) of the checkout session. Passed as a path parameter.

Request URL

https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/preview

cURL

curl -X 'GET' \
  'https://securepay-staging-api.getsecurepay.ai/api/checkout/db5a8d4a-d7ce-4543-8921-7edc3bd48213/preview' \
  -H 'accept: */*'

200 OK — JSON

{
  "success": true,
  "statusCode": "OK",
  "message": "Checkout preview generated successfully",
  "data": {
    "invoiceNo": "SP_IVC_134157_f856fd",
    "subtotal": 200,
    "discount": 0,
    "discountedAmount": 200,
    "vatAmount": 13.95,
    "processingFee": 11,
    "totalPayable": 200,
    "customerBearsFee": false,
    "isVatInclusive": true,
    "vatLabel": "VAT (Inclusive)"
  }
}

Response Headers

api-supported-versions: 1.0
cache-control: no-store
content-security-policy: unsafe-inline 'self'
content-type: application/json; charset=utf-8
date: Fri, 13 Mar 2026 13:46:54 GMT
feature-policy: accelerometer 'none'; camera 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'
pragma: no-cache
referrer-policy: no-referrer-when-downgrade
strict-transport-security: max-age=31536000; includeSubDomains
x-content-type-options: nosniff
x-frame-options: DENY
x-permitted-cross-domain-policies: none

200

Success — Returns a full pricing preview including subtotal, discount, VAT amount, processing fee, and total payable for the checkout session

404

Not Found — No checkout session found for the provided invoiceId

500

Server Error — Internal server error

Error Handling

All errors follow a consistent schema with a machine-readable code and a human-readable message.

Error Schema

{
  "success": false,
  "statusCode": "BadRequest",
  "message": "The request body is invalid.",
  "data": null
}

400

Bad Request — Invalid input parameters or malformed request

401

Unauthorized — Token missing, expired, or revoked

403

Forbidden — Your role doesn't have permission for this action

404

Not Found — The requested resource does not exist

429

Too Many Requests — Rate limit exceeded. Retry after Retry-After seconds

500

Internal Server Error — Something went wrong on our end. Include request_id when contacting support

Changelog

Document history and approval record for the SecurePay API reference.

Document Record

Role	Name	Title	Date
Prepared by	Oluwapelumi Anibi	QA Engineer	12 Mar 2026
Approved by	Opeyemi Ajayi	Head of Engineering	12 Mar 2026