Getting Started

Last updated: 2026-10-20

This guide takes an ECR integration through one complete payment in the Demo environment:

  1. Prepare credentials and a terminal.
  2. Link the terminal.
  3. Create a purchase.
  4. Poll until the transaction has a final result.
  5. Handle the result safely.

Complete the integration checklist before requesting production approval.

Before you begin

You need:

  • a Westpay merchant account with Online API access;
  • a Demo Ocp-Apim-Subscription-Key;
  • a Demo bearer access token;
  • a configured Westpay terminal and its terminalId;
  • the terminal's time-limited registration code; and
  • an HTTPS-capable server-side ECR integration.

Keep credentials in a secret store. Never embed them in the ECR user interface, source code, logs, or support screenshots. Demo and Production credentials are separate.

All examples use this Demo base URL:

text
https://demo-api.westpay.se/in-store/api/v1

See Environments before changing to Production.

Step 1 - Add the required headers

Send these headers on every request:

http
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <merchant-subscription-key>
Accept: application/json

Also send Content-Type: application/json when the request has a JSON body.

The ConnectionId header is only for the browser-based Sandbox simulators. Do not send it when using a physical terminal.

Step 2 - Link the terminal

Turn on the terminal and wait until it displays a registration code. Submit that code with the assigned terminal ID:

bash
curl --request POST \
  'https://demo-api.westpay.se/in-store/api/v1/terminal/link' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Ocp-Apim-Subscription-Key: <merchant-subscription-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "terminalId": "<terminal-id>",
    "registrationCode": "<registration-code>"
  }'

A successful link returns HTTP 200:

json
{
  "printerEnabled": true
}

Confirm that the terminal shows Connected. Store the terminalId as configuration; do not ask the cashier to enter it for every transaction.

See Link Terminal for the complete contract.

Step 3 - Create a purchase

Send a positive amount in major currency units, rounded to two decimal places. 752 is the ISO 4217 numeric code for SEK. Leave paymentMethod empty for a card payment.

bash
curl --request POST \
  'https://demo-api.westpay.se/in-store/api/v1/purchase' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Ocp-Apim-Subscription-Key: <merchant-subscription-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100.00,
    "currencyCode": 752,
    "terminalId": "<terminal-id>",
    "paymentMethod": ""
  }'

HTTP 201 means that the request was accepted for terminal processing. It does not mean that the payment was approved.

json
{
  "onlineAPIRefId": "23179040000954"
}

Persist onlineAPIRefId against the ECR sale before polling. It is the correlation key for status, cancellation, recovery, logs, and support.

Step 4 - Poll for the result

Call the status endpoint with the reference returned in Step 3:

bash
curl \
  'https://demo-api.westpay.se/in-store/api/v1/transaction/23179040000954/status' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Ocp-Apim-Subscription-Key: <merchant-subscription-key>'

Use this polling policy:

  1. Start after receiving HTTP 201 and wait 2 seconds between normal polls.
  2. Run only one polling loop for each onlineAPIRefId. Do not poll the same transaction concurrently.
  3. Continue while transactionStatus is 14 (PENDING).
  4. Stop on any status from 0 to 13 and process that final result once.
  5. Apply a local time limit to the cashier's waiting screen, but never convert a client timeout or network error into a decline. The financial result is still unknown until reconciled.
  6. For HTTP 429, wait for Retry-After when supplied. Otherwise use exponential backoff with jitter. Use the same bounded backoff for retryable 5xx and network failures.
javascript
const sleep = (milliseconds) =>
  new Promise(resolve => setTimeout(resolve, milliseconds));

function getRetryAfterMs(value) {
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);

  const retryAt = Date.parse(value);
  return Number.isNaN(retryAt) ? null : Math.max(0, retryAt - Date.now());
}

async function waitForTransaction(onlineAPIRefId, signal) {
  let retryDelayMs = 2000;

  while (!signal.aborted) {
    const response = await fetch(
      `${BASE_URL}/transaction/${onlineAPIRefId}/status`,
      { headers: API_HEADERS, signal }
    );

    if (response.status === 429 || response.status >= 500) {
      const retryAfterMs = getRetryAfterMs(response.headers.get('Retry-After'));
      const delayMs = retryAfterMs ?? retryDelayMs + Math.random() * 500;

      await sleep(delayMs);
      retryDelayMs = Math.min(retryDelayMs * 2, 30000);
      continue;
    }

    if (!response.ok) {
      throw new Error(`Status request failed with HTTP ${response.status}`);
    }

    const result = await response.json();
    if (result.transactionStatus !== 14) return result;

    retryDelayMs = 2000;
    await sleep(2000);
  }

  throw new Error('Polling stopped before a final result was confirmed');
}

The Online API documentation does not publish a single numeric quota that applies to every customer. Treat the policy above as ECR client guidance, not as a guaranteed service limit. Westpay may assign environment- or contract-specific limits. Your implementation must handle throttling and must not increase polling frequency to speed up terminal processing.

See Retrieve Payment Request for every status value and the recovery rules.

Step 5 - Handle the final result

At minimum:

  • 0 (APPROVED): complete the sale and store the returned transaction and receipt data.
  • 1–8, 10–12: show a clear, status-appropriate failure or cancellation message and return the ECR to a safe state.
  • 9 (TERMINAL_IS_OFFLINE): treat this as a recoverable operational result, not proof that no card transaction occurred. After the terminal reconnects, retrieve the last transaction and poll its reference to reconcile the authoritative result.
  • 13 (REVERSED): record the reversal and do not complete the original sale as approved.

Make financial completion idempotent: receiving or reading the same final result more than once must not create a second sale, refund, or receipt action.

Step 6 - Test the complete lifecycle

Before Production, implement and test:

  • terminal link and unlink;
  • purchase, cancellation, refund, and status retrieval;
  • every card-entry and cardholder-verification method in your scope;
  • terminal and network interruption recovery;
  • merchant and cardholder receipts;
  • reporting and reconciliation; and
  • every optional feature you expose, such as reversal, tips, loyalty, local schemes, or terminal printing.

Use the Online API integration checklist as the production-readiness requirement and evidence list.

Next steps

For access or integration support, contact support@westpay.se.