Skip to main content
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

​
Authorization
string
required
Bearer YOUR_ACCESS_TOKEN
​
SECRET_KEY
string
required
Your API secret key.
​
businessId
string
required
Your business ID.

​
Request body

​
webhookUrl
string
required
The HTTPS URL that Interstellas will POST payment notifications to. Must be publicly accessible.

​
Response

​
status
boolean
true on success.
​
message
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 "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "SECRET_KEY: YOUR_SECRET_KEY" \
  -H "businessId: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourdomain.com/webhooks/interstellas"
  }'

​
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

​
transactionReference
string
The unique reference for this transaction, generated by Interstellas.
​
virtualAccountRef
string
The reference for the virtual account that received the payment.
​
transactionDate
string
ISO 8601 timestamp of when the transaction occurred.
​
amount
integer
Amount received, in kobo. Divide by 100 to convert to naira.
​
charge
integer
Fee deducted from the payment, in kobo.
​
availableBalance
integer
Account balance available after the transaction, in kobo.
​
ledgerBalance
integer
Total ledger balance after the transaction, in kobo.
​
accountName
string
Name on the paying account.
​
accountNumber
string
The paying account number.
​
recipientAccountNumber
string
The virtual account number that received the payment.
​
recpientAccountName
string
The name on the receiving virtual account.
​
description
string
Transaction description.
​
narration
string
Narration provided by the payer.
​
depositorDetails
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");
});