REST API v1

AFA Portal API Documentation

Programmatic access to the AFA registration system. Authenticate with an API key to check balances, submit registrations, and query statuses.

https://afa.data4ghana.com/wp-json/afa/v1 Auth Required JSON

Authentication

All API requests require a valid API key. Generate one from your API Keys dashboard. Pass it in the request header or as a query parameter.

Recommended — HTTP Header:

# Add this header to every request
X-AFA-API-Key: afa_your_key_here

Alternative — Query Parameter:

https://afa.data4ghana.com/wp-json/afa/v1/balance?api_key=afa_your_key_here

Keys with Read Only permission can access GET endpoints. The POST /register endpoint requires a key with Read + Write permission.

Errors & Status Codes

All responses return JSON. Errors include a success: false flag and an error object.

Error Response Schema

{
  "success": false,
  "error": {
    "code":    "invalid_api_key",
    "message": "Invalid or revoked API key."
  }
}

200OK — request successful

201Created — registration submitted

401Unauthorized — missing or invalid API key

402Payment Required — insufficient wallet balance

403Forbidden — key lacks write permission, or wrong user

404Not Found — registration or resource does not exist

409Conflict — duplicate registration (same ID number)

422Unprocessable — validation failed

429Too Many Requests — registration already in progress

500Server Error — internal failure

503Service Unavailable — TeraWallet plugin not active

GET /balance Get wallet balance Read ▶

Returns your current TeraWallet balance, the registration fee for your role, and whether you have enough to register.

Request Example

curl -X GET "https://afa.data4ghana.com/wp-json/afa/v1/balance" \
  -H "X-AFA-API-Key: afa_your_key_here"

Response

{
  "success": true,
  "message": "OK",
  "data": {
    "balance":          50.00,
    "currency":         "GHS",
    "formatted":        "₵50.00",
    "registration_fee": 7.00,
    "can_register":     true,
    "shortfall":        0
  }
}

GET /registrations List your registrations Read ▶

Returns a paginated list of all AFA registrations submitted by the authenticated user.

Parameters

Name	Type	Required	Description
status	string	optional	Filter by status: pending, processing, completed, cancelled, refunded
limit	integer	optional	Results per page (1–50, default: 20)
page	integer	optional	Page number (default: 1)

Request Example

curl -X GET "https://afa.data4ghana.com/wp-json/afa/v1/registrations?status=pending&page=1" \
  -H "X-AFA-API-Key: afa_your_key_here"

Response

{
  "success": true,
  "data": {
    "registrations": [
      {
        "order_id":  1024,
        "status":   "pending",
        "fee":      7.00,
        "currency": "GHS",
        "full_name":"Kofi Mensah",
        "phone":    "0241234567",
        "id_type":  "ghana_card",
        "id_number":"GHA-123456789-0",
        "dob":      "1990-05-12",
        "created_at":"2026-03-10T08:00:00+00:00"
      }
    ],
    "pagination": {
      "page": 1, "limit": 20,
      "total": 3, "total_pages": 1
    }
  }
}

GET /registrations/{id} Get a single registration Read ▶

Returns full details of a single registration by order ID. You can only access your own registrations.

Parameters

Name	Type	Required	Description
{id}	integer	required	The WooCommerce order ID of the registration

Request Example

curl -X GET "https://afa.data4ghana.com/wp-json/afa/v1/registrations/1024" \
  -H "X-AFA-API-Key: afa_your_key_here"

Response

{
  "success": true,
  "data": {
    "order_id":   1024,
    "status":    "approved",
    "fee":       7.00,
    "currency":  "GHS",
    "full_name": "Kofi Mensah",
    "phone":     "0241234567",
    "id_type":   "ghana_card",
    "id_number": "GHA-123456789-0",
    "dob":       "1990-05-12",
    "created_at":"2026-03-10T08:00:00+00:00"
  }
}

GET /registrations/status/{id} Check registration status Read ▶

Lightweight endpoint — returns only the current status of a registration. Useful for polling.

Parameters

Name	Type	Required	Description
{id}	integer	required	The WooCommerce order ID of the registration

Request Example

curl -X GET "https://afa.data4ghana.com/wp-json/afa/v1/registrations/status/1024" \
  -H "X-AFA-API-Key: afa_your_key_here"

Response

{
  "success":    true,
  "data": {
    "order_id":   1024,
    "status":    "approved",
    "updated_at":"2026-03-10T10:30:00+00:00"
  }
}

POST /register Submit a new registration Auth Write ▶

Submits a new AFA registration. Debits the registration fee from your TeraWallet and creates a WooCommerce order. Requires a key with Read + Write permission. Duplicate ID numbers are rejected.

Parameters

Name	Type	Required	Description
full_name	string	required	Applicant's full name
phone	string	required	10-digit Ghana phone: 0XXXXXXXXX
id_type	string	required	Must be: ghana_card
id_number	string	required	Format: GHA-000000000-0
dob	string	required	Date of birth: YYYY-MM-DD (must be 18+)

Request Example

curl -X POST "https://afa.data4ghana.com/wp-json/afa/v1/register" \
  -H "X-AFA-API-Key: afa_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name":  "Kofi Mensah",
    "phone":      "0241234567",
    "id_type":    "ghana_card",
    "id_number":  "GHA-123456789-0",
    "dob":        "1990-05-12"
  }'

Response

{
  "success": true,
  "message": "Registration submitted successfully.",
  "data": {
    "order_id":    1025,
    "status":     "pending",
    "fee_charged": 7.00,
    "new_balance": 43.00,
    "currency":   "GHS",
    "submitted_at":"2026-03-10T08:30:00+00:00"
  }
}