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)
Example: 00000000-0000-0000-0000-000000000000

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)
Example: 00000000-0000-0000-0000-000000000000

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)
Example: locationId=00000000-0000-0000-0000-000000000000

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)
Example: locationId=00000000-0000-0000-0000-000000000000

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)
Example: 00000000-0000-0000-0000-000000000000

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)
Example: 00000000-0000-0000-0000-000000000000

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)
Example: 00000000-0000-0000-0000-000000000000

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 duplicate game starts. If omitted, the server generates a new UUID — idempotency protection is only active when a key is explicitly supplied.

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)
Example: 00000000-0000-0000-0000-000000000000

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

externalTransactionId must be unique per location when supplied. A request that reuses an existing transaction's value at the same location is rejected with 400 Bad Request.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

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 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 (CardTransactionPayment)

Attach payment details to the card transaction.

externalTransactionId
string or null <= 128 characters

An optional caller-supplied identifier for the transaction. Must be unique per location when supplied — re-using a value already attached to a transaction at the same location returns 400 Bad Request. Use this when you want to look up or refund the transaction by your own id later (see POST /location/{locationId}/card-transaction/refund).

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 by external id

Refund a card transaction identified by the caller-supplied externalTransactionId (instead of the cosmos transaction id). All request-body and response semantics match POST /location/{locationId}/card-transaction/{cardTransactionId}/refund — see that endpoint's description for the full refund semantics.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

The unique identifier of the location.

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

The version of the API to use.

externalTransactionId
required
string

The caller-supplied external transaction id that uniquely identifies the original card transaction at the location.

Request Body schema: application/json
optional
reason
string or null

Optional human-readable reason recorded with the refund for audit purposes.

idempotencyKey
string or null <uuid>

Client-supplied key to deduplicate retried refund requests within ~10 minutes. A retry with the same idempotency key returns the cached response without applying additional balance changes.

object (RefundCardTransactionRequestPayment)

Records cash/credit returned to the customer outside this service. Total amount across all refunds for a transaction must not exceed the original payment amount.

Array of objects or null (RefundCardTransactionRequestCard)

null / omitted → refund every card from the original transaction in full. Empty array → no card balance changes (payment-only refund still recorded). Non-empty → refund only the specified cards with the per-dimension amounts inside each entry.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1",
  • "payment": {
    },
  • "cards": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "cardTransactionId": "00000000-0000-0000-0000-000000000002",
  • "cards": [
    ],
  • "totalCreditsRefunded": 0.1,
  • "totalTicketsRefunded": 0.1,
  • "payment": {
    }
}

Refund card transaction

Refund all or part of a card transaction at a location. This service does not process payments — it records the result of cash/credit returned outside the service alongside the card-side reversal.

Scope of the refund

  • Omit the body (or omit cards) to refund every card from the original transaction in full.
  • Provide cards: [] to record a payment-only refund with no card balance changes.
  • Provide a list of cards to refund only those cards with the per-dimension amounts inside each entry.

Fine-grained refunds for each card entry — applies to credits, tickets, and attractions:

  • null (field omitted) → refund the full remaining amount for that dimension.
  • 0 / empty array → refund nothing for that dimension.
  • Positive value → refund that amount, capped at remaining.

Credits can be specified by explicit credits or by price (dollars, converted via the location's credit-per-dollar rate). Explicit credits wins over price.

Timed play is controlled by removeTimedPlay: null (default) or true disables the timed play session; false leaves it alone. Once disabled by any prior refund, subsequent refund attempts are a silent no-op.

Cumulative caps: multiple partial refunds against the same transaction are allowed, but the total refunded amount across all refunds may not exceed what the original transaction added (per card, per dimension) or the original payment amount (for payment.amount). Requests that would exceed the remaining cap are rejected with 400.

Refunding partially used cards: when a card has already spent some of the originally-added credits or tickets, the actually-removed amount clamps at zero (never goes negative). The response's actual*Refunded fields reflect what was applied.

Idempotency: supply idempotencyKey for replay safety. A retry with the same key within in a short period returns the cached response without re-applying changes; a retry while the original is still in flight returns 202 with Retry-After: 3.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

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.

Request Body schema: application/json
optional
reason
string or null

Optional human-readable reason recorded with the refund for audit purposes.

idempotencyKey
string or null <uuid>

Client-supplied key to deduplicate retried refund requests within ~10 minutes. A retry with the same idempotency key returns the cached response without applying additional balance changes.

object (RefundCardTransactionRequestPayment)

Records cash/credit returned to the customer outside this service. Total amount across all refunds for a transaction must not exceed the original payment amount.

Array of objects or null (RefundCardTransactionRequestCard)

null / omitted → refund every card from the original transaction in full. Empty array → no card balance changes (payment-only refund still recorded). Non-empty → refund only the specified cards with the per-dimension amounts inside each entry.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1",
  • "payment": {
    },
  • "cards": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "cardTransactionId": "00000000-0000-0000-0000-000000000002",
  • "cards": [
    ],
  • "totalCreditsRefunded": 0.1,
  • "totalTicketsRefunded": 0.1,
  • "payment": {
    }
}

Card

Card

Get card location balance

Get the balance for a card at a specific location

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

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": {
    }
}

Modify Card Location Balance

Modify the location balance of a card by adjusting credits, tickets, timed play sessions, and attraction passes in a single request. Credit and ticket values are applied as deltas (positive to add, negative to subtract). Timed play and attraction entries each describe a targeted change to an existing balance item.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

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.

life
integer or null

Optionally specify the card life to target when modifying the balance. If not provided, the update will be applied to the card's current life.

Request Body schema: application/json
required
idempotencyKey
string or null <uuid>

Optional client-generated UUID used to deduplicate this request. When supplied, the same key replayed within 10 minutes returns the original response, or 202 Accepted while the original request is still in flight. Omit this field for one-off requests that do not need replay protection.

credits
number or null <double>

Amount to add to (positive) or subtract from (negative) the card's credit balance at this location.

tickets
number or null <double>

Amount to add to (positive) or subtract from (negative) the card's ticket balance at this location.

Array of objects or null (ModifyTimedPlaySessionRequestModel)

Updates to apply to existing timed play sessions on the card. Each entry targets one session by id; sessions that have already ended cannot be modified.

Array of objects or null (ModifyAttractionPassesRequestModel)

Updates to apply to attraction or attraction group pass balances on the card.

Responses

Request samples

Content type
application/json
{
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1",
  • "credits": 10.5,
  • "tickets": 25,
  • "timedPlaySessions": [
    ],
  • "attractions": [
    ]
}

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)
Example: 00000000-0000-0000-0000-000000000000

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": {
    }
}

Refund a card across its transaction history at a location

Refunds payment and removes balance from a card by walking the card's transaction history newest-first and refunding the requested amounts from each record until the full requested refund amount is reached.

Authorizations:
apiKeyspaSession
path Parameters
locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

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.

cardLife
integer or null

Optional card life to disambiguate when a single RFID has been reused across multiple card lives at the location. Omit to target the most recent active card life.

Request Body schema: application/json
optional
object (RefundCardRequestPayment)

Records cash/credit returned to the customer outside this service.

object (RefundCardTransactionRequestCredits)

Credits refund spec. Explicit credits wins over price. price converts via Location.CreditPerDollar. Either-or-both-null = refund all remaining credits.

tickets
number or null <double>

Tickets to remove (cosmos history only). null = drain remaining; 0 = none; positive = that count.

removeTimedPlay
boolean
Default: true

true (default) = disable timed-play sessions that came from the card's cosmos history. false = leave them enabled.

Array of objects or null (RefundCardTransactionRequestAttraction)

Attraction passes to refund (cosmos history only). null = drain all; empty = none.

reason
string or null

Optional human-readable reason recorded with each refund document/row written.

idempotencyKey
string or null <uuid>

Client-supplied key to deduplicate retried refund requests within ~10 minutes. A retry with the same key returns the cached response without applying additional changes.

Responses

Request samples

Content type
application/json
{
  • "payment": {
    },
  • "credits": {
    },
  • "tickets": 0.1,
  • "removeTimedPlay": true,
  • "attractions": [
    ],
  • "reason": "string",
  • "idempotencyKey": "0c14c6a6-6f50-4d1e-b0c4-b46ff43ba6a1"
}

Response samples

Content type
application/json
{
  • "cardNumber": "string",
  • "cardLife": 0,
  • "totalPaymentRefunded": 0.1,
  • "paymentRefunds": [
    ],
  • "totalCreditsRefunded": 0.1,
  • "totalTicketsRefunded": 0.1,
  • "totalAttractionPassesRefunded": [
    ],
  • "totalTimedPlaysDisabled": 0,
  • "balance": {
    },
  • "cardTransactionRefundIds": [
    ],
  • "kioskTransactionRefundIds": [
    ]
}

Transfer card balances

Transfer the location balances from one or more source cards into the target card. By default a source card has its full location balance (credits, tickets, and attraction passes) merged onto the target card, but each source may instead specify the exact credits, tickets, and/or attraction passes to move — any dimension left unspecified moves in full. A record of the transfer is written so it appears in each card's history.

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

The unique identifier of the card.

locationId
required
string (locationId)
Example: 00000000-0000-0000-0000-000000000000

The unique identifier of the location.

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

The version of the API to use.

cardLife
integer or null

Optional card life of the target card to disambiguate when a single RFID has been reused across multiple card lives at the location. Omit to target the most recent active card life.

Request Body schema: application/json
required
required
Array of objects [ 1 .. 10 ] items

The source cards to transfer into the target card. Each source card will have all or some of its location balance moved to the target card.

Responses

Request samples

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

Response samples

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

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)
Example: 00000000-0000-0000-0000-000000000000

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)
Example: 00000000-0000-0000-0000-000000000000

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.

locationId
required
string <uuid>

The location to scope the Hosted Fields session to.

idempotencyKey
string <uuid>

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 <uuid>

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.

idempotencyKey
string or null <uuid>

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 for the given location. The validation URL and domain are read from server-side configuration.

Client-side flow:

  1. Initialize ApplePaySession in the browser.
  2. In the onvalidatemerchant handler, POST the location ID 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
locationId
required
string <uuid>

The location to perform Apple Pay merchant validation for. The validation URL and domain are read from server-side configuration.

idempotencyKey
string or null <uuid>

Client-supplied key to deduplicate requests within 10 minutes.

Responses

Request samples

Content type
application/json
{
  • "locationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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)
Example: locationId=00000000-0000-0000-0000-000000000000

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)
Example: locationId=00000000-0000-0000-0000-000000000000

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)
Example: locationId=00000000-0000-0000-0000-000000000000

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
[
  • {
    }
]