Welcome to the 9thSwift Payment Gateway API

The 9thSwift API provides a secure and reliable way to integrate payments, payouts, and bill payments into your applications.

All requests to the API must be authenticated and transmitted over HTTPS to ensure data integrity and security.

Base URL

Authentication

To interact with the API, you need to include the following headers in your requests:

Security Measures

Standard Checkout

The Transactions API allows you to create and manage payments on your integration.

{{url}}/transaction/init

Initialize a transaction from your backend.

Endpoint: /transaction/init

curl --location -g '{{url}}/transaction/init' \
--data-raw '{
  "reference": "MCD-12345667",
  "amount": 3000,
  "currency": "NGN",
  "callback_url": "https://www.google.com",
  "customer": {
    "payerName": "John Doe",
    "email": "[email protected]",
    "phoneNumber": "09088563125"
  }
}'

{
  "status": "success",
  "message": "Invoice created successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "checkout": "https://staging.9thswift.com/mepvwkmf-SW-ESHI",
      "accessCode": "mepvwkmf-SW-EGoHJylSWS",
      "reference": "MCD-12345667"
    }
  }
}

{{url}}/transaction/init-revenue-payment

This endpoint initializes a revenue payment transaction and creates an invoice for government revenue collection. Upon successful initialization, it returns a checkout URL where the payer can complete the payment.

curl --location -g '{{url}}/transaction/init-revenue-payment' \
--data-raw '{
  "reference": "GLOB-KLLK9XCFGRGA",
  "amount": 200,
  "currency": "NGN",
  "revenueCode": "ENUG60123",
  "taxPayerNumber": "2019873451",
  "callback_url": "https://www.google.com",
  "customer": {
    "payerName": "John Doe",
    "email": "[email protected]",
    "phoneNumber": "09088563125"
  }
}'

{
  "status": "success",
  "message": "Invoice created successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "checkout": "https://checkout.9thswift.com/MLNGP00V-SW-G-SHYPCJBW",
      "accessCode": "MLNGP00V-SW-G-SHYPCJBW",
      "reference": "GLOB-KLLK9XCFGRGA"
    }
  }
}

Usage Notes

1. 1.
   Unique References: Always generate a unique reference for each transaction to avoid conflicts.
2. 2.
   Amount Format: Verify the amount format with your implementation - confirm whether amounts are in kobo/cents or the base currency unit.
3. 3.
   Revenue Codes: Ensure you have the correct revenue code from the government authority before initiating transactions.
4. 4.
   Callback URL: The callback URL must be publicly accessible to receive payment status webhooks.
5. 5.
   Checkout Flow: After receiving the response, redirect the customer to the checkout URL to complete payment.
6. 6.
   Transaction Tracking: Store the accessCode and reference for transaction verification and reconciliation.

Best Practices

• •Validate all customer information before submitting the request
• •Implement proper error handling for failed initialization attempts
• •Use HTTPS for callback URLs to ensure secure webhook delivery
• •Log transaction references for audit trails and customer support
• •Consider implementing idempotency checks using the reference field

{{url}}/transaction/verify/:reference

The Transactions API allows you to verify payments on your integration.

Endpoint: /transaction/verify/:reference

Method: GET

curl --location -g '{{url}}/transaction/verify/MCD-00345667'

{
  "status": "success",
  "message": "Invoice verified successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "reference": "MCD-00345667",
      "status": "success",
      "amount": 307.5,
      "settledAmount": 300,
      "feeCharged": 7.5,
      "currency": "NGN",
      "channel": "card",
      "customerEmail": "[email protected]"
    }
  }
}

{{url}}/transaction/add-payout-recipient

The API allows you to create recipient for payout.

Endpoint: /transaction/add-payout-recipient

Method: POST

curl --location -g '{{url}}/transaction/add-payout-recipient' \
--data '{
  "type": "nuban",
  "name": "Oloyede Chizorom",
  "accountNumber": "8104656733",
  "bankCode": "305",
  "bankName": "PAYCOM (OPAY)",
  "currency": "NGN"
}'

{
  "status": "success",
  "message": "Invoice created successfully",
  "data": {
    "statusCode": "00",
    "data": {
      "recipientCode": "SW-JTEQBHESCV-RECIPIENT"
    }
  }
}

{{url}}/transaction/init-payout

The API allows you to create recipient for payout.

Endpoint: /transaction/add-payout-recipient

Method: POST

curl --location -g '{{url}}/transaction/init-payout' \
--data '{
  "source": "wallet",
  "recipientCode": "SW-JTEQBHESCV-RECIPIENT",
  "reason": "Vendor 2 withdwal",
  "amount": 500,
  "reference": "UIOUV-980L980",
  "currency": "NGN"
}'

{
  "status": "success",
  "message": "Transfer successfully logged and Processing",
  "data": {
    "statusCode": "00"
  }
}

{{url}}/config/bank-list

curl --location -g '{{url}}/config/bank-list'

{
  "status": "success",
  "message": "Bank list retrieved",
  "data": {
    "statusCode": "00",
    "currency": "NGN",
    "banks": [
      {
        "bankName": "7B FINANCE COMPANY LIMITED",
        "bankCode": "110072",
        "logoUrl": "https://cdn.buildwithcedar.com/356/3830/283b1ss.png"
      }
    ]
  }
}

{{url}}/config/account-name-verify

This endpoint allows you to verify account name and number for bank accounts.

your-web-hook-url

const apiKey = process.env.SECRET_KEY;
app.post('/my/webhook/url', function(req, res) {
  //validate event
  const signature = req.header('ApiKey').replace('ApiKey ', '');
  if (!signature || (signature !== apiKey)) {
    throw new Error('Webhook notification not from 9th Swift');
  }
  
  // Retrieve the request's body
  const event = req.body;
  // Do something with event
});

curl --location 'your-web-hook-url' \
--data-raw '{
  "id": "67ec7641416a8374c865a167",
  "type": "payment.success",
  "created": "2025-09-03T10:40:18.742+00:00",
  "data": {
    "reference": "MFNRCBW0-SW-AFHJTTSA-M",
    "status": "success",
    "amount": 1025,
    "settledAmount": 1000,
    "chargedFee": 25
  }
}'

{
  "id": "67ec7641416a8374c865a167",
  "type": "payment.success",
  "created": "2025-09-03T10:40:18.742+00:00",
  "data": {
    "reference": "MFNRCBW0-SW-AFHJTTSA-M",
    "status": "success",
    "amount": 1025,
    "settledAmount": 1000,
    "chargedFee": 25
  }
}

EventType

Here are some points to take notes

1. 1.Add the webhook URL on your 9thSwift dashboard
2. 2.Ensure your webhook URL is publicly available (localhost URLs cannot receive events)
3. 3.Test your webhook to ensure you're getting the JSON body and returning a 200 OK HTTP response
4. 4.If your webhook function has long-running tasks, you should first acknowledge receiving the webhook by returning a 200 OK before proceeding with the long-running tasks
5. 5.If we don't get a 200 OK HTTP response from your webhooks, we flagged it as a failed attempt
6. 6.If we are unable to deliver webhook to you, there is an api to re call failed webhook notification.

{{url}}/wallet/wallet-balance

curl --location -g '{{url}}/wallet/wallet-balance'

{
  "status": "success",
  "message": "Wallet balance retrieved successfully",
  "data": {
    "statusCode": "00"
  }
}

Payment Status

Payment Channel

Payment Currency