API docs by Redocly

Wallet API (1.0.0)

Download OpenAPI specification:

Amusement Connect: api@amusementconnect.com URL: https://amusementconnect.com/ License: MIT

API for players using Amusement Connect wallets

Player

Player

Get player balance at location

Get a player's balance at a location

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/json
{
  • "funds": [
    ],
  • "tickets": 5
}

Set player balance at location

Sets the player balance at a location to the desired state.

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

header Parameters
If-Match
string
Default: *

Optimistic concurrency control header. When included, the update will only be applied if the ETag value on the resource matches the provided value.

Request Body schema: application/json
Array of objects (Money)

The player's available funds at this location, broken down by currency. This will set the player's balance to match these values, so any existing funds not included here will be removed and any changes to the amounts of existing currencies will be updated to match.

tickets
number

The number of tickets the player has at this location. This will set the player's ticket balance to this value.

Responses

Request samples

Content type
application/json
{
  • "funds": [
    ],
  • "tickets": 5
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Get gameplay transactions for a player

Returns a paginated list of gameplay transactions for a player as tab charges. Transactions not associated with a tab will have tabId set to null.

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

skip
integer
Example: skip=10

The number of records to skip in the response. If not specified, no records are skipped.

take
integer
Example: take=10

The maximum number of records to return in the response. If not specified, all records are returned.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 42,
  • "items": [
    ]
}

Get player cards

Get the list of cards registered to a player's wallet

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
string (locationId)

Optionally filter the card balances by location Id

skip
integer
Example: skip=10

The number of records to skip in the response. If not specified, no records are skipped.

take
integer
Example: take=10

The maximum number of records to return in the response. If not specified, all records are returned.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 3,
  • "items": [
    ]
}

Register card

Register a card to a player's wallet

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
rfid
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$

The unique identifier of the RFID card. This should be derived from the 4 byte UID of the RFID card as a 32 bit integer and formatted to a 10 digit string. For example the UID of 0x5130A52A would be converted to "0715468881"

displayName
string or null

Responses

Request samples

Content type
application/json
{
  • "rfid": "0715468881",
  • "displayName": "My Card"
}

Response samples

Content type
application/json
{
  • "rfid": "0715468881",
  • "cardLife": 1
}

Get player card

Get a specific card registered to a player's wallet

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
string (locationId)

Optionally filter the card balances by location Id

skip
integer
Example: skip=10

The number of records to skip in the response. If not specified, no records are skipped.

take
integer
Example: take=10

The maximum number of records to return in the response. If not specified, all records are returned.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 3,
  • "items": [
    ]
}

Update card

Update the players card settings

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
displayName
string

Responses

Request samples

Content type
application/json
{
  • "displayName": "My Card"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Unregister card

Unregister a card from a player's wallet

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Gameplay

Gameplay

Get location game categories

Get the list of available game categories at a location

path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Get location games

Get the list of games available at a location to play

path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

search
string or null <= 100 characters
Example: search=Racing

Optional search term to filter games by name or description.

category
Array of strings[ items <= 30 characters ]
Example: category=Pinball
skip
integer
Example: skip=10

The number of records to skip in the response. If not specified, no records are skipped.

take
integer
Example: take=10

The maximum number of records to return in the response. If not specified, all records are returned.

Responses

Response samples

Content type
application/json
{}

Get game details

Get details for a game at a location. Includes pricing information, images, descriptions, and other details.

path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

gameId
required
string <uuid>

The unique identifier of the game machine.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Racing Madness",
  • "category": "Racing",
  • "image": {},
  • "play": {
    }
}

Start a gameplay session

Attempt to start a gameplay session

Authorizations:
apiKeyspaSession
query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
One of
gameMachineId
string

The unique identifier of the game machine to start.

idempotencyKey
string or null <uuid>

A unique identifier for the request to prevent reattempted requests from causing duplicate game starts.

startMethod
string or null
Default: "Remote"
Enum: "Remote" "Http"

The method used to start the game.

  • Remote: The game is started remotely via Amusement Connect cloud services.
  • Http: Only for use by readers, if this request returns a 200 response with a success status the game will be started.
object (GameplayRequestCard)

Information about the card to be used for gameplay request. Players requesting gameplay must have the card registered to them to be able to use it for gameplay.

object (GameplayRequestPartner)

Information about the partner starting the gameplay session.

object (GameplayRequestPlayer)

Information about the player starting the gameplay session.

object (GameplayRequestPayment)

Payment method for the gameplay session. Provide either paymentId (saved card / tab) or digitalWalletPaymentToken + digitalWalletPaymentMethod (Google Pay / Apple Pay), not both.

GameplayRequestCreditPlay (object) or GameplayRequestPartnerPlay (object)

The play options for the gameplay session.

Responses

Request samples

Content type
application/json
{
  • "readerId": "string",
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1",
  • "startMethod": "Remote",
  • "card": {
    },
  • "partner": {
    },
  • "player": {
    },
  • "payment": {
    },
  • "play": {
    }
}

Response samples

Content type
application/json
{
  • "gameplaySessionId": "d3cf0135-6184-4e1e-a631-b6e34bd0a313",
  • "balance": {
    },
  • "creditsUsed": 0,
  • "player": {
    },
  • "failureReason": "string",
  • "playInstruction": {
    }
}

Location

Location

Get location pricing

Get the card and credit pricing options for location

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

includePackages
boolean

Whether to include the available packages for the location in the response. If not provided, the packages will not be included.

Responses

Response samples

Content type
application/json
{
  • "credits": {
    },
  • "packages": [
    ]
}

Create card transaction

Create a new card transaction at a location Adds a new transaction to for adding to a cards balance at this location. Option 1 - Price only > calculate base and bonus credits based on location rates and promotions Option 2 - base or bonus credits are supplied, we use those values directly Option 3 - if bonus credits are supplied with a price, we calculate the base credits from location configuration and add the supplied bonus credits on at the end Option 4 - if just bonus credits is supplied, we kick them back and say supply a price or base credits as well. Option 5 - if all 3 are supplied, we push forward the price, but use the exact base and bonus Amounts

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

whatIf
boolean

If true, the transaction will be validated but not actually processed. This can be used to check if a transaction request is valid and see the expected outcome without making any changes to the card balances.

Request Body schema: application/json
required
Array of objects or objects or objects
Array of objects or null

A list of package purchases made in a single transaction. Each entry in the list represents a purchase of a specific package for a set of card numbers.

object or object or (object or null) (CardTransactionPayment)
externalTransactionId
string or null <= 128 characters

An optional external identifier for the transaction

Responses

Request samples

Content type
application/json
{
  • "cards": [
    ],
  • "packages": [
    ],
  • "payment": {
    },
  • "externalTransactionId": "string"
}

Response samples

Content type
application/json
Example
{
  • "cardTransactionId": "00000000-0000-0000-0000-000000000002"
}

Refund card transaction

Refund a card transaction by its ID at a location. Reverses the effects of the original transaction, removing any credits, tickets, timed play, or attractions purchased.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

cardTransactionId
required
string <uuid> (cardTransactionId)
Example: 00000000-0000-0000-0000-000000000002

The unique identifier of the card transaction.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Card

Card

Get card location balance

Get the balance for a card at a specific location

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/json
{
  • "credits": 100,
  • "tickets": 5,
  • "tab": {
    },
  • "timedPlay": {
    },
  • "timedPlaySessions": [
    ],
  • "attractions": [
    ],
  • "location": {
    }
}

Charge card balance to open tab at location

Charge a card balance to an open tab at the location. This will add a new charge to the tab for the specified amount and deduct the amount from the card balance. The tab must be open and associated with the card at this location for the charge to be successful.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
transactionId
required
string

The unique identifier to associate the charge with.

required
object (CardChargeToLocationTabCostToPlayRequestModel)
required
object (CardChargeToLocationTabGameMachineRequestModel)

Responses

Request samples

Content type
application/json
{
  • "transactionId": "string",
  • "costToPlay": {
    },
  • "gameMachine": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "externalId": "ext-charge-123456789",
  • "ticketBalance": 10,
  • "player": {
    }
}

Get location card balance Deprecated

We updated the path for this endpoint to be /card/{cardNumber}/location/{locationId} to better reflect that the primary resource being accessed is the card balance, but we will continue to support this path for backward compatibility.

Get the balance for a card at a specific location

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Responses

Response samples

Content type
application/json
{
  • "credits": 100,
  • "tickets": 5,
  • "tab": {
    },
  • "timedPlay": {
    },
  • "timedPlaySessions": [
    ],
  • "attractions": [
    ],
  • "location": {
    }
}

Tab

Operations for managing tabs at locations with an integrated tab provider

Charge card balance to open tab at location

Charge a card balance to an open tab at the location. This will add a new charge to the tab for the specified amount and deduct the amount from the card balance. The tab must be open and associated with the card at this location for the charge to be successful.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)

The unique identifier of the location.

cardNumber
required
string (rfid) ^((\d{10})|(\+\d{11,13}))$
Example: 0715468881

The unique identifier of the card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
transactionId
required
string

The unique identifier to associate the charge with.

required
object (CardChargeToLocationTabCostToPlayRequestModel)
required
object (CardChargeToLocationTabGameMachineRequestModel)

Responses

Request samples

Content type
application/json
{
  • "transactionId": "string",
  • "costToPlay": {
    },
  • "gameMachine": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "externalId": "ext-charge-123456789",
  • "ticketBalance": 10,
  • "player": {
    }
}

Hosted Fields

Payroc Hosted Fields session management

Create a Payroc Hosted Fields session token

Generates a scoped, single-use session token for initializing the Payroc Hosted Fields JS library on the client. The session token:

  • Expires after 10 minutes
  • Can only be used once
  • Is scoped to tokenization only
  • Does not expose the API key or bearer token

The client passes this token to new Payroc.hostedFields({ sessionToken: ... }).

Authorizations:
apiKeyspaSession
query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

terminalId
string

Override the default processing terminal ID.

idempotencyKey
string

Client-supplied key to deduplicate requests within 10 minutes.

Responses

Response samples

Content type
application/json
{
  • "sessionToken": "eyJhbGci...",
  • "expiresAt": "2026-04-08T18:40:00Z",
  • "processingTerminalId": "1234001"
}

Vault a card without opening a tab

Vaults a single-use token (captured client-side via Payroc Hosted Fields) into Payroc's secure card vault and persists the card to the player's saved payment methods. No tab or pre-authorization is created.

Use this when you want to save a card on file without immediately opening a tab — for example, during onboarding before the player starts a session. To open a tab at the same time, use /payment/tabs/open/single-use-token instead.

The response includes vaultId and paymentToken — persist the paymentToken against the player for future tab-open flows using /payment/tabs/open/secure-token.

Authorizations:
apiKeyspaSession
query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
locationId
required
string

Location used to scope the saved payment method.

playerId
required
string

AmusementConnect player ID.

singleUseToken
required
string

Single-use token from Payroc Hosted Fields submissionSuccess callback. Expires after 30 minutes. Raw card data is never accepted.

postalCode
required
string

Billing postal code for AVS verification.

operatorName
string or null

Operator or kiosk identifier.

terminalId
string or null

Override the default processing terminal ID.

idempotencyKey
string or null

Client-supplied key to deduplicate requests within 10 minutes.

Responses

Request samples

Content type
application/json
{
  • "locationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "playerId": "player_xyz",
  • "singleUseToken": "296753xxxxxx",
  • "postalCode": "12345"
}

Response samples

Content type
application/json
{
  • "vaultId": "vault_abc123",
  • "paymentToken": "296753112233",
  • "maskedCardNumber": "************1234",
  • "expiryDate": "0428",
  • "cardType": "Visa"
}

Digital Wallets

Google Pay and Apple Pay direct-sale processing

Create an Apple Pay merchant session

Performs Apple Pay merchant validation by calling the validationURL provided by the Apple Pay JS validatemerchant event.

Client-side flow:

  1. Initialize ApplePaySession in the browser.
  2. In the onvalidatemerchant handler, POST the event's validationURL to this endpoint.
  3. Pass the response body directly to session.completeMerchantValidation().

The backend calls Apple's server using the merchant identity certificate configured in Key Vault. The opaque session object is returned as-is.

Authorizations:
apiKeyspaSession
query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

Request Body schema: application/json
required
appleValidationUrl
required
string <uri>

The validationURL from the Apple Pay JS validatemerchant event. Must be an https://*.apple.com URL.

appleDomainId
string or null

Override the Apple Pay domain ID configured in Key Vault. If omitted, the server-side default is used.

terminalId
string or null

Override the default processing terminal ID.

idempotencyKey
string or null

Client-supplied key to deduplicate requests within 10 minutes.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "epochTimestamp": 1776441992332,
  • "expiresAt": 1776445592332,
  • "merchantSessionIdentifier": "string",
  • "nonce": "string",
  • "merchantIdentifier": "string",
  • "domainName": "pay-dev.amusementconnect.com",
  • "displayName": "Amusement Connect",
  • "signature": "string",
  • "operationalAnalyticsIdentifier": "string",
  • "retries": 0,
  • "pspId": "string"
}

Payments

Get saved payment methods for a player at a location

Returns the player's saved (vaulted) payment methods at a given location. Deleted cards are excluded from the response.

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
required
string (locationId)

The location to scope the saved payment methods to.

Responses

Response samples

Content type
application/json
{
  • "cards": [
    ]
}

Update a saved payment method

Updates a saved payment method on the player's profile at a location. If isActive is set to true, all other saved payment methods for the player at this location will have isActive set to false.

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

cardId
required
string <uuid>

The ID of the saved card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
required
string (locationId)

The location the card belongs to.

Request Body schema: application/json
required
isActive
boolean

Whether this payment method is the active/default one for the player.

Responses

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Delete a saved payment method

Soft-deletes a saved payment method from the player's profile at a location. The card is marked as deleted and excluded from future getSavedPaymentMethods responses.

Authorizations:
apiKeyspaSession
path Parameters
playerId
required
string <uuid> (playerId)
Example: 00000000-0000-0000-0000-000000000001

The unique identifier of the player.

cardId
required
string <uuid>

The ID of the saved card.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
required
string (locationId)

The location the card belongs to.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "errors": {
    }
}

Get tabs for a player at a location

Returns all tabs (all statuses) for a player at a given location, ordered by most recently opened.

Authorizations:
apiKeyspaSession
query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

playerId
required
string <uuid> (playerId)
Example: playerId=00000000-0000-0000-0000-000000000001

The player whose tabs to retrieve.

locationId
required
string <uuid>

The location to scope the tab lookup to.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get gameplay sessions charged to a tab

Returns all gameplay sessions (charges) associated with a tab. Returns 404 if the tab does not exist at the given location.

Authorizations:
apiKeyspaSession
path Parameters
tabId
required
string <uuid> (tabId)
Example: 00000000-0000-0000-0000-000000000003

The tab whose gameplay charges to retrieve.

query Parameters
apiVersion
string
Default: "1.0"
Value: "1.0"

The version of the API to use.

locationId
required
string <uuid>

The location the tab belongs to.

Responses

Response samples

Content type
application/json
[
  • {
    }
]