> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For full documentation content, see https://amer.developers.trustly.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Integrate Trustly Scan and Pay 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. ### 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). ```mermaid %%{ init: { 'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff', 'primaryTextColor': '#000000', 'primaryBorderColor': '#000000', 'lineColor': '#000000', 'signalColor': '#000000', 'signalTextColor': '#000000', 'noteBkgColor': '#f4f4f4', 'noteTextColor': '#000000', 'noteBorderColor': '#000000', 'actorBkg': '#ffffff', 'actorBorder': '#000000', 'actorTextColor': '#000000' } } }%% sequenceDiagram participant Player participant EGM participant CMS as CMS / Bridge participant Trustly as TPAS Note over Player, CMS: Phase 1: The Scan (QR Acquisition) Player->>EGM: A EGM->>CMS: B CMS->>Trustly: C Trustly-->>CMS: D CMS-->>EGM: E Note right of EGM: F Player->>EGM: G Note over Player, Trustly: Phase 2: The Pay (Authorization) Note over Player, Trustly: H Trustly->>CMS: I Note right of CMS: J CMS->>EGM: K ``` | Step | Action | Description | | :---: | :------------ | :-------------------------------------------------------------------- | | **A** | **Initiate** | The player initiates a funding request on the EGM. | | **B** | **Request** | The EGM requests a QR code from the CMS using the Asset ID. | | **C** | **Call** | The CMS calls the Trustly API `POST /qrcode/token` endpoint. | | **D** | **Return** | Trustly returns the payment token and QR image URL to the CMS. | | **E** | **Pass** | The CMS passes the QR image data to the EGM. | | **F** | **Display** | The EGM renders and displays the QR code on the screen. | | **G** | **Scan** | The player scans the QR code using a mobile device. | | **H** | **Authorize** | The player completes authentication and funding on the mobile device. | | **I** | **Notify** | Trustly notifies the CMS through the TPAS that the funding succeeded. | | **J** | **Validate** | The CMS validates the transaction against UBAI limits. | | **K** | **Credit** | The 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. | Term | Definition | | :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Bridging technology | An 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 Token | A 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 Microsite | The 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. | ### Integrate Trustly Scan and Pay Use the information provided here to integrate a CMS or bridging technology with Trustly Scan and Pay. This allows players to fund gaming sessions using QR codes displayed on EGMs. #### Implementation checklist Use this checklist to confirm that all required tasks are complete for your Trustly Scan and Pay integration. #### Environment setup ([Prerequisites](#prerequisites)) * [ ] 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. #### Required API documentation ([Documentation in Prerequisites](#prerequisites)) * [ ] Provide Funding API documentation including endpoints, request and response schemas, authentication rules, timeout rules, and error codes to your assigned Trustly Product Manager. * [ ] Provide Daily Limits API documentation including endpoints for limit creation, retrieval, update, and deletion to your assigned Trustly Product Manager. Document limit validation using the Unique Bank Account Identifier. * [ ] Define and provide to Trustly your API retry requirements and any identifier expiration rules for all of your API endpoints. #### Core system capabilities ([System capabilities](#system-capabilities)) * [ ] 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. #### QR code API integration ([Generate payment QR codes](#generate-payment-qr-codes)) * [ ] 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. #### Funding flow handling ([Integration data flow](#integration-data-flow)) * [ ] Receive funding authorization requests from the TPAS. * [ ] Validate transaction limits using the Unique Bank Account Identifier. * [ ] Return success or failure results within the required window. * [ ] Apply credits to the EGM meter on success. * [ ] Return accurate error codes for any failure case. #### Security and compliance ([Security and compliance](#security-and-compliance)) * [ ] Confirm that all API communication uses TLS 1.2 or higher. * [ ] Confirm that QR code content expires and cannot be reused. #### End-to-end testing ([Test and validate](#test-and-validate)) * [ ] Confirm that QR codes render correctly on EGMs. * [ ] Confirm that QR codes open the Trustly Microsite on a mobile device. * [ ] Confirm that QR codes refresh approximately ten seconds before expiration. * [ ] Confirm that limits are validated correctly by the Daily Limits API. * [ ] Confirm that the EGM handles timeout and service failure conditions. * [ ] Complete end-to-end testing of the certification test cases with the Trustly implementation team in the sandbox environment. #### 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. | Responsibility | CMS Partner | Trustly | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: | :---------: | | **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. | **Support** | **Primary** | #### 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**. ##### 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 | Environment | URL | | :------------- | :-------------------------------------------------------------------------------- | | **Sandbox** | `https://cashlesscasino.sandbox.trustly.one/auth-service/api/oauth2/qrcode/token` | | **Production** | *Provided during onboarding* | ##### Request * **Method:** `POST` * **Content-Type:** `application/json` * **Authorization:** `Basic Auth` Trustly provides The Basic Auth credentials (`accessId` and `accessKey`). **Body parameters** | Parameter | Type | Required | Description | | :----------- | :----- | :------: | :----------------------------------------------------------------------------------------------------------------- | | `asset` | string | Yes | The unique Asset ID of the EGM where the funding request originates. | | `merchantId` | string | Yes | The internal identifier provided by Trustly corresponding to the specific Casino property. | | `gameName` | string | No | The name of the game currently on the EGM. If provided, this renders in the Trustly Microsite header for the user. | | `id` | string | No | The Player ID (if the user is carded or logged in). | **Example request** ```bash 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 | Field | Type | Description | | :---------- | :----- | :---------------------------------------------------------------------------------------------------------------------- | | `token` | string | The encrypted payload for the Trustly Microsite. | | `expiresAt` | string | ISO 8601 date-time string indicating when this specific token and QR code expires. | | `url` | string | The full URL for the Trustly Microsite, including the encoded token. This URL must be converted into the QR Code image. | **Example response** ```json { "token": "w5wDqkdsJ4Ggl+UAvauF/fFv...", "expiresAt": "2025-01-01T17:00:00.0000", "url": "https://cashlesscasino.sandbox.trustly.one/cashlesscasino-client?token=w5wDqkdsJ4Ggl..." } ``` **Common error codes** | Code | Description | | :---- | :------------------------------------------------------------------------------------------ | | `200` | **OK.** The QR code token was successfully generated. | | `400` | **Bad Request.** Missing required fields. For example, `asset` or `merchantId`. | | `401` | **Unauthorized.** Invalid Basic Auth credentials. | | `403` | **Forbidden.** The merchant ID provided is not authorized for this account. | | `500` | **Internal 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.