The PSP Enrollment API lets a payment service provider retrieve primary caregiver enrollment records for households assigned to their organisation, then submit primary caregiver ezwich card numbers.

• Base path: /api/v1/psp_enrollment (alias /api/v1/psp-enrollment)
• Content type: application/json for PUT body
• GET filters: optional region_code, district_code, and community_code (match household location columns on lpm_households_selected_all)
• PUT target: ezwich and Ghana Card updates

Sign in with POST /api/v1/session to obtain a session token. Send that token on every request using one of these headers:

token: YOUR_SESSION_TOKEN
Authorization: Bearer YOUR_SESSION_TOKEN
x-access-token: YOUR_SESSION_TOKEN

Example login:

curl -X POST "https://YOUR_HOST/api/v1/session" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0XXXXXXXXX",
    "password": "YOUR_PASSWORD",
    "organisation_code": "GHIPSS"
  }'

Returns a paginated list of caregiver enrollment records for the authenticated PSP. Records require a named primary caregiver. Optional secondary caregiver fields are included when present. Each household returned is logged in the caregiver request audit table (LIST).

Query parameters

Location filters may be combined with AND. They match region_code / district_code / community_code on lpm_households_selected_all.

Example request

curl -X GET "https://YOUR_HOST/api/v1/psp_enrollment?offset=0&limit=100&region_code=02&district_code=02-03&community_code=02-03-006" \
  -H "token: YOUR_SESSION_TOKEN"

Example response

{
  "successful": true,
  "totalCount": 1250,
  "offset": 0,
  "limit": 100,
  "data": [
    {
      "communityCode": "02-03-006",
      "communityId": "412",
      "communityName": "Example Community",
      "districtCode": "02-03",
      "districtId": "88",
      "districtName": "Example District",
      "gpsLatitude": "6.92999836",
      "gpsLongitude": "-2.83813443",
      "householdCode": "03-BJSJ",
      "householdHeadName": "AUGUSTINA MAWUENA",
      "householdPhoneNumber": "0531122057",
      "householdUUID": "02-03-006-1740462725749-B@7fc4447",
      "householdUniqueCode": "03-02-03-006-000005",
      "primaryCaregiverDateOfBirth": "1989-01-01",
      "primaryCaregiverFirstname": "AUGUSTINA",
      "primaryCaregiverGhanaCardFirstname": "",
      "primaryCaregiverGhanaCardLastname": "",
      "primaryCaregiverGhanaCardNumber": "GHA-726422577-6",
      "primaryCaregiverLastname": "",
      "primaryCaregiverOthernames": "MAWUENA",
      "primaryCaregiverPhoneNumber": "0531122057",
      "primaryCaregiverSex": "Female",
      "primaryCaregiverUUID": "",
      "regionCode": "02",
      "regionId": "2",
      "regionName": "Example Region",
      "secondaryCaregiverDateOfBirth": "",
      "secondaryCaregiverFirstname": "",
      "secondaryCaregiverGhanaCardFirstname": "",
      "secondaryCaregiverGhanaCardLastname": "",
      "secondaryCaregiverGhanaCardNumber": "",
      "secondaryCaregiverId": "15",
      "secondaryCaregiverLastname": "",
      "secondaryCaregiverOthernames": "",
      "secondaryCaregiverPhoneNumber": "0244000000",
      "secondaryCaregiverSex": "",
      "secondaryCaregiverUUID": ""
    }
  ]
}

Response object keys are returned in alphabetical order. When is_special is yes on the household, that field is included.

Submit one or more primary caregiver ezwich card numbers as a JSON array. Each item is validated and processed in order. The household must belong to your PSP, and a prior GET must have created a LIST audit row for that household.

• Body must be a non-empty JSON array (1–500 items).
• Overall HTTP status: 200 all ok, 207 partial, 400 none saved / invalid body.

Item fields

Example request

curl -X PUT "https://YOUR_HOST/api/v1/psp_enrollment" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_SESSION_TOKEN" \
  -d '[
  {
    "householdUUID": "CE248F2C-5FDC-4FDD-98DB-67B7E4890BFA",
    "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
    "primaryCaregiverEzwichCardNumber": "1234567890"
  },
  {
    "householdUUID": "10-11-227-1740866980154-B@ad17cd0",
    "primaryCaregiverUUID": "852b5ffe-0486-41aa-883f-3ca0975dad39",
    "primaryCaregiverEzwichCardNumber": "0987654321"
  }
]'

Response envelope

Example success response (HTTP 200)

{
  "successful": true,
  "message": "Primary caregiver ezwich card numbers saved.",
  "totalCount": 2,
  "successCount": 2,
  "failureCount": 0,
  "data": [
    {
      "successful": true,
      "index": 0,
      "householdUUID": "CE248F2C-5FDC-4FDD-98DB-67B7E4890BFA",
      "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
      "primaryCaregiverEzwichCardNumber": "1234567890",
      "message": "Primary caregiver ezwich card number saved.",
      "affectedRows": 1,
      "requestRowsUpdated": 1,
      "status": 200
    },
    {
      "successful": true,
      "index": 1,
      "householdUUID": "10-11-227-1740866980154-B@ad17cd0",
      "primaryCaregiverUUID": "852b5ffe-0486-41aa-883f-3ca0975dad39",
      "primaryCaregiverEzwichCardNumber": "0987654321",
      "message": "Primary caregiver ezwich card number saved.",
      "affectedRows": 1,
      "requestRowsUpdated": 1,
      "status": 200
    }
  ]
}

Example partial failure (HTTP 207)

{
  "successful": false,
  "message": "Completed with some failures.",
  "totalCount": 2,
  "successCount": 1,
  "failureCount": 1,
  "data": [
    {
      "successful": true,
      "index": 0,
      "householdUUID": "CE248F2C-5FDC-4FDD-98DB-67B7E4890BFA",
      "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
      "primaryCaregiverEzwichCardNumber": "1234567890",
      "message": "Primary caregiver ezwich card number saved.",
      "affectedRows": 1,
      "requestRowsUpdated": 1,
      "status": 200
    },
    {
      "successful": false,
      "index": 1,
      "householdUUID": "UNKNOWN-UUID",
      "message": "Household not found for this payment service provider.",
      "status": 404
    }
  ]
}

Each object in the GET data array uses these fields. Empty strings are returned when a value is unavailable.