This documentation details the API for topping up student bus cards, including environment endpoints, security, and examples of successful and error payloads.

Authentication requires a Client-Key in the header and a request body that is the HMAC-SHA256 signature of the transaction payload.

The entire request body is a JSON object with a single field, data, which is the signature.

1. Construct Details Object: Build the JSON object with card_number, amount, currency, and optional billing_details.
2. Canonicalize: Serialize this object into a JSON string, ensuring alphabetical key order and no whitespace.
3. Sign: Calculate the HMAC-SHA256 signature of the canonical string using your Secret Key.

This is the body sent to the API, where the data value is the signature.

{
  "data": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2" 
}

A successful transaction returns the final details.

{
  "status": "success",
  "message": "Bus card top-up initiated successfully.",
  "transaction_id": "TXN987654321",
  "card_number": "BC1234567890",
  "amount": 50.00,
  "currency": "JMD"
}

Errors return a standard JSON object containing a brief status, a specific error code, and a descriptive message.

{
  "status": "error",
  "code": "INVALID_SIGNATURE",
  "message": "The signature provided in the 'data' field is invalid or could not be verified with the client's secret key."
}

{
  "status": "error",
  "code": "CARD_NUMBER_INVALID",
  "message": "The card number extracted from the signed payload is in an incorrect format."
}