Give your customers Business Steward. See their real numbers.
Invite your business customers from your own systems. Each owner approves on their own screen; from then on you can read that business's financial health, cash outlook and loan readiness — worked out from records the owner keeps every day.
Version 1 · REST and JSON · test mode with sample businesses · signed webhooks
What you can do
Business Steward is where a small business keeps its books: every sale, expense, credit and stock movement, recorded in the app or by WhatsApp message. From those records it works out a health score, a 30-day cash outlook and a loan readiness estimate. The Partner API lets an institution bring its customers onto Business Steward and, with their permission, use those figures in its own lending and relationship work.
- Onboard customers
Send an invitation from your core banking system, CRM or loan-origination tool. The customer signs up or signs in, and approves.
- Assess loan readiness
Eligibility, a score out of 100 and the loan amount the records support — with the monthly averages behind every figure.
- Watch financial health
Cash position, this month against last, a health score in five parts, and a 30-day cash outlook.
- Pay for their access
Optionally cover the subscription of every business connected to you, so your customers use Business Steward at no cost to them.
Three rules shape everything below. You never see a business that has not approved you. You see only the kinds of record the owner approved. Either side can end the connection at any moment, and access stops at once.
How it works
- You invite a customer
Call POST /customers with your own customer number and the kinds of record you are asking for. You get back a link and an 8-character code.
- You send them the link
By SMS, WhatsApp, email or in your own app. If they are new to Business Steward they create a free account first; the invitation waits for them.
- The owner approves on their own screen
They see your institution's name and, in plain words, exactly what you will be able to see. They press Approve or Decline.
- You are told
A signed webhook arrives (customer.approved), or you ask with GET /customers/{id}. The status is now active.
- You read their records
Summary, loan assessment, cash outlook, monthly report or individual entries — whichever scopes were approved — for as long as the connection lasts.
Getting access
Partner accounts are opened by Business Steward, not self-service. Write to us with your institution's name, what you plan to build and a technical contact. You receive a test key first, and a live key once your integration has been checked against the go-live list.
- bsp_test_…test key
Works on sample businesses only. Never touches a real customer. Use it to build and to run your automated tests.
- bsp_live_…live key
Works on real customers, each of whom must approve. Keep it on your servers; never put it in a mobile app or a web page.
A key is shown once, when it is made; we store only a fingerprint of it. If one is exposed, tell us and it is switched off and replaced. You may hold several keys at once, so a key can be rotated without downtime.
Authentication
Send the key in the Authorization header of every request, over HTTPS. The base address is the same for test and live — the key decides which.
Base address https://business-stewards.com/api/partner/v1 Header Authorization: Bearer bsp_test_your_key_here
curl https://business-stewards.com/api/partner/v1/me \ -H "Authorization: Bearer bsp_test_your_key_here"
{
"object": "partner",
"id": "5b1f6f0e-2c8e-4d6a-9d3e-0a4c1f2b7e90",
"name": "Unity Microfinance Bank",
"kind": "mfb",
"mode": "test",
"covers_subscription": true,
"webhook_configured": true,
"rate_limit_per_minute": 300
}Every response carries an X-Steward-Mode header (test or live), so your logs always show which world a call ran in. Requests and responses are JSON, in UTF-8. Dates are ISO 8601 in UTC. Amounts are plain numbers in the business's own currency, named in currency.
Test mode
With a test key, every customer you invite is a sample business. There are four, one for each answer you will meet in production. Choose one with the sample field when you invite; leave it out and one is picked from your customer number (the same number always gets the same sample).
- strongsample
Amara Fashion House, Lagos. Six months of steady records. Likely to qualify.
- borderlinesample
Tunde Provisions Store, Ibadan. Four months of records, thin margins and an overdue supplier bill. Borderline.
- weaksample
Kemi Beauty Supplies, Abuja. Five months of records, spending more than it takes in. Not ready.
- newsample
Ngozi Foods, Enugu. Six weeks of records. Still building a track record.
No real person answers a test invitation, so you stand in for the owner with POST /customers/{id}/simulate and an action of approve, decline or revoke. Webhooks fire exactly as they do live, with "mode": "test". Sample figures are made up, always end today, and are the same every time you ask on the same day.
Quick start
1. Invite a customer. external_ref is your own customer number; it is how you find them again.
curl -X POST https://business-stewards.com/api/partner/v1/customers \
-H "Authorization: Bearer bsp_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "external_ref": "CUST-004512", "business_name": "Amara Fashion House",
"owner_name": "Amara Okafor", "phone": "+2348012345678",
"scopes": ["summary", "loan"], "sample": "strong" }'HTTP/1.1 201 Created
{
"id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
"object": "customer",
"mode": "test",
"external_ref": "CUST-004512",
"status": "pending",
"scopes": ["summary", "loan"],
"business": null,
"invited": { "business_name": "Amara Fashion House", "owner_name": "Amara Okafor", "phone": "+2348012345678", "email": null },
"invite_code": "K7QM2XPD",
"invite_url": "https://business-stewards.com/link/K7QM2XPD",
"subscription_covered": false,
"created_at": "2026-11-16T09:12:44.118Z",
"expires_at": "2026-12-16T09:12:44.118Z",
"decided_at": null, "ended_at": null, "ended_by": null
}2. Approve it (in test mode you do this yourself; live, the owner does it on their phone).
curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/simulate \
-H "Authorization: Bearer bsp_test_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "action": "approve" }'3. Read the loan assessment.
curl "https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loan-assessment?months=6&rate=4" \ -H "Authorization: Bearer bsp_test_your_key_here"
The full response is shown under Reading records.
Customers
A customer is one invitation and the connection that follows from it. All addresses below start with https://business-stewards.com/api/partner/v1.
- GET/meno scope
Who the key belongs to, and whether it is a test or live key
- POST/customersno scope
Invite a customer; returns the link to send them
- GET/customersno scope
List your customers, newest first
- GET/customers/{id}no scope
One customer, and where the invitation stands
- DELETE/customers/{id}no scope
Withdraw an invitation or end a connection
- GET/customers/{id}/summarysummary
Cash, this month so far, health score
- GET/customers/{id}/loan-assessmentloan
Eligibility, readiness score, supported loan amount
- GET/customers/{id}/outlookcashflow
Where cash is heading over the next 7–90 days
- GET/customers/{id}/reportcashflow
One calendar month's health report
- GET/customers/{id}/transactionstransactions
Individual entries, newest first
- POST/customers/{id}/loansloan
Tell us about a loan you gave this customer
- GET/customers/{id}/loansno scope
Loans you have reported for this customer
- POST/customers/{id}/loans/{loan_ref}no scope
Tell us how the loan went
- POST/customers/{id}/simulateno scope
Test keys only: approve, decline or disconnect as the owner
Invite a customer — POST /customers
- external_refstring, required
Your own customer number, up to 80 characters. You can have one open invitation or connection per number.
- scopeslist of strings
What you are asking the owner to share: summary, cashflow, loan, transactions. Default: summary and loan. Ask only for what you will use — a shorter list is approved more often.
- business_namestring
Shown to the owner on the approval screen, so they recognise the invitation. Up to 120 characters.
- owner_namestring
For your own reference. Up to 120 characters.
- phone / emailstring
For your own reference. Business Steward does not send the invitation for you — you send the link.
- samplestring
Test keys only: strong, borderline, weak or new.
Safe to repeat. Sending the same external_ref again returns the invitation that is already open, with status 200 rather than 201, so a retry after a timeout never creates a duplicate. Once an invitation is declined, revoked or expired, the same number can be invited afresh.
The link and the code. invite_url opens the approval screen directly. invite_code is the same thing in eight characters, for an owner who would rather type it: in the app, Connect other apps → Have an invitation code from your bank? An invitation lasts 30 days.
Statuses
- pendingstatus
Invited. Waiting for the owner to answer. Nothing can be read.
- activestatus
The owner approved. Records can be read, for the scopes approved.
- declinedstatus
The owner said no. Nothing was shared.
- revokedstatus
Ended — by the owner, or by you (DELETE). ended_by says which.
- expiredstatus
Not answered within 30 days. Invite again to send a fresh link.
List customers — GET /customers
- statusquery
Only customers in this status.
- external_refquery
Find a customer by your own number.
- limitquery
1 to 100. Default 25.
- starting_afterquery
The id of the last customer on the previous page.
{ "object": "list", "data": [ { "id": "…", "object": "customer", … } ], "has_more": true }To read every customer, keep asking with starting_after set to the last id you received, until has_more is false.
End a connection — DELETE /customers/{id}
Withdraws a pending invitation or ends an active connection. You stop being able to read the business immediately, and if you were covering its subscription, that ends too. The customer is returned with status revoked and ended_by: "partner".
What owners approve
Each scope is shown to the owner in these exact words before they decide. A request for a scope that was not approved is refused with 403 scope_not_granted; to add a scope later, end the connection and invite again with the longer list.
- summaryscope
Business summary. Your cash position, this month's money in and running costs, what customers owe you, and your health score.
- cashflowscope
Cash outlook and monthly reports. Where your cash is heading over the next 30 days, and how each month went.
- loanscope
Loan readiness. Your readiness score and the loan amount your records support, with the monthly averages behind it. If it gives you a loan, it may tell Business Steward how the loan went, which helps make these estimates more accurate.
- transactionsscope
Individual entries. Each sale, expense, credit and stock entry you have recorded, with its date, amount and description.
Never shared, whatever was approved: the owner's login, password or PIN; staff logins; and their customers' phone numbers. The API is read-only — a partner cannot add, change or delete anything in a business's books.
The owner can see every institution connected to their business under Connect other apps, with what each can see, and disconnect any of them with one tap. You are told by webhook (customer.revoked, ended_by: "owner").
Reading records
Records are available only while the customer is active; otherwise the answer is 409 customer_not_active. Every record response starts with customer_id and your external_ref, so it can be filed without a second lookup.
Loan assessment — GET /customers/{id}/loan-assessment
- monthsquery
Repayment period, 1 to 24. Default 6.
- ratequery
Flat interest per month, in percent, 0 to 15. Default 4. Set both to your own product's terms and the amounts follow.
{
"customer_id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
"external_ref": "CUST-004512",
"business": "Amara Fashion House",
"code": "SAMPLE-1",
"currency": "NGN",
"as_of": "2026-11-16T09:14:02.337Z",
"eligibility": "likely_eligible",
"headline": "Your records support a loan of about ₦240,000.",
"readiness_score": { "score": 72, "out_of": 100, "grade": "B" },
"estimated_amount": 240000,
"upper_limit": 480000,
"chance_of_repaying_on_time_percent": 90,
"standard_loan_risk_percent": 13,
"monthly_repayment": 49600,
"total_repayable": 297600,
"terms": { "months": 6, "monthly_interest_percent": 4, "interest": "flat" },
"basis": {
"days_of_records": 185, "days_needed": 90, "days_with_entries_percent": 100,
"average_monthly_money_in": 629750,
"average_monthly_running_costs": 411583.33,
"average_monthly_owner_withdrawals": 70000,
"existing_monthly_loan_repayments": 0,
"free_cash_each_month": 148166.67,
"cash_today": 1222600,
"owed_to_suppliers": 0, "customers_owe": 52000, "customers_overdue": 0,
"loans_received_in_period": 0
},
"factors": [
{ "name": "Track record", "effect_points": 0, "direction": "neutral", "note": "About 6 months of records · entries on 100% of days" },
{ "name": "Steady sales", "effect_points": 3, "direction": "helps", "note": "Sales are steady week to week" },
{ "name": "Room to repay", "effect_points": 5, "direction": "helps", "note": "About ₦148,167 a month is left after costs, owner drawings and existing repayments" },
{ "name": "Cash cushion", "effect_points": 2, "direction": "helps", "note": "Cash on hand covers about 89 days of costs" },
{ "name": "Existing debts", "effect_points": 3, "direction": "helps", "note": "No supplier debt or loan repayments recorded" }
],
"strengths": [ "About ₦148,167 a month is left after costs, owner drawings and existing repayments", "…" ],
"to_improve": [ "Pay yourself a fixed amount each month. You are taking out about ₦70,000 a month." ],
"blockers": [],
"monthly_history": [ { "period": "20 May – 18 Jun", "money_in": 625000, "running_costs": 403000, "left": 222000 }, … ],
"model": { "kind": "machine learning", "version": "1.0-sim", "trained": "2026-11-15", "practice_loans": 40000, "real_loans": 0 },
"note": "A model's estimate from the business's own records. It is not a credit decision or an offer of credit."
}- eligibilitystring
likely_eligible, borderline, not_yet, or building_history (fewer than 90 days of records).
- readiness_scoreobject
The model's odds that the business repays a standard loan without trouble, on a 0–100 scale (50 is even odds, 76 is nine-to-one). Grades: A is 80 and above, B 67–79, C 55–66, D below 55.
- estimated_amountnumber
The largest loan, on the terms asked for, that the model expects to be repaid without trouble at least nine times in ten. 0 when not_yet or building_history.
- upper_limitnumber
The same at eight times in ten. Treat as a ceiling, not a target.
- chance_of_repaying_on_time_percentinteger
The model's estimate for estimated_amount.
- standard_loan_risk_percentinteger
The chance of repayment trouble on the standard loan the score is judged on: half a month's money in, over six months at 4% a month.
- monthly_repaymentnumber
The repayment on estimated_amount; total_repayable is the amount plus interest.
- provisional_amountnumber
Only while building_history: where the estimate stands so far. Not to be lent against.
- basisobject
The monthly averages the model's inputs are built from, taken over up to six months of records.
- factorslist
What moved the score, in five groups. effect_points is the exact number of score points the group added or took off against a typical business.
- to_improvelist
The advice the owner is shown in their own app, drawn from what is pulling their score down hardest.
- blockerslist
Plain reasons behind a not_yet, such as nothing being left each month to repay from.
- monthly_historylist
Money in, running costs and what was left for each complete 30-day period, oldest first.
- modelobject
Which model produced the answer, and how many practice and real loans it has learned from. See the model section below.
Summary — GET /customers/{id}/summary
{
"customer_id": "0f6c1a52-…", "external_ref": "CUST-004512",
"business": "Amara Fashion House", "code": "SAMPLE-1", "currency": "NGN", "as_of": "2026-11-16T09:14:40.902Z",
"cash": { "cash_in_hand": 722200, "bank": 500400, "mobile_money": 0, "total": 1222600 },
"this_month": { "money_in": 311500, "running_costs": 232000, "kept": 79500,
"same_days_last_month": { "money_in": 303000, "running_costs": 232000, "kept": 71000 } },
"month_end_forecast": { "money_in": 623000, "running_costs": 464000, "kept": 159000 },
"customers_owe": 52000, "owed_to_suppliers": 0, "runway_days": 79,
"health_score": { "score": 82, "out_of": 100, "parts": [ { "name": "Profitability", "points": 17, "out_of": 20, "note": "Net margin 26% — healthy" }, … ] },
"findings": [ { "level": "good", "title": "Money in is up 3% on last month", "detail": "₦311,500 so far vs ₦303,000 by day 15 last month." } ],
"entries_recorded": 385
}The health score has five parts of 20 points each: profitability, cash position, debt exposure, customer debt and owner withdrawals. It describes this month; the loan readiness score looks back up to six months. They answer different questions and will usually differ.
Cash outlook, monthly report and entries
- /outlook?days=30cashflow
Cash today, the expected balance at the end of the period (7 to 90 days), the tightest day and its date, whether cash is expected to run short, and the expected money in and out with the basis for each line.
- /report?month=2026-10cashflow
One calendar month: money in, running costs, what was kept, the month before for comparison, cash at month end, health score, where the money went, top customers, what went well, what to watch and what to do next. Defaults to the last finished month.
- /transactionstransactions
Individual entries, newest first. Filters: from, to (YYYY-MM-DD), kind (money_in, money_out, customer_owes, we_owe, stock, owner_invested, owner_withdrew, transfer) and limit (1 to 500, default 100).
Field-by-field definitions for every response are in the OpenAPI file.
The loan readiness model
The assessment comes from a machine-learning model. For one business and one loan it estimates a single thing: the chance of repayment trouble — two or more missed instalments, or money still owed at the end. Every figure in the response is read off that estimate. It uses only the owner's own records: no bureau file, no BVN lookup, no device data. Your own credit policy, identity checks and bureau search still apply, and the decision is yours.
What it has learned from — please read this first
Version 1.0-sim has not yet learned from a real loan. No Business Steward business had a recorded loan outcome when it was built, so it was taught on 40,000 practice businesses: day-by-day simulations with swinging sales, slow spells, rent, a household that is fed first, customers who pay late, suppliers who cut off late payers, and owners who do not record everything. The practice world was set so that conventionally sized loans go wrong about one time in ten. Until model.real_loans is well above zero, treat its figures as a structured second opinion, not as a validated scorecard.
How it did on loans it had never seen
- Tested on8,000 loans
One loan in five was kept back from training and used only for testing.
- Telling good from badAUC 0.884
1.0 would be perfect and 0.5 a coin toss.
- Its stated oddscalibrated
When it said about 9.4%, 9.0% went wrong; when it said about 36%, 40% did.
- Against fixed rules1.1% vs 12%
Lending to the same number of applicants as a fixed rule (repayment up to 35% of what is left each month), this share of the model's loans ran into trouble, against the rule's.
These figures show the model has learned the practice world well. They do not show how it performs on real borrowers — that can only be known once real loans have been made and have finished.
What it measures
Fifteen measurements, all of them ratios, so a kiosk and a wholesaler — in naira or in dollars — are measured on the same scale. They are taken from up to the last 180 days of records.
- Track recordhistory_days, active_share
How long the record is, and on what share of days there are entries.
- Steady salesinflow_cv, trend, neg_weeks, worst_month
How much weekly money-in swings, which way it is heading, how often more went out than came in, and how bad the worst month was.
- Room to repayop_margin, drawings
What trading leaves before the owner's drawings, and how much the owner takes out. Books that show almost no drawings are treated as incomplete.
- Cash cushioncover_days
Days of running costs the cash on hand would cover — capped at 60, so a large balance (the easiest figure in a set of books to get wrong) cannot buy a larger estimate.
- Existing debtssup_debt, overdue_recv, existing_repay
Unpaid supplier bills, customers paying late, and loan repayments already being made, each against monthly money in.
- The loan itselfburden_free, burden_inflow, tenor
The monthly repayment against what is left each month and against money in, and the number of months.
Why this kind of model
It is an additive boosted model: one learned curve for each measurement, added together. That was chosen over a black box for one reason — every answer can be explained exactly. The effect_points in factors are not an approximation; they are each group's actual share of the score. Curves are held to one direction where the direction is not in doubt, so a larger repayment can never be scored as safer.
From the model to the figures
- readiness_score0–100
The odds of no trouble on a standard loan (half a month's money in, six months, 4% a month), on the scale used for lending scorecards: every 12 points multiplies the odds by about 2.7.
- estimated_amountrisk ≤ 10%
The largest loan, on the terms you ask about, whose chance of trouble is 10% or less.
- upper_limitrisk ≤ 20%
The largest loan whose chance of trouble is 20% or less.
- likely_eligibleeligibility
An estimated amount exists, and the standard loan's risk is 20% or less.
- borderlineeligibility
Some loan stays within 20% risk, but the business does not meet the line above. The amount quoted is the cautious end.
- not_yeteligibility
Not even a loan of 5% of a month's money in stays within 20% risk — or no money in is recorded.
- building_historyeligibility
Fewer than 90 days of records: too little to judge, whatever the model says.
Three guardrails are not learned. No amount is given under 90 days of records. A repayment is never set above what the books show is left each month. And the risk can only rise with the size of the loan.
How it gets better
By learning from what actually happened. When you report a loan and, later, how it went, the business's measurements on the day of the loan are kept with the outcome, and the model is trained again on real results. The model field in every response says which version answered and how many real loans it has learned from; the -sim at the end of the version name goes once it has learned from any.
Its limits. The figures are only as complete as the owner's recording. A business that records only its good days will look better than it is; compare days_with_entries_percent and, where you hold it, the account turnover you can see yourself.
Reporting loans
Two calls per loan: one when you give it, one when it ends. This is optional, and it is the single most useful thing a partner can do — it is what turns a model taught on practice loans into one that knows your borrowers.
When you give a loan — POST /customers/{id}/loans
- loan_refstring, required
Your own loan number, up to 80 characters. Sending it again returns the loan already recorded.
- amountnumber, required
The principal, in the business's own currency.
- monthsinteger, required
1 to 60.
- monthly_interest_percentnumber, required
Flat interest per month, 0 to 30.
- disbursed_ondate
YYYY-MM-DD. Defaults to today.
curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loans \
-H "Authorization: Bearer bsp_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "loan_ref": "LN-2026-00871", "amount": 250000, "months": 6,
"monthly_interest_percent": 4, "disbursed_on": "2026-11-20" }'HTTP/1.1 201 Created
{
"object": "loan",
"loan_ref": "LN-2026-00871",
"customer_id": "0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11",
"external_ref": "CUST-004512",
"mode": "live",
"amount": 250000, "months": 6, "monthly_interest_percent": 4, "disbursed_on": "2026-11-20",
"status": "active", "missed_instalments": null, "closed_on": null,
"predicted_risk_percent": 11, "model_version": "1.0-sim",
"created_at": "2026-11-20T10:02:11.402Z", "updated_at": "2026-11-20T10:02:11.402Z"
}The connection must be active and include the loan scope, because the business's measurements are taken that day. Only the fifteen measurements are stored with the loan — ratios, with nothing that names the business. predicted_risk_percent is what the model said at that moment, kept so it can be checked against what happens.
When it ends — POST /customers/{id}/loans/{loan_ref}
- statusstring, required
active, repaid, repaid_late, defaulted or written_off.
- missed_instalmentsinteger
How many instalments were missed over the life of the loan.
- closed_ondate
YYYY-MM-DD.
curl -X POST https://business-stewards.com/api/partner/v1/customers/0f6c1a52-7d0b-4b1e-9a57-3c2f8e4d6b11/loans/LN-2026-00871 \
-H "Authorization: Bearer bsp_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "status": "repaid", "missed_instalments": 0, "closed_on": "2027-05-20" }'You can send this more than once as a loan's standing changes, and after the connection has ended. For learning, a loan counts as troubled if it is defaulted or written_off, or had two or more missed instalments. GET /customers/{id}/loans lists what you have reported. Owners are told, on the approval screen, that a lender may report how a loan went.
Webhooks
Give us an HTTPS address and we send it a POST whenever an owner answers or a connection ends. You receive a signing secret (whsec_…) to check that each message really came from Business Steward.
- customer.approvedevent
The owner approved. The customer is now active and its business details are included.
- customer.declinedevent
The owner declined. Nothing was shared.
- customer.revokedevent
The owner disconnected (ended_by: owner). Ending it yourself with DELETE sends no event.
POST /your/webhook/address
Content-Type: application/json
X-Steward-Event: customer.approved
X-Steward-Signature: t=1794822764,v1=5d1c0e6b…c41a
{
"id": "evt_3f9c1b7a52e04d6c8a1f0b2d4e6a8c90",
"type": "customer.approved",
"mode": "live",
"created_at": "2026-11-16T09:12:44.118Z",
"data": { "customer": { "id": "0f6c1a52-…", "external_ref": "CUST-004512", "status": "active", … } }
}Checking the signature
Take the timestamp t and the raw request body, exactly as received. Compute HMAC-SHA256 of t + "." + body with your signing secret, in hex, and compare it with v1. Reject the message if they differ, or if t is more than five minutes old.
// Node.js
const crypto = require("crypto");
function isFromSteward(rawBody, header, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // too old
const expected = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}# Python
import hmac, hashlib, re, time
def is_from_steward(raw_body: bytes, header: str, secret: str) -> bool:
m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
if not m or abs(time.time() - int(m.group(1))) > 300:
return False
expected = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, m.group(2))Delivery. Each event is sent once, and we wait five seconds for any 2xx answer. There are no automatic retries in this version, so treat webhooks as a prompt rather than the record: if your endpoint was down, GET /customers?status=active always shows the truth. Every event carries its own id, for your records. The address must be public HTTPS; redirects are not followed.
Errors and limits
Errors always have the same shape. Build on code, which will not change; show or log message, which may be reworded.
HTTP/1.1 409 Conflict
{ "error": { "code": "customer_not_active", "message": "The owner has not approved this connection yet." } }- 400invalid_json
The body is not a JSON object.
- 401missing_key
No Authorization header.
- 401invalid_key
The key is wrong, switched off, or of the wrong kind.
- 403partner_suspended
Your partner account is suspended.
- 403scope_not_granted
The owner did not approve this kind of record.
- 403customer_unavailable
The business is paused, or is not a business account.
- 403test_only
simulate was called with a live key.
- 404customer_not_found
No such customer for this key. Test and live customers are separate.
- 404not_found
No such address.
- 405method_not_allowed
That address does not take that method.
- 409customer_not_active
The owner has not approved yet, or the connection has ended.
- 409not_pending
The invitation was already answered or has expired.
- 409not_open
The connection had already ended.
- 404loan_not_found
No loan with that loan_ref for this customer.
- 422invalid_request
A field is missing or wrong. The message says which.
- 429rate_limited
Too many requests. Wait for the seconds given in Retry-After.
- 500server_error
Something failed on our side. Safe to try again.
- 503not_available
The partner API is not switched on.
Rate limit. 300 requests a minute for each key. Beyond that the answer is 429 with a Retry-After header in seconds; wait, then carry on. For a nightly refresh of a large book, spread the calls out rather than sending them in one burst.
Retrying. GET and DELETE are safe to repeat. POST /customers is safe to repeat for the same external_ref. On a 500 or a network timeout, wait a few seconds and try again, doubling the wait each time.
Versions. This is version 1, and the version is in the address. New fields may be added to responses at any time, so ignore fields you do not recognise. Anything that would break a working integration — removing a field, changing a meaning — will come as a new version, with notice and both running side by side.
Paying for your customers
Business Steward is free for a business's first 6 months and then paid by subscription (pricing). An institution can instead agree to cover its customers. When that is switched on for your account, /me shows covers_subscription: true, the owner is told on the approval screen, and every business that connects to you uses Business Steward at no cost to them for as long as the connection lasts.
Each covered customer shows subscription_covered: true. Cover ends when the connection ends, from either side, and the business goes back to its own arrangement. Terms are agreed with us directly — ask.
Security and data
- Consent is recorded, and can be withdrawn
A connection exists only because an owner pressed Approve, and the time is kept. The owner can withdraw at any moment; access stops with the next request.
- Least access
You ask for named scopes; the owner sees them in plain words; nothing outside them is ever returned. The API cannot change a business's books.
- Keys
Keys are stored as a SHA-256 fingerprint, never in the clear, and can be switched off instantly. Test and live are separate keys and separate customers.
- Transport
HTTPS only. Webhooks are signed with HMAC-SHA256 and sent only to public HTTPS addresses.
- Your side of it
Keep live keys on your servers. Store only what you need, for as long as you need it. When an owner disconnects, stop using what you hold beyond what your own legal duties require.
How Business Steward itself handles personal information is set out in the privacy policy.
Going live
Before a live key is issued, we ask you to confirm each of these against test mode.
- 01You invite a customer and store the id against your own customer number.
- 02Your message to the customer explains who Business Steward is and why you are asking, and carries the invite link.
- 03You handle all five statuses, including declined and expired, without treating them as errors.
- 04You handle a strong, a borderline, a weak and a new business — the four samples — sensibly in your own screens.
- 05You check the webhook signature, and still work when a webhook is missed.
- 06You handle 409 customer_not_active and 403 scope_not_granted when reading records: an owner can disconnect at any time.
- 07You back off on 429 and retry on 500.
- 08Live keys are held on your servers only, with a named person responsible for rotating them.
Ready to start?
Tell us who you are and what you want to build, and we will reply by email.