Quickstart

The test gateway is built in. It needs no gateway account and moves no money, so you can write and test your payment code today.

1. Install#

The package is not on npm yet. See Install for how to add it from the repo.

2. Create a payment#

import { CallCash } from "callcash";

const cash = new CallCash(); // no config: the test gateway

const payment = await cash.payments.create({ amount: 250, reference: "order_1" });
// payment.status === "pending", payment.gateway === "test"

amount is rand: 250 means R250.00. reference is your own order number.

3. Decide what happens#

The test gateway has no checkout page: checkout_url and checkout_form are both null. You decide the outcome in code instead.

async function onCash(event) {
  if (event.type === "payment.paid") console.log("fulfil", event.reference, event.amount);
}

await cash.test.pay(payment.id, onCash); // your handler gets payment.paid

Other outcomes to rehearse, each on a fresh payment:

await cash.test.fail(id, onCash, "insufficient funds");     // payment.failed
await cash.test.pay(id, onCash, { amount: 2.5 });           // the gateway confirms the wrong total: payment.mismatch
await cash.test.pay(id, onCash, { method: "instant_eft" }); // paid by instant EFT

4. Read it back#

const p = await cash.payments.get(payment.id);
// p.status === "paid", p.verified === true, p.paid_at is set

What the test gateway does not do#

• It keeps payments in memory. A restart forgets them.
• It sends no webhooks. cash.test.pay() stands in for the webhook.
• It shows no checkout page. To see a real checkout, use Yoco test keys or Netcash test mode.
• Refunds on test payments succeed straight away.

Next#

When your handler does the right thing for paid, failed and mismatch, connect a real gateway: Configuration.