EBITS Pay REST API (v1)

EBITS Pay has two layers:

Both layers run in the same Laravel application, so there is nothing extra to host. Anything done through the API shows up straight away in the portal and its audit trail, and the other way round.

Base URL: https://<your-domain>/api/v1. All responses are JSON.

1. Authentication

You can get a token in two ways:

• From the portal: go to My profile → API access tokens → Create token. The token is shown once, so copy it then.
• From an app: sign in with the user's email and password:

POST /api/v1/auth/token
Content-Type: application/json

{ "email": "treasurer@ktwa.org", "password": "••••••••", "device_name": "Finance app (Android)" }

201 Created
{
  "token": "ebp_4Fq…",            // keep it secret; it is shown only this once
  "token_type": "Bearer",
  "expires_in_days": 90,
  "user": { "name": "Kwame Asante", "role": "Administrator", "permissions": ["members.view", "…"],
            "organisation": { "name": "…", "branding": { "logo_url": "…", "brand_color": "#0e7490", "palette": { "50": "#…", "…": "…" } } } }
}

Send the token on every request:

Authorization: Bearer ebp_4Fq…
Accept: application/json

• Permissions: a token can do exactly what its user's role allows, nothing more. Changing the role changes what the token can do.
• Login limits: 5 failed sign-ins per email per 5 minutes. Authenticated calls are limited to 120 per minute per user.
• When a token stops working: revoking it (DELETE /auth/token, or Revoke on the profile page), when it expires, when the user is deactivated or the organisation is suspended, and when an administrator resets the user's password.
• Temporary passwords: a user who still has a temporary password must sign in to the portal and choose a new password before the API will accept them (403).
• Only a hash is stored. EBITS staff cannot read your token.

EBITS platform users

EBITS (super-admin) accounts are not part of any client. To work inside a client, add the header X-Organisation: <organisation id or slug>. The role must include Open client portals.

2. Endpoints

Members

The Member ID (member_no) is the member's own staff or membership number, as imported. It must be unique within the organisation. Spaces are removed and letters are upper-cased ("ghs 4471" becomes "GHS4471").

POST /api/v1/members
{ "member_no": "GHS4471", "first_name": "Ama", "last_name": "Serwaa", "phone": "0244555666",
  "email": "ama@example.com", "gender": "female", "date_of_birth": "1988-04-12", "group_id": 3 }

• Required: member_no, first_name, phone (a Ghana number).
• Optional: last_name, email, gender (male/female), date_of_birth, joined_at, status (active/inactive/suspended), group_id, location, custom_fields (object).

Payments

POST /api/v1/payments
{ "member_no": "GHS4471", "payment_type_code": "DUES", "amount": 50, "channel": "cash" }

• member_id or member_no
• payment_type_id or payment_type_code
• channel: cash or bank are recorded as paid immediately; momo sends a prompt to phone (default: the member's phone) and stays pending until Hubtel confirms it.
• For per-item types (e.g. T-shirts), send quantity; the amount is worked out for you.
• Eligibility, minimum/fixed amounts and limits are checked exactly as in the portal. Breaking a rule returns 422 with a message.

3. Responses and errors

Lists are paginated:

{ "data": [ … ], "links": { "next": "…" }, "meta": { "current_page": 1, "per_page": 25, "total": 342 } }

Every error has a message. Validation errors also have errors: { field: ["…"] }.

4. Quick test with curl

TOKEN=$(curl -s -X POST https://pay.example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"treasurer@ktwa.org","password":"password","device_name":"curl"}' | jq -r .token)

curl -s https://pay.example.com/api/v1/dashboard -H "Authorization: Bearer $TOKEN" | jq
curl -s "https://pay.example.com/api/v1/members?search=ama" -H "Authorization: Bearer $TOKEN" | jq

The machine-readable description is in docs/openapi.yaml. Import it into Postman, Insomnia or Swagger UI.