API Integration Flows

Welcome to the Alberta Payments API documentation. This portal explains the step-by-step flows required to authenticate clients and interact with the protected store and transaction endpoints.

Route Summary

Quick reference for every route exposed by routes/clients-api.php. Each row links to the detailed flow below.

1. Register Account

Before accessing any data, a client must register and specify which stores they need access to. Registration initiates a multi-step onboarding process.

Go to Registration Form →

Provide the following payload to create an account:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "1234567890",
  "store_id": [105, 106],
  "password": "SecurePassword123",
  "password_confirmation": "SecurePassword123"
}

Field rules

On validation failure, the API responds with HTTP 422 and a per-field error map:

{
  "success": false,
  "data": [],
  "message": "First error message.",
  "errors": {
    "phone": ["Phone number must be exactly 10 digits."],
    "store_id": ["Please select at least one store."]
  }
}

2. Create a JWT (Login)

JSON Web Tokens (JWTs) are a token format used for authentication with our data APIs. You must exchange your approved client credentials for a JWT, and tokens are scoped to a single store at a time.

Send the credentials to receive the token:

{
  "email": "jane@example.com",
  "password": "SecurePassword123"
}

A successful response includes the JWT, its expiry, and the store id the token is scoped to:

{
  "success": true,
  "data": {
    "client": { "id": 42, "name": "Jane Doe", "email": "jane@example.com" },
    "store_id": 105,
    "authorization": {
      "token": "eyJhbGciOiJIUzI1Ni...",
      "type": "bearer",
      "exp": 1735689600
    }
  },
  "message": "Token generated successfully"
}

Using the JWT to authenticate

In order to authenticate with the API, provide the JWT as a Bearer token in the Authorization header for all subsequent requests.

Authorization: Bearer eyJhbGciOiJIUzI1Ni...

3. Logout

Invalidate the current JWT token. After logging out, the token can no longer be used for protected endpoints.

Requires Authorization: Bearer [JWT] header.

Forgot Password Flow

If a client loses their password, they must request a secure reset link. The system will dispatch a cryptographically signed URL to their email. The endpoint always returns the same generic success message regardless of whether the email is registered, to avoid leaking account existence.

Payload:

{
  "email": "jane@example.com"
}

Reset Password Flow

The user clicks the signed link in their email, which brings them to a web form. Submitting that form hits the reset endpoint. The signature query parameters (expires and signature) come from the email link and must be preserved.

Payload:

{
  "password": "NewSecurePassword456",
  "password_confirmation": "NewSecurePassword456"
}

Password rules are identical to the ones enforced on registration (minimum 8 characters, alphanumeric, must include at least one letter and one digit, must match the confirmation field).

Get Transactions

Fetch detailed transactional data for a specific store, terminal, and transaction type. Results are paginated via page and per_page query parameters.

Path parameters

Query parameters