Getting Started
Last updated: 2026-10-20
This guide takes an ECR integration through one complete payment in the Demo environment:
- Prepare credentials and a terminal.
- Link the terminal.
- Create a purchase.
- Poll until the transaction has a final result.
- 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:
texthttps://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:
httpAuthorization: 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:
bashcurl --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.
bashcurl --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:
bashcurl \ '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:
- Start after receiving HTTP
201and wait 2 seconds between normal polls. - Run only one polling loop for each
onlineAPIRefId. Do not poll the same transaction concurrently. - Continue while
transactionStatusis14(PENDING). - Stop on any status from
0to13and process that final result once. - 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.
- For HTTP
429, wait forRetry-Afterwhen supplied. Otherwise use exponential backoff with jitter. Use the same bounded backoff for retryable5xxand network failures.
javascriptconst 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
- Explore the Sandbox and its integration walkthrough.
- Review Error Handling.
- Complete the integration checklist.
- Use the Demo Swagger UI for the full schema.
For access or integration support, contact support@westpay.se.