Skip to main content
Shogun is a Banking-as-a-Service API that gives your backend direct access to virtual accounts, fund transfers, and real-time payment collections. This guide walks you through the four steps you need to make your first end-to-end payment flow work: get your credentials, generate an auth token, provision a customer account, and register a webhook.
1

Get your API credentials

After your business account is approved, navigate to Dashboard → Security → API Client to find your credentials.
CredentialDescription
client_idYour unique business identifier — safe to log
client_secretYour secret key for generating auth tokens
Never expose your client_secret in client-side code, environment files committed to version control, or any public repository.
2

Generate a bearer token

Exchange your credentials for a short-lived JWT. All API calls require this token in the Authorization header.
curl -X POST https://api.shogun.io/api/v1/security/api/generate_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'
A successful response returns a token and its expires_in value in seconds:
{
  "status": true,
  "response_code": "00",
  "message": "Token generated successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600
  }
}
Cache the token on your server and regenerate it before it expires. Tokens are valid for 1 hour.
Use the POST /api/v1/security/api/validate_token endpoint (with the token as a Bearer header) to check whether a cached token is still valid before making sensitive requests.
3

Create a customer account

Provision a permanent virtual account for one of your customers using their BVN or NIN. This account can receive payments indefinitely — no need to generate a new one for each transaction.
curl -X POST https://api.shogun.io/api/v1/account/api/create_customer_account \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "phone": "08012345678",
    "bvn": "12345678901",
    "account_name": "John Doe"
  }'
On success, Shogun returns the provisioned account details:
{
  "status": true,
  "response_code": "00",
  "message": "Customer account created successfully",
  "data": {
    "account_number": "8801234567",
    "account_name": "John Doe",
    "account_type": "virtual",
    "status": "active",
    "balance": "0.000000000"
  }
}
Your customer can now receive payments at account number 8801234567. Share this number with them as their dedicated payment address.
At least one of bvn or nin must be provided. Both values must be exactly 11 digits. If identity verification fails, you’ll receive response_code: "83" — see Errors for guidance.
4

Set up a webhook

Register a webhook URL so Shogun notifies your server in real time whenever a payment lands or a transfer completes.
curl -X POST https://api.shogun.io/api/v1/customer/api/create_webhook \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/shogun",
    "events": ["COLLECTION_SUCCESS", "TRANSFER_SUCCESS", "TRANSFER_FAILED"]
  }'
Shogun signs every webhook payload with an HMAC-SHA256 signature in the X-Shogun-Signature header. You must verify this signature before processing the event. See Authentication for verification code examples in Python and JavaScript.

​
Next steps

Authentication

Token lifecycle, credential management, and webhook signature verification

Errors

Response codes, HTTP status mapping, and retry logic

Transfers

Send funds to any bank account

Webhooks

Receive and process inbound payments