Quickstart

This walkthrough takes you from credentials to a completed charge and payout in the sandbox. Every request goes to https://api.zerocash.tech.

Use your sandbox keys throughout. Sandbox and production share the same base URL — the credentials decide which environment you are in. See Environments.

Step 1 — Generate a bearer token

Exchange your public key and API key for a token.

curl --request POST \
  --url https://api.zerocash.tech/api/b2b/auth/generate-bearer-token \
  --header 'api-key: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{"publicKey":"YOUR_PUBLIC_KEY"}'

const auth = await fetch(
  "https://api.zerocash.tech/api/b2b/auth/generate-bearer-token",
  {
    method: "POST",
    headers: {
      "api-key": process.env.ZEROCASH_API_KEY,
      "content-type": "application/json",
    },
    body: JSON.stringify({ publicKey: process.env.ZEROCASH_PUBLIC_KEY }),
  }
).then((r) => r.json());

const token = auth.token;

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.....",
  "expiresAt": 1752085041
}

Send this token as Authorization: Bearer <token> on every request that follows. It expires at expiresAt (Unix seconds) — refresh against that value rather than assuming a fixed lifetime.

Step 2 — Collect a payment

Charge a customer’s mobile money wallet. For KES you only need the phone number; every other currency also needs a momoOperatorId from the mobile money operators list.

curl --request POST \
  --url https://api.zerocash.tech/api/b2b/fiat/deposit/momo \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "amount": 100,
    "currency": "KES",
    "externalReference": "order_12345",
    "phoneNumber": "254712345678"
  }'

const charge = await fetch(
  "https://api.zerocash.tech/api/b2b/fiat/deposit/momo",
  {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      amount: 100,
      currency: "KES",
      externalReference: "order_12345",
      phoneNumber: "254712345678",
    }),
  }
).then((r) => r.json());

Response

{
  "success": true,
  "message": "Initiated request.",
  "transactionId": "123456789"
}

This response means the request was accepted, not that money moved. The customer still has to approve the prompt. Do not fulfil the order yet.

externalReference is your own unique ID. Keep it unique per attempt — it is how you reconcile, and how you avoid double-charging on a retry.

Step 3 — Confirm the outcome

Money movement is asynchronous, so you confirm the result one of two ways.

Webhooks (recommended)
Polling

Configure a webhook URL in your dashboard and Zerocash pushes each status change to you.

transaction_updated

{
  "event": "transaction_updated",
  "data": {
    "transactionId": "BeOfXV1NVIcZlsSVeQAF",
    "status": "successful",
    "type": "deposit",
    "externalReference": "order_12345",
    "method": "momo",
    "thirdPartyReference": "TEQTEYRU"
  },
  "timestamp": "2024-10-03T16:33:14.600Z"
}

Always verify the signature before trusting a payload.

Look the transaction up by transactionId or by your externalReference.

curl --request GET \
  --url https://api.zerocash.tech/api/b2b/transactions/order_12345 \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Response

{
  "success": true,
  "data": {
    "transactionId": "lBK9bMny2gs4hLsG3XGq",
    "amount": 100,
    "type": "deposit",
    "currency": "KES",
    "chargeStatus": "successful",
    "status": "SUCCESSFUL",
    "method": "momo",
    "externalReference": "order_12345",
    "thirdPartyReference": "TFH174NFSJ"
  }
}

Some charges come back with a stepRequired field before they reach a final status:

`stepRequired`	What to do
`otp`	Collect the code from the customer and submit it to Validate OTP.
`redirect`	Send the customer to the returned `redirectUrl` to authorise the payment.

Only release goods or credit an account once the status is successful.

Step 4 — Send a payout

Payouts use a single endpoint for every destination. The destination field and the shape of payoutMethod determine where the money goes.

curl --request POST \
  --url https://api.zerocash.tech/api/b2b/fiat/payout \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "amount": 100,
    "currency": "KES",
    "country": "KE",
    "externalReference": "payout_12345",
    "destination": "MoMo",
    "payoutMethod": {
      "accountName": "Test User",
      "accountNumber": "254712345678"
    }
  }'

curl --request POST \
  --url https://api.zerocash.tech/api/b2b/fiat/payout \
  --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "amount": 100,
    "currency": "KES",
    "country": "KE",
    "externalReference": "payout_12346",
    "destination": "Bank Account",
    "payoutMethod": {
      "accountName": "Test User",
      "accountNumber": "1234567890",
      "code": "07"
    }
  }'

Response

{
  "success": true,
  "message": "Withdrawal Request Accepted for Processing.",
  "transactionId": "mIt5ycmF3YCqaOQp6Ljz"
}

As with charges, this is an acknowledgement. Wait for the transaction_updated webhook — or poll the transaction — before you treat the payout as delivered.

In sandbox, account number 254712345678 always succeeds and 254787654321 always fails, so you can exercise both branches. Full list in Testing payouts.

Where to next

Choose a charge method

Compare mobile money, bank transfer, card, and OPay.

Payouts in depth

Every destination type, cross-currency debits, and saved beneficiaries.

Set up webhooks

Receive status changes instead of polling.

API reference

Full schemas and an interactive playground for all 32 endpoints.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Step 1 — Generate a bearer token

Step 2 — Collect a payment

Step 3 — Confirm the outcome

Step 4 — Send a payout

Where to next

Choose a charge method

Payouts in depth

Set up webhooks

API reference

​Step 1 — Generate a bearer token

​Step 2 — Collect a payment

​Step 3 — Confirm the outcome

​Step 4 — Send a payout

​Where to next

Choose a charge method

Payouts in depth

Set up webhooks

API reference

Step 1 — Generate a bearer token

Step 2 — Collect a payment

Step 3 — Confirm the outcome

Step 4 — Send a payout

Where to next