← Home

PayVerify API

Verify Telebirr & CBE payments programmatically. Base URL /api/v1.

Authentication

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_xxxxxxxx

Responses include an x-request-id and rate-limit headers (x-ratelimit-remaining, retry-after on 429).

Create a payment request (optional)

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"}'

Submit a verification

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).

Instant verify by SMS (Telebirr)

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.

Look up a transaction

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.

Statuses & decisions

decision.source is SMS, BANK_API, GEMINI, or MANUAL; decision.reasons[] carries machine-readable codes (e.g. OUTSIDE_WINDOW, AMOUNT_MISMATCH, DUPLICATE_TRANSACTION).

Receipt-date window

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.

Webhooks

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));
}

Rate limits & quotas

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

Errors return { error: { code, message, request_id } }. Branch on code; quote request_id in support.

unauthorized / invalid_api_key401Missing/invalid/revoked key
rate_limited429Too many requests
quota_exceeded402Monthly quota reached
validation_error422Bad/missing fields (see details)
not_found404Resource not in your project
provider_unreachable502Bank provider/relay unreachable
invalid_state409Verification already has a txn / decided
sms_match_unavailable422SMS matching off for project/provider
unsupported_media_type415Use multipart or JSON
internal500Server error — retry / contact support