📖 Developer Reference v1.0

WithPay API Documentation

Integrate tip collection, event ticketing, and wedding RSVPs into your app. Use these REST endpoints to initialize checkouts, verify transactions, and listen to real-time webhooks.

📥 Download Postman Collection ⚡ Quick Start

✓ API v1.0 · Stable REST · JSON https://www.withpay.bayainnovation.com/api

🔐

Authentication

Every API request must include your secret key via the Authorization header as a Bearer token. You can generate keys from your API Keys page.

Header Format

HTTP

Authorization: Bearer tip_live_xxxxxxxxxxxxxxxxx

⚡

Rate Limiting

Default limit is 60 requests / minute. Exceeding this will return 429 Too Many Requests. Contact support to increase your limit.

POST https://www.withpay.bayainnovation.com/api/checkout

Initializes a new payment checkout session. Returns a secure checkout_url to redirect your payer to.

Request Body (JSON)

Parameter	Type	Description
amount Required	float	Amount to charge. Must be greater than 0.
currency	string	Defaults to `ETB`. Supported: `ETB`, `USD`.
description	string	Short reason for the payment (e.g. "Donation", "Tip").
callback_url	string	Webhook URL Chapa POSTs to on success. Overrides account default.
return_url	string	Where to redirect the user after a successful transaction.

Example Request

JSON

{
  "amount": 100,
  "currency": "ETB",
  "description": "Support my work",
  "callback_url": "https://www.withpay.bayainnovation.com/api/webhook",
  "return_url":   "https://www.withpay.bayainnovation.com/payment/success"
}

Example Response

JSON · 200 OK

{
  "success": true,
  "message": "Checkout initialized.",
  "data": {
    "checkout_url": "https://www.withpay.bayainnovation.com/checkout/WP-660F1B2C3D4E5"
  }
}

📱

QR Code Integration

The checkout_url is designed to be embedded in QR codes. Use any standard QR library to transform it into a scannable code for your users. Tip: https://www.withpay.bayainnovation.com/checkout/{tx_ref}

GET https://www.withpay.bayainnovation.com/api/verify?tx_ref={tx_ref}

Retrieves the status and complete metadata of a specific transaction using its unique reference ID.

Query Parameters

Parameter	Type	Description
tx_ref Required	string	The unique transaction reference returned during initialization.

Example Response

JSON · 200 OK

{
  "success": true,
  "message": "Transaction found.",
  "data": {
    "tx_ref":     "WP-660F1B2C3D4E5-8A9B0C1D",
    "chapa_ref":  "chapa-req-12345",
    "amount":     "100.00",
    "currency":   "ETB",
    "status":     "success",
    "payer_name": "Abebe Kebede",
    "created_at": "2024-04-03 14:00:00"
  }
}

GET https://www.withpay.bayainnovation.com/api/events/verify/{reference}

Verifies an event ticket booking using its unique reference (e.g., BK-XXXXXXXX). Ideal for scanning QR codes at the door.

URL Parameters

Parameter	Type	Description
reference Required	string	The unique booking reference (e.g., `BK-63B6C4CF`).

Example Response

JSON · 200 OK

{
  "status": "success",
  "data": {
    "reference":      "BK-63B6C4CF",
    "event_title":    "Summer Music Festival",
    "buyer_name":     "John Doe",
    "buyer_phone":    "0912345678",
    "tier":           "vip",
    "quantity":       2,
    "booking_status": "confirmed",
    "created_at":     "2026-05-08 12:45:00"
  }
}

GET https://www.withpay.bayainnovation.com/api/wedding/verify/{reference}

Verifies a wedding RSVP booking using its unique reference (e.g., WD-XXXXXXXX). Use for QR code scanning at the wedding venue entrance.

URL Parameters

Parameter	Type	Description
reference Required	string	The unique wedding booking reference (e.g., `WD-63B6C4CF`).

Example Response

JSON · 200 OK

{
  "status": "success",
  "data": {
    "reference":       "WD-63B6C4CF",
    "wedding_title":   "Bride's & Groom's Wedding",
    "buyer_name":      "Almaz Abera",
    "buyer_phone":     "0911223344",
    "ticket_quantity": 2,
    "rsvp_status":     "confirmed",
    "created_at":      "2026-05-24 18:30:00"
  }
}

🪝

Webhooks Verification

If you provided a callback_url during checkout initialization, WithPay will send a POST request to your server when the transaction completes.

Signature Verification (PHP)

PHP

$rawInput  = file_get_contents('php://input');
$signature = $_SERVER['HTTP_CHAPA_SIGNATURE'];
$expected  = hash_hmac('sha256', $rawInput, 'YOUR_WEBHOOK_SECRET');

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    die('Invalid Signature');
}

// Signature OK — process the event
$event = json_decode($rawInput, true);

⚠️

Testing on Localhost?

Webhooks require a public URL. Use Ngrok or LocalTunnel to expose your local server for testing.

🌐

HTTP Response Codes

200 OK Request succeeded. Response body contains data.

400 Bad Request Malformed JSON body or missing required fields.

401 Unauthorized Missing or invalid Authorization Bearer token.

422 Validation Error Request was valid but semantic validation failed.

429 Too Many Requests Rate limit exceeded (60 req/min). Slow down and retry.

502 Bad Gateway Could not reach the Chapa payment gateway.