Installing the skill
This guide is also packaged as a Claude skill: ecocash-instant-payment. Install it once
and Claude uses everything in this guide on its own whenever you work on an EcoCash EIP
integration. It writes charges with the exact field names, keeps /sandbox/payment/v1 in the
URL, never re-sends a charge after a timeout, and knows which portal details are still unconfirmed.
12.1 What you are installing
One folder, ecocash-skills/ecocash-instant-payment:
SKILL.md |
Setup, auth, the endpoint map, the payload and payment-flow rules, and the three unconfirmed portal details. Always loaded. |
references/ |
Twelve deep-dive files: this guide’s sections 2-11, plus the portal’s Documentation and SDKs & Codegen tabs verbatim. Read only when a task needs them. |
templates/ |
The tested clients from section 8: PHP/Laravel, Node.js, Python, Java (Spring) and C# (.NET 8). |
scripts/eip_cli.py |
A standard-library tool Claude runs for you: build the auth header, lint a payload, and charge, look up, wait for and refund in the sandbox. |
config/eip.env.example |
The .env template from section 3.2. |
evals/evals.json |
The test prompts used to benchmark the skill (12.7). |
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.
12.2 Install in Claude Code
Clone the repository and copy the skill folder into place.
git clone https://github.com/67even/ecocash-instant-payment-api.git
cd ecocash-instant-payment-api
For one project. The skill loads only in that repository:
mkdir -p /path/to/your/project/.claude/skills
cp -r ecocash-skills/ecocash-instant-payment /path/to/your/project/.claude/skills/
For every project on your machine:
mkdir -p ~/.claude/skills
cp -r ecocash-skills/ecocash-instant-payment ~/.claude/skills/
Either way you should end up with <skills-dir>/ecocash-instant-payment/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.
12.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
ecocash-instant-payment.zip. Download it, or build it from a clone:
cd ecocash-skills
zip -r ecocash-instant-payment.zip ecocash-instant-payment -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
ecocash-instant-payment/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.
12.4 Confirm Claude loaded it
In Claude Code, run /skills. ecocash-instant-payment 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/ecocash-instant-payment/SKILL.md must find a file.
On claude.ai, the skill appears under Customize → Skills with a toggle. It has to be on.
12.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 EcoCash payments to our Laravel ticketing app using the EcoCash Instant Payment API -
a service, config, and endpoints to start a payment and poll for the result.
Our EcoCash refunds return 400 and sometimes 409. Here's the body we send: { ... }
Every request from our .NET app to the EcoCash EIP sandbox returns 404. Here's our HttpClient setup.
Review our Node.js EcoCash integration before we apply for production access.
Walk me through getting EcoCash sandbox credentials and a test number.
It also recognises EIP’s own vocabulary when you never type “EcoCash”: charginginformation,
chargeMetaData, terminalID, clientCorrelator, originalEcocashReference,
/transactions/amount/, tranType MER/REF/REV, sandbox PINs 0000-9999, errors
E001-E015. It stays out of the way for Paynow checkout, where EcoCash is one payment option
of a different API.
12.6 The eip_cli.py tool
Claude runs this for you, but it works on its own too (Python 3, standard library only). It reads
the same EIP_* variables as the templates.
cd ecocash-skills/ecocash-instant-payment
python3 scripts/eip_cli.py self-test # the payload linter checks itself
python3 scripts/eip_cli.py lint body.json # casing, amount, tranType, MSISDN, undocumented fields
python3 scripts/eip_cli.py --env-file .env header # the Basic Authorization header
python3 scripts/eip_cli.py --env-file .env charge --msisdn 263771234567 --amount 1
python3 scripts/eip_cli.py --env-file .env wait --msisdn 263771234567 --correlator <printed-correlator>
python3 scripts/eip_cli.py --env-file .env refund --msisdn 263771234567 --original-ref <transactionId> --amount 1
python3 scripts/eip_cli.py --dry-run charge --msisdn 263771234567 --amount 1 # print it, secrets masked, send nothing
It refuses any base URL other than the sandbox unless you pass --allow-live, and charge never
retries: after a timeout, run lookup with the same correlator.
12.7 How well it works
Three 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, start and poll endpoints) | 7/7 | 4/7: built against a different EcoCash API, with an invented X-API-KEY header and field names |
| Diagnose a failing refund payload (400/409) | 8/8 | 7/8: presented REF as settled, and added undocumented fields and status names |
| Fix a .NET app that gets 404 on every call | 5/5 | 2/5: removed the required trailing slash, and read the wrong status field |
| Overall | 100% | 62% |
The prompts and checks are in evals/evals.json. The skill costs about 20k extra tokens per
task, mostly from reading the reference files.
12.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 ecocash-instant-payment-api && git pull
rm -rf ~/.claude/skills/ecocash-instant-payment
cp -r ecocash-skills/ecocash-instant-payment ~/.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 12 of the README in README.md. Spotted something wrong? Open an issue.