search
Ventrata.comOCTO.travel
githubEdit

Redemption

Redeem tickets and bookings by reference or barcode

To use this capability add octo/redemption to your Octo-Capabilities header.

This capability allows a supplier to redeem tickets using a barcode or reference number. It's not enabled by default and not available or intended for resellers.

hashtag
Products

GET https://api.ventrata.com/octo/products

This endpoint isn't specific to this capability as it's part of the OCTO core, but worth mentioning as it will return a list of products that the redemption lookup and redeem endpoints might return. This is important if you need to know what products, options and units to expect and map them in advance.

[
  {
    "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "internalName": "Walking Tour of Barcelona",
    "reference": "BRC-WALK",
    "locale": "en",
    "timeZone": "Europe/Madrid",
    "allowFreesale": true,
    "availabilityType": "START_TIME",
    "deliveryFormats": ["PDF_URL", "QRCODE"],
    "deliveryMethods": ["TICKET", "VOUCHER"],
    "redemptionMethod": "DIGITAL",
    "capabilities": [
      {
        "id": "octo/content",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "octo/cart",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "octo/pricing",
        "revision": 1,
        "required": false,
        "dependencies": []
      },
      {
        "id": "octo/offers",
        "revision": 1,
        "required": false,
        "dependencies": ["octo/pricing"]
      },
      {
        "id": "octo/card-payment",
        "revision": 1,
        "required": false,
        "dependencies": []
      }
    ],
    "options": [
      {
        "id": "DEFAULT",
        "default": true,
        "internalName": "DEFAULT",
        "reference": null,
        "restrictions": {
          "minUnits": 0,
          "maxUnits": null
        },
        "units": [
          {
            "id": "adult",
            "internalName": "Adult",
            "reference": "adult",
            "type": "ADULT",
            "restrictions": {
              "minAge": 18,
              "maxAge": 99,
              "idRequired": false,
              "minQuantity": null,
              "maxQuantity": null,
              "paxCount": 1,
              "accompaniedBy": []
            }
          },
          {
            "id": "child",
            "internalName": "Child",
            "reference": "child",
            "type": "CHILD",
            "restrictions": {
              "minAge": 0,
              "maxAge": 17,
              "idRequired": false,
              "minQuantity": null,
              "maxQuantity": null,
              "paxCount": 1,
              "accompaniedBy": ["adult"]
            }
          }
        ]
      }
    ]
  }
  // ...rest of the products
]

You can see a full description of the endpoint and documentation on each field here.

hashtag
Lookup

GET https://api.ventrata.com/octo/redemption/lookup

Finds all matching bookings given a scanned code (reference). This can either be a barcode or reference number. From the input we'll attempt to locate all matching bookings and return them in the response.

hashtag
Query Parameters

Name
Type
Description

reference

string

The reference/barcode you're looking up

The response is an array of bookings, the schema of which is described here. The only addition are two fields:

redemptionCode which you'll need to redeem that booking. redeemable which is true or false depending whether this booking can be redeemed.

circle-info

The first thing to note is the endpoint may return multiple results, when this happens it is because the scanned code might be that of a package which contains more than one bookings that you must chose which you want to redeem.

hashtag
Redeem

POST https://api.ventrata.com/octo/redemption/redeem

Once you've chosen a booking to redeem, this endpoint performs the redemption.

hashtag
Request Body

Name
Type
Description

redemptionCode*

string|array

The redemption code or codes from the lookup call

Note if your application groups multiple redemption codes together it's also possible to send redemptionCode parameter as an array of codes you want to redeem. If this parameter is sent as an array then the response body will also be an array of each redemption response. For example:

Will redeem codes "a", "b" and "c" together.

The redemptionCode parameter is taken from the lookup response. The response will return the booking object, now with a status altered to "REDEEMED".

hashtag
Redemption Credentials

POST https://api.ventrata.com/octo/redemption/credentials

In some cases where you might have multiple credentials on the same system that you redeem for, this endpoint is un-authenticated where you send the reference/barcode and a list of credentials, and we will return the most appropriate.

hashtag
Request Body

Name
Type
Description

reference

string

apiKeys

array

An example request might be like:

The system will then search through each API key to find the one most appropriate for the given code and return it, for example:

However if the code is not recognised from any of the apiKeys then null will be returned instead, for example:

In which case you should assume the reference does not belong to any of the provided apiKeys.

hashtag
Redemption Validation

POST https://api.ventrata.com/octo/redemption/validate

hashtag
Request Body

Name
Type
Description

redemptionCode*

String

The redemption code from the lookup call

Finally the POST /redemption/validate endpoint allows you to validate a ticket against the validation rules stored in our system. Use this if you want to rely on our system to define the validation rules beyond redemption and not have to manage the validity state yourself.

Note if the ticket is not already redeemed the validate endpoint will automatically redeem it first, so it's suggested that you you should use either redemption/redeem or redemption/validate but not both at the same time.

PreviousGift VouchersNextOnline Check-in

Last updated