CashVerify API Docs

Developer integration kit

Integrate payment verification in minutes

Call once with your API key. We fetch the bank receipt, match your expected values, claim the transaction so it cannot be reused, and notify you by webhook when needed.

API key auth Hosted checkout Up to 3 bank retries 5-day payment age Each receipt used once Signed webhooks
API base https://your-host

Quick start · deposit verify

This is the first path: you collect the receipt and call verify. The hosted pay page and payouts are the other two links above.

1. Get credentials

An admin creates your company in the dashboard and shares a one-time API key plus optional webhook secret.

  • API key looks like pv_live_…
  • Store it server-side only — never in mobile/web clients
  • Optional HTTPS webhook URL for async results

2. Verify a payment

From your backend, POST /api/v1/verify once with the receipt and what you expected.

  • Send at least one of link, transactionId, or SMS message
  • Send orderId and expected.amount so the amount is checked before the receipt is claimed
  • Use Idempotency-Key if you retry the same request

3. Handle the result

Read status. That is the only field you need to branch on. See verify statuses for the full list.

  • verified → mark the order paid
  • pending → show “still confirming…” and wait for the webhook (or poll the attempt)
  • Anything else → show the error string; do not credit

Authentication

Every v1 endpoint requires your company API key, except public GET /api/v1/banks (supported bank list for UIs).

Header (preferred)

Authorization: Bearer pv_live_YOUR_KEY

Or

X-Api-Key: pv_live_YOUR_KEY

Security

Keys are hashed at rest. Revoke compromised keys from Admin → Companies. Prefer server-to-server calls only.

Verify API

POST /api/v1/verify · GET /api/v1/verify/attempts/:id · GET /api/v1/banks (public)

POST /api/v1/verify

Verify a Telebirr, CBE, Ebirr, Abyssinia, or Awash receipt and claim it if matched. bank: "auto" detects the bank from the paste. generic is only for an unknown receipt URL.

Request body

{
  "bank": "auto",
  "transactionId": "CG51RYXTXY",
  "orderId": "ord_12345",
  "expected": {
    "amount": 500,
    "name": "Your Business Name",
    "account": "2519****5678"
  }
}
FieldTypeNotes
bankstringauto (detect) · telebirr · cbe · ebirr · abyssinia · awash · generic (unknown URL)
linkurlFull receipt URL. Send at least one of link, transactionId, or message
transactionIdstringBank reference / TX id (min 6)
messagestringFull SMS — we extract link / id
accountSuffixstringCBE only: last 8 digits of the sender or receiver account, with a short FT… id
accountNumberstringOn verify: Abyssinia payer / sender account, with a short FT… id. On withdraw: the receiver account (Telebirr: phone)
orderIdstringYour order / invoice id. Send this so the claim is tied to your order
expectedobjectSend amount. Also name, account (the receipt value to match — not accountSuffix or accountNumber), date, reference. If you omit expected, a real receipt is claimed with no amount check

Optional headers

Idempotency-Key: ord_12345-CG51RYXTXY
Content-Type: application/json

Once that attempt has a final result, sending the same Idempotency-Key returns that result and does not verify again.

cURL

curl -s "$BASE/api/v1/verify" \
  -H "Authorization: Bearer pv_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ord_12345-CG51RYXTXY" \
  -d '{
    "bank": "telebirr",
    "transactionId": "CG51RYXTXY",
    "orderId": "ord_12345",
    "expected": { "amount": 500 }
  }'
GET /api/v1/verify/attempts/:id

Poll an attempt after a 202 pending response (webhook is preferred). result is the same JSON POST /api/v1/verify returned, or null while it is still pending.

GET /api/v1/verify/attempts/ATTEMPT_UUID
Authorization: Bearer pv_live_YOUR_KEY
{
  "success": true,
  "attemptId": "…",
  "status": "verified",
  "orderId": "ord_12345",
  "bank": "telebirr",
  "reference": "CG51RYXTXY",
  "attemptCount": 1,
  "result": { "status": "verified", "verified": true },
  "createdAt": "…",
  "updatedAt": "…"
}
GET /api/v1/banks

Public. No API key. Use this to fill bank dropdowns in your UI.

{
  "success": true,
  "banks": [
    { "id": "telebirr", "label": "Telebirr", "logo": "/image/banks/telebirr.jpg" }
  ]
}

Hosted checkout (redirect)

Use this when you want a ready-made pay page instead of collecting the receipt yourself. The same one-time claim and webhooks still apply.

  1. In admin, add at least one active receive account for the company. Create fails with 400 if none are active.
  2. From your backend, POST /api/v1/checkout/sessions with orderId, amount, successUrl, and cancelUrl.
  3. Redirect the customer to checkoutUrl. They pick an account, pay that account, and paste the SMS / link / TX. Failed verify stays on the page until it succeeds.
POST /api/v1/checkout/sessions

Requires API key. Returns a one-time checkoutUrl.

{
  "orderId": "ord_12345",
  "amount": 100,
  "currency": "ETB",
  "successUrl": "https://your-shop.com/paid",
  "cancelUrl": "https://your-shop.com/cart",
  "expiresInMinutes": 60
}
{
  "success": true,
  "sessionId": "…",
  "checkoutUrl": "https://your-host/checkout/TOKEN",
  "expiresAt": "…"
}

The page matches the session amount and the receive account the customer picked. You do not send expected. Optional support phone / URL (set in admin) appear on the page. Direct POST /api/v1/verify is separate and still uses expected from that request only.

Return URLs (per session)

successUrl and cancelUrl are required on each session (not company settings). They must be absolute https:// (or http://) URLs. Query params below are merged onto your URL (existing query string is kept).

EventRedirectQuery params added
Payment verified successUrl orderId, sessionId, attemptId, status=verified
Customer cancels cancelUrl orderId, sessionId, status=cancelled
Soft pending (202) No redirect yet Checkout keeps polling; redirects to successUrl only after verified
// After success (~1s), browser goes to e.g.:
https://your-shop.com/paid?orderId=ord_12345&sessionId=…&attemptId=…&status=verified

// After cancel:
https://your-shop.com/cart?orderId=ord_12345&sessionId=…&status=cancelled

Verify / cancel API responses also include a ready-made redirectUrl. Treat the browser return as UX only — mark the order paid from the webhook or by polling the attempt (idempotent on attemptId / claimId).

Verify / deposit statuses

This table is for POST /api/v1/verify and hosted checkout — not withdraw. Withdraw uses queued, assigned, processing, approved, failed, and cancelled — see Withdraw. Always check status (and HTTP code). Failures include a human-readable error string — show it to operators or end users. Verify answers within about 25 seconds: a final status, or 202 pending while we keep retrying in the background. Do not call verify again just because the bank was slow. Concurrent verifies of the same receipt share one bank fetch. If that receipt is already claimed, already_used returns immediately.

statusHTTPMeaningYour action
verified200Matched & claimedFulfill order
pending202Bank did not finish within ~25s; retries continue in the backgroundShow “still confirming…”; wait for webhook or poll
mismatch422Receipt OK but expected failed — see error + match.checksShow which fields differ; ask customer to correct
already_used409TX already claimed. Returned immediately when the bank and reference are known — error may include the prior orderReject — possible replay
too_old422Payment older than retention windowReject (see error / maxAgeDays)
invalid_date422No usable payment dateReject / support
fetch_failed400Bank fetch failed after retriesAsk customer to retry later; show error
invalid400/401Bad input or API keyFix request / key

Verified example

{
  "success": true,
  "verified": true,
  "status": "verified",
  "claimId": "…",
  "attemptId": "…",
  "orderId": "ord_12345",
  "bank": "telebirr",
  "reference": "CG51RYXTXY"
}

Mismatch example

{
  "success": false,
  "verified": false,
  "status": "mismatch",
  "error": "Amount mismatch: expected 500, receipt shows 450. Account mismatch: expected 10001234, receipt shows 1******34.",
  "bank": "telebirr",
  "reference": "CG51RYXTXY",
  "match": {
    "verified": false,
    "message": "Amount mismatch: expected 500, receipt shows 450. Account mismatch: expected 10001234, receipt shows 1******34.",
    "checks": {
      "amount": { "expected": 500, "actual": 450, "pass": false },
      "account": { "expected": "10001234", "actual": ["1******34"], "pass": false }
    }
  }
}

Already used example

{
  "success": false,
  "verified": false,
  "status": "already_used",
  "error": "This receipt was already used for order prior_order",
  "reference": "CG51RYXTXY",
  "claimedAt": "…",
  "orderId": "prior_order",
  "sameCompany": true
}

If no prior order id is available: This receipt was already used for a previous payment.

Withdraw

Send a payout with the same company API key. These statuses are not the verify table — create returns queued or assigned. Approval arrives later on your existing webhook as withdraw.completed.

POST /api/v1/withdraws

Requires API key. transactionId is your own withdraw id, not a bank receipt.

{
  "transactionId": "wd_12345",
  "bank": "telebirr",
  "amount": 1000,
  "name": "Receiver Name",
  "accountNumber": "0912345678"
}
{
  "success": true,
  "withdraw": {
    "id": "…",
    "transactionId": "wd_12345",
    "status": "assigned",
    "approved": false,
    "bank": "telebirr",
    "amount": 1000,
    "name": "Receiver Name",
    "accountNumber": "0912345678",
    "bankReference": null,
    "error": null,
    "deviceId": "…",
    "createdAt": "…",
    "updatedAt": "…",
    "completedAt": null
  }
}
  • Sending the same transactionId again returns the original withdraw and does not pay twice
  • A payout phone for that bank must be registered and online in admin, and have enough balance. Otherwise the status stays queued
  • For Telebirr, accountNumber is the receiver phone
  • Do not mark the withdraw paid from this response. Wait for withdraw.completed or poll the withdraw
GET /api/v1/withdraws/:id

Read the current status with the same API key. The body is the same withdraw object as create. Final values are approved, failed, or cancelled. processing means the phone is still sending it.

GET /api/v1/withdraws/WITHDRAW_UUID
Authorization: Bearer pv_live_YOUR_KEY
{
  "success": true,
  "withdraw": { "id": "…", "status": "approved", "approved": true }
}
POST /api/v1/withdraws/:id/cancel

Allowed while the withdraw is queued or assigned. A withdraw already in progress cannot be cancelled.

POST /api/v1/withdraws/WITHDRAW_UUID/cancel
Authorization: Bearer pv_live_YOUR_KEY
statusMeaningYour action
queuedCreated; waiting for an online payout phone with enough balanceWait or poll — not paid yet
assignedHanded to a payout phoneWait — not paid yet
processingThe payout phone is sending itWait — not paid yet
approvedPayout sentMark the withdraw complete
failedDid not send — see errorDo not treat as paid
cancelledYou cancelled while queued or assignedNo payout

Webhooks

When a deposit verify or a withdraw finishes, we POST the same company webhook URL. X-PV-Event is verification.completed or withdraw.completed. verification.completed means the attempt finished — including mismatch and fetch_failed. Credit only when status is verified. Failed deliveries are retried with the same backoff.

Headers

Content-Type: application/json
X-PV-Event: verification.completed
X-PV-Delivery-Id: …
X-PV-Signature: sha256=<hmac_hex>

X-PV-Event is verification.completed or withdraw.completed. The sample above is the deposit event.

Verify signature (Node)

import { createHmac, timingSafeEqual } from 'crypto';

function valid(rawBody, secret, header) {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  const a = Buffer.from(header || '');
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Payload shape

{
  "event": "verification.completed",
  "attemptId": "…",
  "orderId": "ord_12345",
  "status": "verified",
  "verified": true,
  "claimId": "…",
  "bank": "telebirr",
  "reference": "CG51RYXTXY",
  "extracted": { },
  "match": { },
  "attemptCount": 1,
  "completedAt": "…",
  "error": null
}

Deposit event. Read status before you credit. Respond 2xx quickly. Failed deliveries are retried with backoff.

Withdraw payload

Same headers and HMAC. X-PV-Event is withdraw.completed. Sent when the payout is approved or failed, not while it is still queued.

{
  "event": "withdraw.completed",
  "withdrawId": "…",
  "transactionId": "wd_12345",
  "status": "approved",
  "approved": true,
  "bank": "telebirr",
  "amount": 1000,
  "name": "Receiver Name",
  "accountNumber": "0912345678",
  "bankReference": "reference from the payout",
  "error": null,
  "completedAt": "…"
}

A payout that did not send uses "status": "failed" and "approved": false.

Bank inputs

Pass whatever the customer shared. With bank: "auto" we detect from the link, id, or SMS.

BankTypical inputRequired for a short TX id
Telebirr SMS message, receipt link, or 10-character transactionId None — the 10-character id is enough
CBE Receipt link or SMS (including mbreciept) FT… id plus accountSuffix (last 8 of sender or receiver)
Ebirr Full receipt link, or an SMS that contains it Id alone is not enough
Abyssinia Slip link or SMS that contains the slip URL Short FT… id plus payer accountNumber
Awash AwashPay receipt link or the full SMS Id alone is not enough

Platform rules

One call, server retries

Call verify once. We retry the bank up to 3 times. Concurrent requests for the same receipt share that fetch. Do not spam the endpoint.

5-day payment age

Receipts older than 5 days return too_old and are not claimed.

Global uniqueness

Each (bank, reference) can be claimed once on the platform. Second use → already_used.

Retention

Claims and attempt history used for replay detection are kept ~5 days, then purged.

Verify client flow

This is the deposit-verify path. Hosted checkout and withdraw are the other two paths above.

  1. Customer submits receipt / SMS / TX id with their order.
  2. Your backend calls POST /api/v1/verify with API key + orderId + expected.
  3. If verified → mark paid. If pending → show “still confirming…” and wait for webhook (or poll the attempt).
  4. On failure → surface error (and for mismatch, optionally match.checks) in your UI.
  5. On webhook / poll final status → update order atomically (idempotent on attemptId / claimId).
  6. Never trust client-side verification alone.