The PSP Enrollment API lets a payment service provider retrieve primary caregiver enrollment records for households assigned to their organisation, then submit completed enrollment responses (payment card / ezwich details).

• 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: mark lpm_psp_enrollment_request as updated (requestStatusId = 2) and upsert into lpm_caregivers_psp

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 completed caregiver enrollment responses as a JSON array. Each item is validated and processed in order.

For each item the API:

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

Required item fields

Optional item fields (persisted on upsert)

Additional attributes are accepted, including (non-exhaustive): updateDate, primaryCaregiverId, primaryCaregiverOthernames, primaryCaregiverDateOfBirth, secondary caregiver fields, enrolmentDate, paymentCardType, paymentCardIssueDate, paymentCardOthernames, and isDuplicate.

Example request

curl -X PUT "https://YOUR_HOST/api/v1/psp_enrollment" \
  -H "Content-Type: application/json" \
  -H "token: YOUR_SESSION_TOKEN" \
  -d '[
  {
    "requestId": 391599,
    "householdUUID": "f65935be-536b-11f1-960f-7aaf00f2bedf",
    "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
    "updateDate": "2026-07-02T00:00:00.000Z",
        "enrolmentDate": "2026-05-12",
        "paymentCardType": "CARD",
        "paymentCardNumber": "GC178708643679180420",
        "primaryCaregiverId": 2294637,
        "paymentCardLastname": "AWUDU",
        "primaryCaregiverSex": "Male",
        "enrolmentReferenceId": "GH940601000013",
        "paymentCardFirstname": "ISSIFU",
        "paymentCardIssueDate": "2026-05-12T00:00:00.000Z",
        "primaryCaregiverUUID": "d7a14b02-536b-11f1-960f-7aaf00f2bedf",
        "secondaryCaregiverId": 0,
        "paymentCardExpiryDate": "2036-05-04T00:00:00.000Z",
        "paymentCardOthernames": "",
        "secondaryCaregiverSex": "",
        "secondaryCaregiverUUID": "",
        "primaryCaregiverLastname": "AWUDU",
        "primaryCaregiverFirstname": "ISSIFU",
        "primaryCaregiverOthernames": " ",
        "secondaryCaregiverLastname": "",
        "primaryCaregiverDateOfBirth": "1994-06-01T00:00:00.000Z",
        "primaryCaregiverPhoneNumber": "+233246032178",
        "secondaryCaregiverFirstname": "",
        "primaryCaregiverIsDuplicated": false,
        "secondaryCaregiverOthernames": "",
        "secondaryCaregiverDateOfBirth": null,
        "secondaryCaregiverPhoneNumber": "",
        "primaryCaregiverGhanaCardNumber": "GHA-729527365-4",
        "secondaryCaregiverGhanaCardNumber": ""
  }
]'

Response envelope

Per-item success fields

Example success response (HTTP 200)

{
  "successful": true,
  "message": "Caregiver enrollments saved.",
  "totalCount": 1,
  "successCount": 1,
  "failureCount": 0,
  "data": [
    {
      "successful": true,
      "index": 0,
      "householdUUID": "f65935be-536b-11f1-960f-7aaf00f2bedf",
      "requestId": 391599,
      "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
      "paymentCardNumber": "1022105822",
      "responseAction": "ENROLLED",
      "requestStatusId": 2,
      "caregiversPspId": 42,
      "caregiversPspUpserted": "inserted",
      "message": "Caregiver enrollment saved.",
      "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": "f65935be-536b-11f1-960f-7aaf00f2bedf",
      "requestId": 391599,
      "primaryCaregiverUUID": "b65f1776-536b-11f1-960f-7aaf00f2bedf",
      "paymentCardNumber": "1022105822",
      "responseAction": "ENROLLED",
      "requestStatusId": 2,
      "caregiversPspId": 42,
      "caregiversPspUpserted": "updated",
      "message": "Caregiver enrollment saved.",
      "requestRowsUpdated": 1,
      "status": 200
    },
    {
      "successful": false,
      "index": 1,
      "householdUUID": "UNKNOWN-UUID",
      "requestId": 999999,
      "message": "No enrollment request found for this householdUUID / requestId.",
      "status": 404
    }
  ]
}

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