KERSHI DEVELOPERS

API Documentation

Explore endpoints, request/response contracts, and production-ready integration patterns.

Real-provider checks use the server-side Ethiopian Payment Verify SDK. Only bank-fetched evidence with matching amount and receiver is marked verified.

Authentication

Authenticate server-side requests using the x-api-key header. Keep API keys private.

Headers

x-api-key: <your-api-key>
Content-Type: application/json

Base URLs

Production API

https://YOUR_KERSHI_HOST/api

Bank Fields

Bank	Required	Fields
`cbe`	Required	Reference number, Account suffix (last 8 digits)
`telebirr`	Required	Transaction number
`dashen`	Required	Reference number
`abyssinia`	Required	Reference number, Account suffix (5 digits)
`cbebirr`	Required	Receipt number, Phone (251XXXXXXXXX)
`awash`	Required	Receipt URL or token
`mpesa`	Required	Transaction number
`sinqe`	Required	Receipt URL or token
`ebirr`	Required	Receipt URL or token, Phone (optional)

Settlement Matching

Settlement account matching verifies that a valid receipt was paid into the intended wallet or bank account.

How matching works

Save the receiver once, then send its settlementAccountId. The full value is AES-GCM encrypted; API responses return only masked values. Ethiopian phone formats and bank-account suffixes are normalized before matching.

Strict verification request

{
  "provider": "cbe",
  "reference": "FT26262VQ6GV",
  "accountSuffix": "35207333",
  "amountMinor": 13500,
  "settlementAccountId": "<saved-account-id>"
}

Matched Response Object

{
  "verificationStatus": "verified",
  "assurance": "authoritative",
  "amountMatch": true,
  "recipientMatch": true,
  "reference": "FT••••GV",
  "source": "bank_receipt"
}

Endpoints

POST /api/v1/verifications

Submit a verification

Submit or review a bank payment verification request.

Request Body

curl -X POST 'https://YOUR_KERSHI_HOST/api/v1/verifications' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $KERSHI_API_KEY' \
  -H 'Idempotency-Key: <unique-request-id>' \
  -d '{
    "provider": "cbe",
    "reference": "<receipt-reference>",
    "accountSuffix": "<8-digits>",
    "amountMinor": 13500,
    "settlementAccountId": "<saved-account-id>"
  }'

RESPONSES

200 · Completed 202 · Processing 400 · Invalid request

GET /api/v1/verifications/:requestId

Retrieve verification result

Submit or review a bank payment verification request.

Request Body

curl -X POST 'https://YOUR_KERSHI_HOST/api/v1/verifications' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $KERSHI_API_KEY' \
  -H 'Idempotency-Key: <unique-request-id>' \
  -d '{
    "provider": "cbe",
    "reference": "<receipt-reference>",
    "accountSuffix": "<8-digits>",
    "amountMinor": 13500,
    "settlementAccountId": "<saved-account-id>"
  }'

RESPONSES

200 · Completed 202 · Processing 400 · Invalid request

POST /api/v1/webhook-endpoints/:id/test

Test a webhook endpoint

Sends a sample webhook payload to validate your endpoint.

Request Body

{
  "webhookUrl": "https://your-app.example/webhooks/verify",
  "scenario": "success"
}

RESPONSES

200 · Completed 202 · Processing 400 · Invalid request

Webhooks

Delivered by the worker after a verification reaches a terminal state.

Webhook Delivery

{
  "event": "verification.completed",
  "requestId": "sample-request-id",
  "data": {
    "processingStatus": "completed",
    "status": "success",
    "verified": true,
    "bank": "cbe",
    "amount": "1500",
    "currency": "ETB",
    "referenceNumber": "DEMO-12345678"
  }
}

Event