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.
Developer integration kit
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.
Pick a path You collect the receipt Customer uses the hosted pay page You pay someone out
https://your-host
This is the first path: you collect the receipt and call verify. The hosted pay page and payouts are the other two links above.
An admin creates your company in the dashboard and shares a one-time API key plus optional webhook secret.
pv_live_…From your backend, POST /api/v1/verify once with the receipt and what you expected.
link, transactionId, or SMS messageorderId and expected.amount so the amount is checked before the receipt is claimedIdempotency-Key if you retry the same requestRead status. That is the only field you need to branch on. See verify statuses for the full list.
verified → mark the order paidpending → show “still confirming…” and wait for the webhook (or poll the attempt)error string; do not creditEvery v1 endpoint requires your company API key, except public GET /api/v1/banks (supported bank list for UIs).
Authorization: Bearer pv_live_YOUR_KEY
X-Api-Key: pv_live_YOUR_KEY
Keys are hashed at rest. Revoke compromised keys from Admin → Companies. Prefer server-to-server calls only.
POST /api/v1/verify · GET /api/v1/verify/attempts/:id · GET /api/v1/banks (public)
/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.
{
"bank": "auto",
"transactionId": "CG51RYXTXY",
"orderId": "ord_12345",
"expected": {
"amount": 500,
"name": "Your Business Name",
"account": "2519****5678"
}
}
| Field | Type | Notes |
|---|---|---|
bank | string | auto (detect) · telebirr · cbe · ebirr · abyssinia · awash · generic (unknown URL) |
link | url | Full receipt URL. Send at least one of link, transactionId, or message |
transactionId | string | Bank reference / TX id (min 6) |
message | string | Full SMS — we extract link / id |
accountSuffix | string | CBE only: last 8 digits of the sender or receiver account, with a short FT… id |
accountNumber | string | On verify: Abyssinia payer / sender account, with a short FT… id. On withdraw: the receiver account (Telebirr: phone) |
orderId | string | Your order / invoice id. Send this so the claim is tied to your order |
expected | object | Send 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 |
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 -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 }
}'
/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": "…"
}
/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" }
]
}
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.
POST /api/v1/checkout/sessions with orderId, amount, successUrl, and cancelUrl.checkoutUrl. They pick an account, pay that account, and paste the SMS / link / TX. Failed verify stays on the page until it succeeds./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.
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).
| Event | Redirect | Query 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).
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.
| status | HTTP | Meaning | Your action |
|---|---|---|---|
| verified | 200 | Matched & claimed | Fulfill order |
| pending | 202 | Bank did not finish within ~25s; retries continue in the background | Show “still confirming…”; wait for webhook or poll |
| mismatch | 422 | Receipt OK but expected failed — see error + match.checks | Show which fields differ; ask customer to correct |
| already_used | 409 | TX already claimed. Returned immediately when the bank and reference are known — error may include the prior order | Reject — possible replay |
| too_old | 422 | Payment older than retention window | Reject (see error / maxAgeDays) |
| invalid_date | 422 | No usable payment date | Reject / support |
| fetch_failed | 400 | Bank fetch failed after retries | Ask customer to retry later; show error |
| invalid | 400/401 | Bad input or API key | Fix request / key |
{
"success": true,
"verified": true,
"status": "verified",
"claimId": "…",
"attemptId": "…",
"orderId": "ord_12345",
"bank": "telebirr",
"reference": "CG51RYXTXY"
}
{
"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 }
}
}
}
{
"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.
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.
/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
}
}
transactionId again returns the original withdraw and does not pay twicequeuedaccountNumber is the receiver phonewithdraw.completed or poll the withdraw/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 }
}
/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
| status | Meaning | Your action |
|---|---|---|
| queued | Created; waiting for an online payout phone with enough balance | Wait or poll — not paid yet |
| assigned | Handed to a payout phone | Wait — not paid yet |
| processing | The payout phone is sending it | Wait — not paid yet |
| approved | Payout sent | Mark the withdraw complete |
| failed | Did not send — see error | Do not treat as paid |
| cancelled | You cancelled while queued or assigned | No payout |
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.
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.
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);
}
{
"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.
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.
Pass whatever the customer shared. With bank: "auto" we detect from the link, id, or SMS.
| Bank | Typical input | Required 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 |
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.
Receipts older than 5 days return too_old and are not claimed.
Each (bank, reference) can be claimed once on the platform. Second use → already_used.
Claims and attempt history used for replay detection are kept ~5 days, then purged.
This is the deposit-verify path. Hosted checkout and withdraw are the other two paths above.
POST /api/v1/verify with API key + orderId + expected.verified → mark paid. If pending → show “still confirming…” and wait for webhook (or poll the attempt).error (and for mismatch, optionally match.checks) in your UI.attemptId / claimId).