Accept Payments

Integrate Trustly Scan and Pay

View as Markdown

Trustly Scan and Pay powers real-time bank transfers in physical gaming environments. It utilizes Trustly Open Banking technology to provide instant funding directly from a customer bank account to a casino Electronic Gaming Machine (EGM). The casino Cashless Wagering System (CWS), a component of the Casino Management System (CMS) or bridging technology, manages funds and governs the credit process.

Prerequisites

To support Trustly Scan and Pay transactions, the CMS or bridging technology must support specific functional capabilities. Additionally, you must provide API specifications to the Trustly integration team to enable the configuration of the Trustly Payment Agent Service (TPAS).

System capabilities

Your system must support the following functionality:

  • QR Code Acquisition and Display: The system must be capable of requesting and displaying dynamic, time-sensitive QR codes on Electronic Gaming Machines (EGMs).
  • Credit Application: The system must apply funds to the EGM credit meter immediately upon request from the TPAS and return the transaction status.
  • Limit Enforcement: The system must create, modify, enforce, and delete debit instrument limits in compliance with applicable gaming regulations (such as Nevada Technical Standard 3.150). It must use the UBAI provided by the TPAS for limit tracking.

Documentation

You must provide comprehensive documentation for the following APIs to allow Trustly to configure the TPAS connection to your CMS or bridging technology:

  • Funding API: Specifications must include full endpoint paths, JSON request and response schemas, error codes, timeout settings, IP whitelisting requirements, and authentication requirements (including token refresh procedures and Time-To-Live).
  • Daily Limits API: Specifications must detail endpoints for getting, setting, updating, and deleting limits. It must also include logic for validating limits against the UBAI and specific error codes for scenarios such as Limit Reached.

Integration data flow

The following diagram illustrates the technical communication flow between the EGM, the CMS (or bridging technology), and the TPAS. This process separates the physical QR code acquisition (Scan) from the backend funding authorization (Pay).

StepActionDescription
AInitiateThe player initiates a funding request on the EGM.
BRequestThe EGM requests a QR code from the CMS using the Asset ID.
CCallThe CMS calls the Trustly API POST /qrcode/token endpoint.
DReturnTrustly returns the payment token and QR image URL to the CMS.
EPassThe CMS passes the QR image data to the EGM.
FDisplayThe EGM renders and displays the QR code on the screen.
GScanThe player scans the QR code using a mobile device.
HAuthorizeThe player completes authentication and funding on the mobile device.
INotifyTrustly notifies the CMS through the TPAS that the funding succeeded.
JValidateThe CMS validates the transaction against UBAI limits.
KCreditThe CMS credits the EGM meter and unlocks play.

Terminology

The following table lists the core terminology and acronyms used in a Trustly Scan and Pay integration.

TermDefinition
Bridging technologyAn intermediary application or software layer that translates data between the TPAS and casino systems.
Cashless Wagering System (CWS)The component or system responsible for electronic funds transfers to and from gaming devices and managing player account balances.
Casino Management System (CMS)The central system that manages all casino operations, including accounting, player tracking, and reporting. The CWS is typically a component of the CMS.
Debit Instrument TokenA unique identifier from the TPAS that represents the player bank account. The CMS uses this token to enforce regulatory spending limits.
Electronic Gaming Machine (EGM)Any slot machine, video poker machine, or other electronic terminal where a player places a wager.
Electronic Table Game (ETG)A multi-player electronic terminal that allows players to wager on a virtual or live table game. Examples include roulette or blackjack.
Trustly Payment Agent Service (TPAS)The application or platform provided by Trustly that handles the Open Banking connection, fund transfer, and communication with the CMS or CWS.
Trustly MicrositeThe secure interface where the player selects the transfer amount and authorizes the payment through their bank.
Unique Bank Account Identifier (UBAI)An encrypted ID (up to 40 characters) generated by Trustly for each Debit Instrument (the unique ID for the bank account). It is sent with every funding request and must be used by the CMS to validate transaction limits.

Implementation checklist

Use this checklist to confirm that all required tasks are complete for your Trustly Scan and Pay integration.

  • Obtain sandbox credentials from Trustly. Credentials include accessId, merchantID, and accessKey.
  • Verify that sandbox Trustly API endpoints are reachable from the CMS or bridging environment.
  • Add Trustly IP ranges to your CMS gateway allow lists if required.
  • Provide Funding API documentation including endpoints, request and response schemas, authentication rules, timeout rules, and error codes.
  • Provide Daily Limits API documentation including endpoints for limit creation, retrieval, update, and deletion.
  • Define and provide to Trustly your API retry requirements and any identifier expiration rules.
  • Implement functionality to request and display dynamic QR codes on EGMs.
  • Implement QR code rotation logic based on expiration timestamp.
  • Implement funding application logic so the CMS or bridging technology can update the EGM credit meter in real time.
  • Enforce player and transaction limits using the Unique Bank Account Identifier.
  • Handle failure modes such as timeouts, invalid requests, and limit validation failures.
  • Call the QR Code endpoint POST https://cashlesscasino.sandbox.trustly.one/auth-service/api/oauth2/qrcode/token using Basic Authentication credentials.
  • Parse url, token, and expiresAt from the response.
  • Convert the url value into a QR code image for EGM display.
  • Refresh the QR code approximately ten seconds before expiration.

Roles and responsibilities

A successful Scan and Pay integration requires coordination between the CMS partner and Trustly. The following table details the specific ownership of tasks throughout the integration process.

ResponsibilityCMS PartnerTrustly
API specification: Provide comprehensive documentation for the Funding API and Daily Limits API, including endpoints, authentication methods, and error codes.Primary
TPAS configuration: Develop and configure the TPAS to communicate with the CMS APIs based on the provided specifications.Primary
Credential management: Generate and provide the Basic Auth credentials (accessId and accessKey) required to access the QR Code API.Primary
QR code integration: Integrate with the Trustly QR Code API to retrieve payment tokens and image URLs for specific Electronic Gaming Machine (EGM) assets.Primary
QR code display and rotation: Implement logic on the EGM to render the QR code image and automatically rotate it ten seconds before the expiresAt timestamp to prevent reuse.Primary
Limit enforcement: Use the UBAI provided by Trustly to validate transaction limits against player or casino settings before authorizing funds.Primary
End-to-end testing: Validate that the full flow from the QR scan to fund dispersal functions correctly in the test environment before the production launch.SupportPrimary

Security and compliance

Trustly Scan and Pay meets the strict security and regulatory requirements of the gaming industry.

  • PII isolation: The CMS or bridging technology does not process or store consumer Personally Identifiable Information (PII) during the funding flow. All banking authentication occurs directly between the user and their bank in the Trustly Microsite.
  • Encryption: All API communication must occur over HTTPS using TLS 1.2 or higher.
  • Tokenization: The UBAI allows the CMS to enforce limits without handling raw account numbers.
  • QR Code Security: Rotation logic prevents replay attacks by invalidating QR codes shortly after generation.

Generate payment QR codes

Once Trustly has configured the TPAS for your environment, you will integrate with the QR Code API. Your system calls this endpoint to retrieve the secure URL that generates the QR code image.

API endpoint

EnvironmentURL
Sandboxhttps://cashlesscasino.sandbox.trustly.one/auth-service/api/oauth2/qrcode/token
ProductionProvided during onboarding

Request

  • Method: POST
  • Content-Type: application/json
  • Authorization: Basic Auth

Trustly provides The Basic Auth credentials (accessId and accessKey).

Body parameters

ParameterTypeRequiredDescription
assetstringYesThe unique Asset ID of the EGM where the funding request originates.
merchantIdstringYesThe internal identifier provided by Trustly corresponding to the specific Casino property.
gameNamestringNoThe name of the game currently on the EGM. If provided, this renders in the Trustly Microsite header for the user.
idstringNoThe Player ID (if the user is carded or logged in).

Example request

$curl -X POST https://cashlesscasino.sandbox.trustly.one/auth-service/api/oauth2/qrcode/token \
>  -u "YOUR_ACCESS_ID:YOUR_ACCESS_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "asset": "EGM-Floor1-042",
>    "merchantId": "123456789",
>    "gameName": "Blackjack Video",
>    "id": "PLAYER_998877"
>  }'

Response

FieldTypeDescription
tokenstringThe encrypted payload for the Trustly Microsite.
expiresAtstringISO 8601 date-time string indicating when this specific token and QR code expires.
urlstringThe full URL for the Trustly Microsite, including the encoded token. This URL must be converted into the QR Code image.

Example response

1{
2  "token": "w5wDqkdsJ4Ggl+UAvauF/fFv...",
3  "expiresAt": "2025-01-01T17:00:00.0000",
4  "url": "https://cashlesscasino.sandbox.trustly.one/cashlesscasino-client?token=w5wDqkdsJ4Ggl..."
5}

Common error codes

CodeDescription
200OK. The QR code token was successfully generated.
400Bad Request. Missing required fields. For example, asset or merchantId.
401Unauthorized. Invalid Basic Auth credentials.
403Forbidden. The merchant ID provided is not authorized for this account.
500Internal Server Error. An error occurred on the Trustly side. Please retry the request.

EGM display implementation

The CMS is responsible for rendering the QR code on the EGM and managing its lifecycle.

QR code generation

  1. Extract the url field from the API response.
  2. Use a standard library to generate a QR Code image from the URL. The QR Code must meet the minimum size and contrast requirements to be easily scannable by standard mobile devices on the EGM display.

QR code rotation

To prevent replay attacks or the use of stale sessions, the QR code must auto-rotate before it expires.

  1. Store the expiresAt timestamp from the API response.
  2. Monitor the current time against this timestamp.
  3. Initiate a request for a new QR code 10 seconds before the current expiresAt time. This buffer accounts for network latency and the time it takes a user to scan the code and load the page.
  4. Replace the displayed image immediately upon receiving the new URL.

Test and validate

To allow Trustly to perform end-to-end (E2E) testing of the Trustly Scan and Pay integration, the CMS team must validate the following functionality:

  • QR Code generates and displays correctly on the EGM
  • The QR Code successfully opens the Trustly Microsite on a mobile device.
  • The QR Code automatically refreshes ~10 seconds before expiration without manual intervention.
  • Transactions respect the limits defined in the Daily Limits API. This is validated with the UBAI.
  • The EGM handles API timeouts or failures. For example, hiding the QR code or showing a Service Unavailable message.