API Documentation

Use the GOVPAY APIs to create payable applications, redirect citizens to Hosted Checkout, capture payments, and record counter (POS) collections. Responses are JSON. Amounts for eGov applications are in Cayman Islands Dollars (KYD / CI$).

Collection channels

Citizen session (cookie)

Citizen portal and Hosted Checkout capture use an HTTP-only session cookie (`govpay_session`) issued after login or registration. Send it automatically from the browser; do not expose it to client-side JavaScript.

API keys (server-to-server)

For agency backends creating applications or recording POS payments, authenticate with Basic Auth using your Key Id and Key Secret. Credentials are issued for your integration and used only over the API — there is no Console settings UI for API keys.

curl https://govpayv2.netcluesdemo.com/api/egov/applications \
  -u KEY_ID:KEY_SECRET \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Roles

1. 1

   Create an application

   POST /api/egov/applications with applicant and licence fields. GOVPAY calculates the KYD fee and returns an application id plus hostedPayUrl.

2. 2

   Redirect to Hosted Checkout

   Send the citizen to /pay/hosted/{applicationId}. They sign in, choose a card (or other method), and confirm.

3. 3

   Confirm status

   GET /api/egov/applications/{id} until status is paid, or listen for the application.paid webhook.

# 1) Create application
curl -X POST https://govpayv2.netcluesdemo.com/api/egov/applications \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jordan Ebanks",
    "dateOfBirth": "1990-04-12",
    "nationality": "Caymanian",
    "citizenship": "caymanian",
    "email": "jordan@email.ky",
    "phone": "+1-345-555-0100",
    "addressLine1": "12 Harbour Dr",
    "district": "George Town",
    "licenceNumber": "DL-884201",
    "licenceClass": "B",
    "licenceGroup": "0-3",
    "termYears": 5,
    "expiryDate": "2026-08-01",
    "signedName": "Jordan Ebanks"
  }'

# Response includes hostedPayUrl → open in browser
# 2) Citizen completes Hosted Checkout
# 3) Poll GET /api/egov/applications/{id}

Successful captures write to the admin payment ledger with channel web or pos and type cash, card, or bank transfer. Citizen dashboards show matching receipts under Payments.

• Use a unique payment reference per capture for reconciliation.
• Treat paid as terminal for that application id.
• Refunds are processed via support policy — not a public refund API yet.

curl -X POST https://govpayv2.netcluesdemo.com/api/egov/applications \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jordan Ebanks",
    "dateOfBirth": "1990-04-12",
    "nationality": "Caymanian",
    "citizenship": "caymanian",
    "email": "jordan@email.ky",
    "phone": "+1-345-555-0100",
    "addressLine1": "12 Harbour Dr",
    "district": "George Town",
    "licenceNumber": "DL-884201",
    "licenceClass": "B",
    "licenceGroup": "0-3",
    "termYears": 5,
    "expiryDate": "2026-08-01",
    "signedName": "Jordan Ebanks"
  }'

Response (201)

{
  "application": {
    "id": "app_01J8…",
    "service": "driving_licence_renewal",
    "status": "pending_payment",
    "fullName": "Jordan Ebanks",
    "amountCid": 75,
    "currency": "KYD",
    "createdAt": "2026-07-30T12:00:00.000Z"
  },
  "hostedPayUrl": "/pay/hosted/app_01J8…"
}

After creating an application, redirect the citizen to the returned hostedPayUrl, or open the same UI in-place with Standard Checkout (checkout.js). Hosted Checkout handles authentication, saved cards, confirmation, and receipt messaging. You only need to create the application and verify final status.

1. 1

   Create

   Your server calls POST /api/egov/applications.

2. 2

   Open

   Redirect to hostedPayUrl, or open via checkout.js (see Standard Checkout).

3. 3

   Citizen pays

   Login → select method → confirm. Capture runs server-side.

4. 4

   Reconcile

   Poll GET application or consume application.paid webhook.

Include checkout.js on any page. Mount a branded Pay with GOVPAY button, or call GovPay.Checkout to open the same hosted modal in an iframe overlay. Your backend still creates the application; the browser only receives the application id.

<script src="https://govpayv2.netcluesdemo.com/checkout.js"></script>
<div id="govpay"></div>
<script>
  GovPay.mountPayButton("#govpay", {
    createApplication: async function () {
      var res = await fetch("/api/your-create-session", { method: "POST" });
      var data = await res.json();
      return { applicationId: data.applicationId };
    },
    handler: function (response) {
      console.log("Payment success", response);
    },
    onDismiss: function () {
      console.log("Citizen closed checkout");
    }
  });
</script>

1. 1

   Load script

   Add <script src="https://govpayv2.netcluesdemo.com/checkout.js"></script> (or Next.js <Script src="/checkout.js" />).

2. 2

   Create application

   Server-side POST /api/egov/applications — never put secrets in the browser.

3. 3

   Open modal

   Pass applicationId into GovPay.Checkout or mountPayButton. The script iframes /pay/hosted/{id}?embed=1.

4. 4

   Handle result

   handler() receives paid events via postMessage; always re-verify status on your server.

POS payments create admin ledger rows with channel `pos` and a payment type of `cash`, `card`, or `banktransfer`. Operators work in shifts with opening and closing cash counts.

• Use a unique `reference` per payment (idempotent upsert by reference).
• Include terminalId and operatorName for audit trails.
• Cash remains POS-only — do not send cash on web captures.

Subscription products are configured per agency (utilities, renewals). Cancellation is immediate for the citizen portal; settle any outstanding invoices per agency policy.

Register an HTTPS callback URL via the API. GOVPAY POSTs signed JSON events when ledger state changes. Respond with HTTP 2xx within 5 seconds; failures retry with exponential backoff.

1. 1

   Register URL

   Call the webhooks API with your integration credentials to register your HTTPS endpoint.

2. 2

   Verify signature

   Validate X-GovPay-Signature using your webhook secret.

3. 3

   Idempotent handling

   Events may retry — key off event.id when updating your systems.

• Validate the HMAC signature in X-GovPay-Signature (hex digest of raw body with your webhook secret).
• Optionally restrict inbound traffic to known GOVPAY webhook IP ranges.
• Use HTTPS only — plain HTTP endpoints are rejected.
• Rotate webhook secrets via the API if an endpoint is compromised.

import crypto from "crypto";

function verifyGovPaySignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

POS payments upsert by `reference`. Re-posting the same reference updates the same ledger row instead of creating duplicates. For eGov captures, once an application is `paid`, subsequent capture calls return the paid application without charging again.

• Generate references on your server before calling POS APIs.
• Store application ids before redirecting to Hosted Checkout.
• Webhook handlers must be idempotent on event.id.