Installing the skill
This guide is also packaged as a Claude skill: innbucks-integration. Install it once and
Claude uses everything in this guide on its own whenever you work on an InnBucks integration.
It sends amounts in cents, sends both the API key and the bearer token, refreshes the token
before 15 minutes, checks codes every 30 seconds, treats Claimed as paid, never re-sends a
deposit after a timeout, and knows which details InnBucks has not documented.
16.1 What you are installing
One folder, innbucks-skills/innbucks-integration:
SKILL.md |
Setup, auth, the endpoint map, the payment and agent flows, and the rules that keep money safe. Always loaded. |
references/ |
Twelve deep-dive files generated from this guide’s sections 2-15. Read only when a task needs them. |
templates/ |
The tested clients from section 9: PHP/Laravel (service, exception, polling job), Node.js and Python. |
scripts/innbucks_cli.py |
A standard-library tool Claude runs for you: log in, lint a payload, generate and check codes, build deep links, and run agent calls against the test environment. |
config/innbucks.env.example |
The .env template from section 4.3. |
evals/evals.json |
Test prompts and checks for benchmarking the skill. |
It has no dependencies, makes no network calls of its own, and sends no telemetry. The
references/ and templates/ are generated from this README by tools/build_skill.py, so the
skill never knows more or less than this guide.
16.2 Install in Claude Code
Clone the repository and copy the skill folder into place.
git clone https://github.com/67even/innbucks-merchant-api-integration.git
cd innbucks-merchant-api-integration
For one project. The skill loads only in that repository:
mkdir -p /path/to/your/project/.claude/skills
cp -r innbucks-skills/innbucks-integration /path/to/your/project/.claude/skills/
For every project on your machine:
mkdir -p ~/.claude/skills
cp -r innbucks-skills/innbucks-integration ~/.claude/skills/
On Windows (PowerShell):
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse innbucks-skills\innbucks-integration "$HOME\.claude\skills\"
Either way you should end up with <skills-dir>/innbucks-integration/SKILL.md. Start a new
Claude Code session and it is picked up automatically.
⚠️ Don’t install it in both places. A personal skill in
~/.claude/skills/overrides a project skill with the same name, so an old copy in your home directory silently wins over a freshly updated copy in the repository.
16.3 Install on claude.ai, desktop and mobile
Claude on the web and in the desktop app takes a ZIP, uploaded once and available everywhere you’re signed in.
The ready-made zip is attached to every
release as
innbucks-integration.zip. Download it, or build it from a clone:
cd innbucks-skills
zip -r innbucks-integration.zip innbucks-integration -x '*/evals/*' -x '*/.DS_Store' -x '*/__pycache__/*'
Then in Claude: Customize → Skills → + → Create skill → Upload a skill, and choose that file.
⚠️ Zip the folder, not its contents. The archive must contain
innbucks-integration/SKILL.md, and the folder name has to match thename:inSKILL.md. A zip of loose files is rejected, and the error doesn’t say why.
16.4 Confirm Claude loaded it
In Claude Code, run /skills. innbucks-integration should be listed. If it’s missing, the
folder is in the wrong place or SKILL.md isn’t directly inside it:
ls ~/.claude/skills/innbucks-integration/SKILL.md must find a file.
On claude.ai, the skill appears under Customize → Skills with a toggle. It has to be on.
16.5 Use it
You don’t invoke the skill by name. Its description tells Claude when it is relevant, and Claude decides. Ask for what you want:
Add InnBucks payments to our Laravel ticketing app: a service, config, a checkout page with
the code, QR code and deep link, and a job that checks the code until it's paid.
Our InnBucks payments show US$0.04 on the customer's phone instead of US$4.50. Here's our code.
Every InnBucks call starts failing with 401 about 15 minutes after the app starts.
We're an InnBucks agent. Build the deposit flow with the ID check, and handle lost responses.
Review our Node.js InnBucks integration before we submit UAT.
It also recognises InnBucks’ own vocabulary when you never type “InnBucks”: /api/code/generate,
/api/code/inquiry, /auth/third-party, X-Api-Key with a bearer token, paymentToken,
authNumber and stan, destinationMsisdn, originalParticipantReference, statuses
Claimed / Timed Out, *569#.
16.6 The innbucks_cli.py tool
Claude runs this for you, but it works on its own too (Python 3, standard library only). It reads
the same INNBUCKS_* variables as the templates.
cd innbucks-skills/innbucks-integration
python3 scripts/innbucks_cli.py self-test # the payload linter checks itself
python3 scripts/innbucks_cli.py lint generate body.json # cents, currency, type, field names
python3 scripts/innbucks_cli.py deeplink 535403380 # the deep link for INNBUCKS_ENV
python3 scripts/innbucks_cli.py --env-file .env login # proves credentials (token masked)
python3 scripts/innbucks_cli.py --env-file .env generate --amount 100 --reference QS-1
python3 scripts/innbucks_cli.py --env-file .env inquiry --code 535403380
python3 scripts/innbucks_cli.py --env-file .env wait --code 535403380 # every 30 s until final
python3 scripts/innbucks_cli.py --dry-run generate --amount 100 --reference QS-1 # print, send nothing
It refuses to move money in production (deposit, reversal, bank-change, utility) unless
you pass --allow-live, never re-sends a request after a timeout, and never checks a code more
often than every 30 seconds.
16.7 How well it works
Four realistic tasks were run with the skill and without it (same model, no network), then graded against the same checklist:
| Task | With the skill | Without |
|---|---|---|
| Build Laravel ticket checkout (service, config, checkout page, status checks) | 7/7 | 3/7: invented the inquiry path and deep-link scheme, sent dollars instead of cents, polled every 5-10 seconds |
| Fix a token that stops working after a while (401s) | 3/3 | 1/3: did not know the 15-minute lifetime, guessed the login path and made the API key optional |
| Build an agent cash-deposit flow that survives lost responses | 5/5 | 0/5: no linked account inquiry or ID check, decimal amounts, and it re-sent deposits with no deposit inquiry |
| Review an integration before UAT | 5/5 | 1/5: missed the 30-second rule, Claimed, the deposits-only reversal and the UAT video |
| Overall | 100% | 25% |
The prompts and checks are in evals/evals.json; the method and costs are in
VERIFICATION.md. The skill costs about 17k extra tokens per
task, mostly from reading the reference files.
16.8 Updating and uninstalling
The skill is versioned with this repository. Each release lists what changed (also in CHANGELOG.md) and carries the matching skill zip. Updating means copying it again:
cd innbucks-merchant-api-integration && git pull
rm -rf ~/.claude/skills/innbucks-integration
cp -r innbucks-skills/innbucks-integration ~/.claude/skills/
On claude.ai, upload the new release’s zip (or zip it again); the new version replaces the old one. To uninstall, delete the folder, or switch the skill off in Customize → Skills.
This page is generated from section 16 of the README in README.md. Spotted something wrong? Open an issue.