# callCash

> One client for South African payments: Yoco and Netcash behind one call, with every payment checked with the gateway before your code hears about it. callCash never holds money. Today it is the `callcash` npm package (0.1.0, not yet published), running inside your own server on your own gateway keys. A hosted API with cc_ keys is planned and not built.

Rules for agents writing payment code: amounts are rand, not cents; fulfil orders only in the webhook handler on payment.paid, never on the redirect; make the handler idempotent by event.id; always return r.response from webhook routes; keep callcash on the server. The package ships these rules as node_modules/callcash/AGENTS.md.

## Start

- [Introduction](https://callcash.riverrr.co.za/docs/index.md): What callCash is, what works today, and what is still planned.
- [Quickstart](https://callcash.riverrr.co.za/docs/quickstart.md): Take a test payment with the built-in test gateway. No account, no keys, no money.
- [Install](https://callcash.riverrr.co.za/docs/install.md): How to add the callcash package while it is not on npm yet.
- [Configuration](https://callcash.riverrr.co.za/docs/configuration.md): Every option new CallCash() takes, and the three ways to run it.

## Gateways

- [Yoco](https://callcash.riverrr.co.za/docs/yoco.md): Connect your Yoco account: keys, the webhook secret, the return URL, and what callCash checks.
- [Netcash](https://callcash.riverrr.co.za/docs/netcash.md): Connect Netcash Pay Now: the service key, test mode, the four NetConnector URLs, and how unsigned notifications are checked.

## Building

- [Payments](https://callcash.riverrr.co.za/docs/payments.md): Create, read, list and update payments; how references are reused; routing and failover between gateways.
- [Webhooks and events](https://callcash.riverrr.co.za/docs/webhooks.md): One handler for every gateway. What is checked, how events arrive once, and what happens when your handler fails.
- [Refunds](https://callcash.riverrr.co.za/docs/refunds.md): Refund all or part of a payment on Yoco, and record refunds made in the Netcash portal.
- [Errors](https://callcash.riverrr.co.za/docs/errors.md): Every error code, when it happens, whether it is safe to retry, and what to do.
- [Testing](https://callcash.riverrr.co.za/docs/testing.md): Test your payment code with the built-in test gateway, then with Yoco test keys and Netcash test mode.
- [Framework examples](https://callcash.riverrr.co.za/docs/examples.md): Copy-ready code for Next.js (App Router) and Express.

## Help

- [Troubleshooting](https://callcash.riverrr.co.za/docs/troubleshooting.md): The problems you are most likely to hit, and what to check.
- [Use with AI agents](https://callcash.riverrr.co.za/docs/ai-agents.md): Point Claude Code, Codex, Cursor and Gemini CLI at callCash's rules, and give them the docs as Markdown.
- [Status](https://callcash.riverrr.co.za/docs/status.md): Exactly what is verified, what is assumed, and what is not built yet, as of version 0.1.0.

## Optional

- [All docs in one file](https://callcash.riverrr.co.za/llms-full.txt): every page above, concatenated