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 paginated sales transactions for a specific store and terminal. Each page returns up to per_page unique sale records, with each sale's line items nested inside an items array. Data is sourced from trn_sales joined with trn_salesdetail, ordered newest first.

Path parameters

Query parameters

Example request

GET /v1/clients/stores/105/terminal/1/transactions/transaction?page=1&per_page=10
Authorization: Bearer eyJhbGciOiJIUzI1Ni...

Success response

HTTP 200. The top-level data object contains standard Laravel pagination metadata alongside a data array where each element represents one sale and its line items.

{
    "success": true,
    "data": {
        "current_page": 1,
        "data": [
            {
                "terminal_id": "101",
                "sales_id": 1812231011,
                "item_code": "23",
                "item_name": "Instant Redeem",
                "unit_cost": "0.0000",
                "unit_price": "0.01",
                "quantity_sold": "-1.00",
                "total_cost": "0.00",
                "total_price": "-0.01",
                "transaction_type": "Void",
                "transaction_date": "2018-12-23",
                "transaction_time": "18:57:54"
            },
            {
                "terminal_id": "101",
                "sales_id": 1812231012,
                "item_code": "23",
                "item_name": "Instant Redeem",
                "unit_cost": "0.0000",
                "unit_price": "0.01",
                "quantity_sold": "-1.00",
                "total_cost": "0.00",
                "total_price": "-0.01",
                "transaction_type": "Void",
                "transaction_date": "2018-12-23",
                "transaction_time": "18:59:14"
            },
            {
                "terminal_id": "101",
                "sales_id": 1812231014,
                "item_code": "23",
                "item_name": "Instant Redeem",
                "unit_cost": "0.0000",
                "unit_price": "0.01",
                "quantity_sold": "-1.00",
                "total_cost": "0.00",
                "total_price": "-0.01",
                "transaction_type": "Void",
                "transaction_date": "2018-12-23",
                "transaction_time": "20:12:57"
            },
            {
                "terminal_id": "101",
                "sales_id": 1812231015,
                "item_code": "2",
                "item_name": "Taxable Item",
                "unit_cost": "0.0000",
                "unit_price": "0.04",
                "quantity_sold": "1.00",
                "total_cost": "0.00",
                "total_price": "0.04",
                "transaction_type": "Void",
                "transaction_date": "2018-12-23",
                "transaction_time": "21:09:02"
            },
            {
                "terminal_id": "101",
                "sales_id": 1812231017,
                "item_code": "2",
                "item_name": "Taxable Item",
                "unit_cost": "0.0000",
                "unit_price": "0.01",
                "quantity_sold": "1.00",
                "total_cost": "0.00",
                "total_price": "0.01",
                "transaction_type": "Void",
                "transaction_date": "2018-12-23",
                "transaction_time": "21:55:07"
            }
        ],
        "from": 1,
        "last_page": 12,
        "per_page": 5,
        "to": 5,
        "total": 60
    },
    "message": "Transaction details retrieved successfully."
}

Error responses