API Reference

This document is intended for external system integrators who need to interact with the SportyWallet Worker service over HTTP.

• Base URL
• Authentication
• Rate Limiting
• Endpoints
  • GET /ping
    • Response
    • Example
  • GET /readcard
    • Response
    • Example
  • POST /writecard
    • Request
    • Request Body
    • Response
    • Example Request
    • Example - Success
    • Example - Missing API Key
    • Example - Invalid Value
• Error Reference

---

Base URL

The Worker service exposes a local HTTP endpoint:

Protocol	URL
HTTP	http://localhost:60000

---

Authentication

Requests to POST /writecard must include the following header:

Header	Value
X-Api-Key	Your assigned API key

If the header is missing or invalid, the Worker returns 401 Unauthorized.

---

Rate Limiting

The following endpoints are subject to a fixed-window rate limit:

• Max 5 requests per minute per client
• Excess requests receive an HTTP 429 Too Many Requests response

The /ping endpoint is not rate-limited.

---

Endpoints

GET /ping

A simple health-check endpoint. Use this to verify that the Worker service is running and reachable.

Rate limited: No
Auth required: No

Response

Status	Body	Description
200 OK	"pong"	Service is running

Example

# Response

HTTP/1.1 200 OK
Content-Type: application/json

"pong"

GET /readcard

Reads the ID of the card currently placed on the connected reader device.

Rate limited: Yes
Auth required: No

Response

Status	Body	Description
200 OK	{ "cardId": "..." }	The identifier of the detected card
429 Too Many Requests		Rate limit exceeded

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "cardId": "card_1234567890"
}

POST /writecard

Recharges the card currently placed on the reader with the specified amount of credits.

Rate limited: Yes
Auth required: Yes (X-Api-Key header)

Request

Component	Value
Method	POST
Path	/writecard
Headers	Content-Type: application/json, X-Api-Key: <your-api-key>
Body	JSON object with credits

Request Body

{
  "credits": 10.5
}

Field	Type	Required	Description
credits	number	Yes	Credits to write onto the card

Response

Status	Body	Description
200 OK	Operation result (object)	Recharge completed successfully
400 Bad Request	"Invalid credits value"	The request body is missing credits or it is null
400 Bad Request	"Missing customerId from auth flow"	The API key was validated but no customer identifier was resolved
401 Unauthorized	"Unauthorized: missing api key"	The X-Api-Key header was not provided
401 Unauthorized	"Unauthorized: invalid api key"	The provided API key is invalid
429 Too Many Requests		Rate limit exceeded
500 Internal Server Error	Error message	The card write operation failed

Example Request

POST /writecard HTTP/1.1
Host: localhost:60000
X-Api-Key: your-api-key
Content-Type: application/json

{
  "credits": 10.5
}

Example - Success

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Recharge completed",
  "credits": 10
}

Example - Missing API Key

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Unauthorized: missing api key

Example - Invalid Value

HTTP/1.1 400 Bad Request
Content-Type: text/plain

"Invalid credits value"

---

Error Reference

HTTP Status	Meaning
200 OK	Request succeeded
400 Bad Request	Invalid request payload or missing customer identifier
401 Unauthorized	Missing or invalid API key
429 Too Many Requests	Rate limit exceeded - wait before retrying
500 Internal Server Error	The write operation failed

---