Third-party member tickets

OCAPI supports the integration of third-party member ticket schemes to enable patrons to redeem tickets from third-party systems using a card number (referred to as a "ticket redemption card").

Third-party member tickets enable promotional and reward-based ticket configuration and validation to be done outside of Vista's systems during an order flow.

NOTE

A third-party member ticket scheme can also be integrated with Vista Loyalty to enable additional rules to be run to calculate eligibility of the tickets for the member. The tickets linked to these third-party schemes are validated and processed completely within Vista software.

Identifying available third-party member schemes

The GetThirdPartyTicketMemberSchemes endpoint returns the list of third-party schemes available for a given cinema site.

Copy

Copied

[
  {
    "id": "string",
    "name": {
      "text": "string",
      "translations": []
    },
    "cardNumberFormat": {
      "partialFormat": null,
      "fullFormat": null,
      "prefixLength": 0
    },
    "redemptionLimitPerShowtime": null
  }
]

NOTE

A third-party member scheme may also be configured for subscription tickets.

Third-party scheme ticket flow

Add ticket redemption card to order

A third-party member card must be added to an in-progress order via the AddTicketRedemptionCard endpoint.

Copy

Copied

{
  "type": "ThirdPartyMemberCard",
  "credentials": {
    "cardNumber": "string",
    "thirdPartyMemberSchemeId": "string"
  },
  "showtimeId": "string"
}

NOTE

A ticket redemption card can be the following types:

ThirdPartyMemberCard - used for third-party member tickets.
MemberTicketRedemptionCard - used for subscription tickets .

This endpoint validates the provided card, stores its details against the order, and returns its id, redemptionLimit, and other details.

Copy

Copied

{
  "ticketRedemptionCard": {
    "id": "string",
    "type": "ThirdPartyMemberCard",
    "maskedCardNumber": "string",
    "subscriptionId": 0,
    "thirdPartyMemberSchemeId": "string",
    "memberName": {
      "givenName": "string",
      "familyName": "string",
      "middleName": "string"
    }
  },
  "redemptionLimit": {
    "isUnlimited": true,
    "maximum": 0,
    "minimum": 0
  }
}

Add third-party member tickets to order

Third-party member tickets are added to the order via the SetShowtime endpoint.

Copy

Copied

{
  "tickets": [
    {
      "id": "string",
      "ticketTypeId": "string",
      "ticketRedemptionCardId": "string"
    }
  ]
}

When adding a third-party member ticket, the ticketRedemptionCardId is required and must be set to the id of the added ticket redemption card.

The request will be declined if the requested number of tickets exceeds the redemptionLimit of the ticket redemption card, or if other validation rules in the third-party system are not met.

Committing third-party tickets in the third-party system

It is important to note that, unlike voucher tickets or loyalty member reward tickets, third-party member ticket redemptions are committed in the third-party system as soon as they are added to the order, not during order completion.

As such, if the order is abandoned, the patron may not be able to re-use their third-party member tickets until the previous order expires or is cancelled (which will reverse the commit in the third-party system).