Verify Telebirr & CBE payments programmatically. Base URL /api/v1.
Pass your project API key as a bearer token (or x-api-key header). Create keys in the dashboard; they are shown once.
Authorization: Bearer pk_live_xxxxxxxxResponses include an x-request-id and rate-limit headers (x-ratelimit-remaining, retry-after on 429).
Create an intent when you ask a customer to pay. Its timestamp anchors the REQUEST_TIME receipt-date window.
curl -X POST /api/v1/payment-requests \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"expectedAmount": 250, "providerCode": "TELEBIRR", "externalRef": "order_123"}'Provide a transaction number, a receipt file, or both. Multipart for files; JSON for transaction-only.
curl -X POST /api/v1/verifications \
-H "Authorization: Bearer $KEY" \
-F "amount=250" \
-F "providerCode=TELEBIRR" \
-F "transactionNumber=ABC123XYZ" \
-F "paymentRequestId=pr_..." \
-F "externalRef=order_123" \
-F "[email protected]"The bank check runs inline: when it resolves you get 200 with the final decision (APPROVED / REJECTED / NEEDS_REVIEW). When a receipt still needs OCR you get 202 with a PENDING verification — the result arrives by webhook, or poll GET /api/v1/verifications/:id. Reusing an externalRef returns the original (idempotent).
Pair the merchant's receiving phone in SMSWire and point its webhook at /api/integrations/smswire/<projectId> (URL + signing secret in project settings). Then the customer pays and enters only the last 4 digits of the phone they paid from:
curl -X POST /api/v1/verifications -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"amount": 250, "providerCode": "TELEBIRR", "payerLast4": "1234", "externalRef": "order_123"}'If the bank SMS (sender 127) with that payer and amount already arrived you get 200 APPROVED (decision.source = SMS). Otherwise 202 PENDING with sms_deadline_at: poll GET /api/v1/verifications/:id or wait for the webhook. Only a unique match approves — if two pending payments share last-4 and amount, the SMS is marked ambiguous and the reason SMS_AMBIGUOUS is added.
After sms_deadline_at, ask the customer for the transaction number:
curl -X POST /api/v1/verifications/<id>/transaction -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{"transactionNumber": "CKH8ABC12D"}'Checked against stored bank SMS first, then the bank API — same 200/202 semantics as create. A late SMS can still approve a pending verification; the txn ledger prevents any payment being used twice. 409 invalid_state if the verification already has a txn or was decided; 422 sms_match_unavailable if SMS matching is off.
Fetch a transaction straight from the provider — no matching, nothing stored. Returns the normalized payer / recipient / amount / date. For CBE, pass accountSuffix (last digits of the receiving account) so the reference resolves.
curl -X POST /api/v1/transactions/lookup \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"provider": "TELEBIRR", "transactionNumber": "ABC123XYZ"}'200 with the transaction; 404 not_found when the provider has no such transaction; 502 provider_unreachable when the provider/relay is down.
APPROVED — auto-verified by bank SMS, bank API or OCR rules.NEEDS_REVIEW — ambiguous; queued for a human in the dashboard.REJECTED — duplicate or a clear mismatch.PENDING — still processing.decision.source is SMS, BANK_API, GEMINI, or MANUAL; decision.reasons[] carries machine-readable codes (e.g. OUTSIDE_WINDOW, AMOUNT_MISMATCH, DUPLICATE_TRANSACTION).
Each project sets a window (minutes), a reference point (TODAY or REQUEST_TIME), and a direction. A receipt dated outside the window is routed to manual review instead of auto-approving — configure it in project settings.
Set a webhook URL in project settings to receive verification events: verification.approved, verification.rejected, verification.needs_review. Deliveries retry with backoff.
Each request carries X-PayVerify-Event, X-PayVerify-Delivery, and a signed X-PayVerify-Signature: t=<unix>,v1=<hmac>. Verify it with your webhook secret:
import crypto from "crypto";
function verify(rawBody, header, secret) {
const [t, v1] = header.split(",").map(p => p.split("=")[1]);
const expected = crypto.createHmac("sha256", secret)
.update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Requests are rate-limited per API key (429 with Retry-After + X-RateLimit-* headers). Projects may also have a monthly verification quota — exceeding it returns 402 quota_exceeded.
Errors return { error: { code, message, request_id } }. Branch on code; quote request_id in support.
unauthorized / invalid_api_key401Missing/invalid/revoked keyrate_limited429Too many requestsquota_exceeded402Monthly quota reachedvalidation_error422Bad/missing fields (see details)not_found404Resource not in your projectprovider_unreachable502Bank provider/relay unreachableinvalid_state409Verification already has a txn / decidedsms_match_unavailable422SMS matching off for project/providerunsupported_media_type415Use multipart or JSONinternal500Server error — retry / contact support