FAQ

Last updated: 2026-03-22

Frequently Asked Questions

Common questions from ECR developers integrating with the Westpay Online API.

1 Is the Online API a server-to-server solution?

Yes. The Online API is a server-to-server solution. All requests originate from your ECR backend and travel over HTTPS directly to the Westpay API gateway — no browser, no end-user client, no SDK on the terminal side is involved in the request path.

This means your integration must run from a trusted back-end process that securely holds:

A short-lived Bearer token (JWT) issued by the identity provider
A subscription key (Ocp-Apim-Subscription-Key) issued per merchant account

Never expose either credential in a client-side application or POS UI.

2 Do I need to poll for the payment result, or will the API push it to me?

The Online API uses a push-based model via SignalR (WebSocket). Your POS Terminal app connects to the SignalR Hub and receives a real-time notification the moment the cardholder completes or declines the transaction — no polling required.

As a safety net, the Retrieve Payment Request endpoint is always available. We strongly recommend:

Persisting the onlineAPIRefId returned when you create a payment request
Falling back to a polling call if the WebSocket connection drops unexpectedly

3 What happens if our server loses the connection mid-transaction?

The terminal continues processing independently — a dropped connection on your side does not cancel or interrupt the cardholder's transaction.

To recover the result:

Call Retrieve Payment Request using the onlineAPIRefId you stored at creation time
Use the returned status (Approved, Declined, Cancelled, etc.) to drive your ECR logic

Always store the onlineAPIRefId immediately and durably after a successful create call — it is your single recovery handle.

4 Can a single merchant subscription manage multiple terminals simultaneously?

Yes. One subscription key can target any terminal that belongs to the associated merchant account. Each request identifies its destination via the Terminal ID (TID), so you can run parallel sessions across different terminals from the same backend service.

The key constraint is one active payment request per terminal at a time. Sending a second request to a terminal that is already busy returns a conflict error. Your ECR should track per-terminal state and queue or reject new requests accordingly.

5 Can we use a single long-lived token, or must we refresh credentials regularly?

Authentication uses two separate credentials with different lifetimes:

Credential	Header	Lifetime	Notes
Bearer token (JWT)	`Authorization`	Short-lived	Must be refreshed before expiry
Subscription key	`Ocp-Apim-Subscription-Key`	Stable	Rotate only when compromised

Long-lived Bearer tokens are not supported for security reasons. We recommend building a token-refresh routine into your ECR backend that proactively obtains a new JWT before the current one expires — rather than waiting for a 401 response mid-transaction.

See Getting Started for the full authentication flow.

6 We went live with separate credentials per merchant. How do we migrate to a single shared set for all future customers?

The TID in each request already identifies the owning merchant, so per-merchant credentials are not required by design. Migrating is straightforward:

Contact Westpay to provision a single shared subscription key covering all your merchant accounts
For each live merchant — swap to the new key, verify a test transaction, then revoke the old key
All new merchants onboard automatically under the shared credentials going forward

Keep old keys active until production traffic is confirmed on the new key before revoking them.