Webhooks

Interstellas sends real-time payment notifications to a URL you register. When a virtual account receives a payment, Interstellas POSTs a notification to your endpoint.

Registering your webhook URL

PATCH /clients/settings/update-webhook-url

Headers

string

required

Your public API key.

string

required

Your API secret. Use a stl_test_... value in sandbox, stl_live_... in production.

string

required

Your business ID.

Request body

string

required

The HTTPS URL that Interstellas will POST payment notifications to. Must be publicly accessible.

Response

boolean

true on success.

string

Confirmation message, e.g. "Webhook Url updated successfully".

Code example

curl -X PATCH https://sandbox.stellasbank.com/api/v1/clients/settings/update-webhook-url \
  -H "x-api-key: stl_c8e286ca55b0123e0b05da047494f585" \
  -H "x-api-secret: stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0" \
  -H "businessId: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourdomain.com/webhooks/interstellas"
  }'

const res = await fetch(
  "https://sandbox.stellasbank.com/api/v1/clients/settings/update-webhook-url",
  {
    method: "PATCH",
    headers: {
      "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
      "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
      businessId: "YOUR_BUSINESS_ID",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ webhookUrl: "https://yourdomain.com/webhooks/interstellas" }),
  }
);
const json = await res.json();

import requests

res = requests.patch(
    "https://sandbox.stellasbank.com/api/v1/clients/settings/update-webhook-url",
    headers={
        "x-api-key": "stl_c8e286ca55b0123e0b05da047494f585",
        "x-api-secret": "stl_test_6332e4b1dd6c2e5814395b549aec6deb0d0664406c66f2285f95f801c76117c0",
        "businessId": "YOUR_BUSINESS_ID",
    },
    json={"webhookUrl": "https://yourdomain.com/webhooks/interstellas"},
)
print(res.json())

Incoming payment notification

When a payment is received into one of your virtual accounts, Interstellas sends a POST request to your registered webhook URL.

Verifying the request

Incoming webhook requests include an AUTH-KEY header provided by Interstellas. Validate this header on your server to confirm the request originated from Interstellas and not a third party.

TODO — The source documentation does not specify the format of the AUTH-KEY value or how to validate it. Confirm this with the Interstellas team before going live.

Payload fields

string

The unique reference for this transaction, generated by Interstellas.

string

The reference for the virtual account that received the payment.

string

ISO 8601 timestamp of when the transaction occurred.

integer

Amount received, in kobo. Divide by 100 to convert to naira.

integer

Fee deducted from the payment, in kobo.

integer

Account balance available after the transaction, in kobo.

integer

Total ledger balance after the transaction, in kobo.

string

Name on the paying account.

string

The paying account number.

string

The virtual account number that received the payment.

string

The name on the receiving virtual account.

string

Transaction description.

string

Narration provided by the payer.

object

Additional details about the payer.

Example payload

{
  "transactionReference": "TXN_REF_ABC001",
  "virtualAccountRef": "VA_REF_XYZ789",
  "transactionDate": "2024-06-09T14:22:00.000Z",
  "amount": 500000,
  "charge": 10000,
  "availableBalance": 4500000,
  "ledgerBalance": 4500000,
  "accountName": "Grace Hopper",
  "accountNumber": "0123456789",
  "recipientAccountNumber": "9012345678",
  "recpientAccountName": "Ada Lovelace",
  "description": "Payment for order_12345",
  "narration": "Invoice #INV-001",
  "depositorDetails": {}
}

Required response

Your endpoint must return HTTP 200 OK to acknowledge receipt. If Interstellas does not receive a 200, it will retry the notification.

Node.js (Express)

app.post("/webhooks/interstellas", (req, res) => {
  const authKey = req.headers["auth-key"];
  // TODO: validate authKey against your expected value

  const payload = req.body;
  // Process the payment notification
  console.log("Payment received:", payload.transactionReference);

  res.status(200).send("OK");
});

Overview

Members

Business

Virtual accounts

Funds

Bulk transfers

Disputes

Subscriptions

Payouts

Audit logs

Settings

Registering your webhook URL

Headers

Request body

Response

Code example

Incoming payment notification

Verifying the request

Payload fields

Example payload

Required response

​Registering your webhook URL

​Headers

​Request body

​Response

​Code example

​Incoming payment notification

​Verifying the request

​Payload fields

​Example payload

​Required response

Registering your webhook URL

Headers

Request body

Response

Code example

Incoming payment notification

Verifying the request

Payload fields

Example payload

Required response