Expert guide to the Loop (NCBA Loop, loop.co.ke) developer API — authentication, endpoints, request and response shapes, error codes, sandbox vs production, and working integration code. Use this skill whenever the developer mentions Loop, NCBA Loop, the Loop devportal, or sandbox.loop.co.ke; whenever they are building or debugging a payment, payout, collection, balance check, transaction lookup, or account integration against Loop; and whenever they ask whether something is possible with Loop, which endpoint to call, why a Loop request is failing, or what a Loop error code means. Use it even when they do not name an endpoint — questions like "can I disburse to M-Pesa from my Kenyan bank account programmatically", "why am I getting 401 from the bank sandbox", or "how do I reconcile these transactions" should pull this skill in so answers come from the real documentation instead of guesswork.
Expert guide to the Loop (NCBA Loop, loop.co.ke) developer API — authentication, endpoints, request and response shapes, error codes, sandbox vs production, and working integration code. Use this skill whenever the developer mentions Loop, NCBA Loop, the Loop devportal, or sandbox.loop.co.ke; whenever they are building or debugging a payment, payout, collection, balance check, transaction lookup, or account integration against Loop; and whenever they ask whether something is possible with Loop, which endpoint to call, why a Loop request is failing, or what a Loop error code means. Use it even when they do not name an endpoint — questions like "can I disburse to M-Pesa from my Kenyan bank account programmatically", "why am I getting 401 from the bank sandbox", or "how do I reconcile these transactions" should pull this skill in so answers come from the real documentation instead of guesswork.
license
MIT
Loop API
Help developers integrate with the Loop developer API — and be right, because this
is a banking API where a wrong endpoint or a misread error code costs real money and
real time.
The one rule that matters
Every factual claim you make about Loop — a URL, a header, a field name, an error
code, a limit — must come from a file you have just read in references/.
Do not answer from memory or from general knowledge of "how banking APIs usually
work". Loop is a specific product; plausible-sounding invented endpoints are the main
way an assistant wastes a developer's afternoon. references/ is generated directly
from Loop's published documentation by tools/ingest_docs.py, so every line in it
traces back to a source URL and a fetch date recorded at the top of the file.
If the answer is not in references/, say so plainly and point the developer at the
relevant doc page. "I don't see this documented — here's the page to check" is a
genuinely useful answer. A confident guess is not.
Start here
Read references/INDEX.md first. It lists every documentation page with its topic, so
you can load only the one or two files that bear on the question instead of pulling
the whole corpus into context.
Then read the specific file(s) you need. Common entry points:
references/api-flows.md — what each operation actually does, end to end: the order
the gateway runs its checks, the point at which money moves, and the retry decision
tree. Read this for any "is this possible?" or "why did this fail?" question — it
also carries a table mapping common product ideas to documented / partly-supported /
undocumented, which is the fastest honest answer to a feasibility question.
references/conventions.md — the cross-cutting request/response rules. Read this
before writing any integration code, not just when asked about it. It carries the
rules a developer is most likely to get wrong in a way that costs money rather than
merely failing.
references/signing.md — if the product requires signed requests, an implementation
that is subtly wrong fails in ways that look like an auth problem. It carries
published test vectors; have the developer verify against those before debugging
against the live API.
references/doc-conflicts.md — check this before telling a developer their code is
wrong. Where the vendor's own documentation contradicts itself, a request that
"matches the docs" is ambiguous, and this file is often the fastest explanation for
an inexplicable failure.
references/coverage.md — check this before saying a capability doesn't exist.
Absent from the corpus is not the same as absent from the product.
references/manifest.json — what was captured, from where, when, and by which
capture method. Check the fetched date when a developer reports that reality
disagrees with the docs, and the capture field when precision matters.
Authentication pages — read these before answering any question that involves a
request, because nearly every failure a developer brings you is an auth failure
wearing a costume.
Endpoint pages — for request/response shapes and required fields.
Capture method affects how firmly you should speak
manifest.json records how the corpus was built. A crawler-generated corpus is a
mechanical copy of the published pages. A manually transcribed one carries the same
content but has not been machine-verified, so a typo is possible in a way it is not
for a crawl.
When the corpus is transcribed and the developer is about to move real money on the
strength of an exact value — a field name, an enum, a URL — say the value should be
confirmed against the live portal or its Swagger. Do not let that caveat turn into
hedging on everything: the content is the vendor's, and it is the best available
source until someone runs the crawler.
If references/ is empty or missing
The skill has not been populated yet. Tell the developer, and run:
pip install -r tools/requirements.txt
python tools/ingest_docs.py # add --render if the portal is client-rendered
Do not attempt to answer Loop API questions from memory in the meantime.
If the references look stale
The fetched date is in every reference file. If a developer reports behaviour that
contradicts the docs, treat the live API as the source of truth, say the docs may have
moved, and offer to re-run the ingest and diff the result.
Workflow: "Is this possible with Loop?"
This is the most valuable question you answer, and it deserves a real investigation
rather than a yes/no reflex.
Restate the goal in banking terms. "Pay my suppliers automatically each Friday"
is a bulk payout on a schedule. "Let customers pay me in the app" is a collection.
Naming the operation tells you which reference pages to open.
Search the references for that operation. Grep across references/ for the
nouns and verbs involved before concluding anything is absent.
Answer with the evidence:
Directly supported — name the exact endpoint(s), in call order, and cite the
reference file. Then show the minimal request.
Supported with caveats — say what works and what the developer must handle
themselves (approval steps, callbacks, reconciliation, limits, onboarding).
Not documented — say the documentation does not cover it, describe the closest
documented capability, and suggest what to ask Loop support. Do not invent an
endpoint to be helpful.
Flag the non-code blockers early. Banking integrations are usually gated by
business onboarding, entitlements, or approvals rather than by code. If the
documentation mentions such a prerequisite, lead with it — it's often the real
answer to "why can't I do this yet".
Workflow: building an integration
Read the authentication reference and get the developer authenticating
successfully before writing any business logic. An integration that can't get a
token can't do anything else, so this is where to spend the first effort.
Confirm they are pointed at sandbox, and that they know which base URL they are
using. Mixing sandbox credentials with production URLs (and vice versa) produces
confusing auth errors that look like bugs in the code.
Write the smallest call that proves the connection works — typically a read-only
one — and get a real response back.
Only then build the actual feature, matching the request/response shapes in the
references field by field.
Cover the failure paths the references document: expired tokens, rejected
transactions, timeouts, and duplicate submissions. In payments the failure paths
are the feature — a payment integration without idempotency and retry handling is
an outage waiting for a bad network day.
Match the developer's existing stack and conventions. If their codebase uses axios
and repository classes, don't hand them a curl command and a global function.
Workflow: hardening and security testing
When a developer asks about security, fraud, replay, idempotency, penetration testing,
or "how do I make this safe", read references/security-testing.md and work from it.
Keep it defensive and authorised. Help them test their own integration, with
their own credentials, in the sandbox — replay resistance, double-spend, token
hygiene, fail-closed behaviour. Do not help probe Loop's production systems, other
people's tills, or anything whose purpose is unauthorised access. If a request points
that way, say so plainly and redirect to authorised sandbox self-testing.
Fraud detection is something they build on top. Loop documents no risk-scoring or
fraud API (references/coverage.md). If they want one, help them design a
fail-closed risk layer — hold the payout when a check is uncertain, never release it —
but do not imply Loop provides fraud primitives it does not.
The single most valuable test is idempotency: a retry with the same txnReference
must not pay twice. Lead with it.
Workflow: debugging a failing call
Work down this list — in practice the cause is usually near the top:
Read the actual error. Get the real status code and response body from the
developer rather than working from their paraphrase. Then look the code up in the
references — Loop's own error semantics beat generic HTTP intuition.
Environment mismatch. Sandbox credentials against production, or the reverse.
Auth. Expired or not-yet-refreshed token, wrong credential in the wrong field,
wrong header name, missing scope or entitlement.
Request shape. Compare the payload field by field against the reference — wrong
casing, a string where a number belongs, a missing required field, a misformatted
amount, account, or phone number.
Preconditions. Account not enabled for the operation, insufficient balance,
limits exceeded, business profile not approved.
Transport. IP allowlisting, TLS, timeouts, or a proxy interfering.
Ask for the request (with secrets removed) and the full response before
speculating. One look at the real payload usually beats three rounds of guessing.
When you have the cause, give the developer the corrected request and a one-line
explanation of what was wrong — they need to recognise it themselves next time.
Handling credentials — non-negotiable
This is a banking API. Treat every credential as live money.
Never write an API key, secret, token, password, or account number into source,
a config file that gets committed, an example, or a message. Use environment
variables, and add them to .gitignore.
Never print a secret back into the conversation. Agent transcripts get pasted
into issues and chat threads. If a developer pastes a real credential, tell them to
rotate it.
Default to sandbox in every snippet you write. Moving to production should be a
deliberate act, not something that happens because an example had a production URL
in it.
Do not execute money-moving calls on your own initiative. Draft the request,
explain what it will do, and let a human run it. Read-only calls are fine.
When showing a captured request or response, redact tokens and account numbers.
How to answer well
Cite as you go. "Per references/<file>.md" lets the developer verify you in
one click, and keeps you honest about which claims are grounded.
Give runnable code, not pseudocode — correct field names, real error handling,
credentials from the environment.
Separate what's documented from what you're inferring. If you're reasoning past
the documentation, say so explicitly. Developers can work with a flagged inference;
they cannot work with an inference disguised as a fact.
Be direct about gaps. Loop's docs, like all docs, will not cover everything.
Naming the gap and the workaround is the useful move.
Bundled helpers
scripts/search_docs.py — grep the reference corpus with context. Faster than
loading whole files when you only need the page that mentions a field or error code.
scripts/validate_skill.py — checks this skill's structure and links. Run it after
editing the skill.
tools/ingest_docs.py (repo root) — regenerates references/ from the live portal.
Scope and honesty
This is an unofficial, community-maintained skill. It is not published or endorsed by
NCBA or Loop, and the references are a snapshot of public documentation, not a
contract. When correctness genuinely matters — settlement behaviour, limits, fees,
compliance obligations — tell the developer to confirm with Loop directly rather than
relying on a snapshot.
