External Checkout API

There is an API to start a checkout process via a URL.

Starting the Checkout Process

This checkout process can be started by a link to the external checkout page: admira/checkout/external

Note: if the base route is changed it need to be replaced.

The following query arguments NEED be passed to the URL:

• eti
  • (required) string - External transaction ID, used to identify the transaction.
• success_url
  • (required) string - URL to redirect to on successful checkout.
• error_url
  • (required) string - URL to redirect to on failed checkout.
• products
  • (required) array - Array of product ID keys and quantity values. Example: products[123]=2&products[456]=1
• space
  • (optional) string - Space ID to use for the checkout. Defaults to the first space in the list of spaces.

Any other query arguments can be added and supported via the filter admira_tickets_external_checkout_params.

Upon entering this URL, the following will happen on a successful request:

1. The query arguments are processed.
2. Additional query arguments may be added or modified via the filter admira_tickets_external_checkout_query_args
3. Required parameters are checked.
4. The cart is created.
5. The parameters will be added in the cart's externalData as a stringified JSON object.
6. Space ID is fetched if not provided.
7. Add each product to the cart.
8. Cart is fetched if the local cart system is enabled.
9. Add the cart_id as query arg to the admira/checkout/external URL and redirect to it.

There are multiple points of failure in this process and they are all detailed in Start Checkout Errors.

The checkout will then proceed as normal for the user to pay for the cart and complete the checkout process, which is detailed in the Finishing the Checkout Process section below.

Finishing the Checkout Process

Upon the checkout process finishing, the user will be directed to the url admira/checkout/external/finish (unless the tickets base route is changed) with the cart ID as a query argument.

On this URL, the following will happen on a successful request:

1. The cart ID is checked to see if it's set as a query argument.
2. The cart is fetched using the cart ID.
3. The cart's externalData is fetched from the cart data.
4. The externalData parameters are processed and checked.
5. The status of the Cart is checked to see if it's SOLD.
6. The transaction of the Cart is fetched for its transaction ID.
7. Query arguments for the redirect as prepared as the 'cart_id', 'eti', and 'transaction_id'.
8. The query args are possibly changed or added to via the filter admira_tickets_external_checkout_finish_query_args.
9. The cart_id, the eti, and the transaction_id are added to the query arguments of the success URL and the user is redirected to it.

There are multiple points of failure in this process and they are all detailed in Finish Checkout Errors.

Start Checkout Errors

During the start of the checkout process, there are several points where errors can occur. These errors will redirect the user to the error_url provided in the query arguments with at least a error code and other parameters if available at that point.

The code and additional data that can be returned passed via the query arguments, along with an explanation, are as follows:

invalid_param:{key}

• The parameter {key} is missing or invalid. This can happen if the eti, success_url, error_url, or products parameters are not provided or are malformed.
• Additional data:
  • eti: The external transaction ID that was provided, if it is available.

missing_param:{key}

• The parameter {key} is required but was not provided or was removed by the admira_tickets_external_checkout_params filter. This can happen if the eti, success_url, error_url, or products parameters are not provided.
• Additional data:
  • eti: The external transaction ID that was provided, if it is available.

create_cart_failed

• The cart could not be created in admira.
• Additional data:
  • eti: The external transaction ID that was provided.

cart_add_external_data_failed

• The external data could not be added to the cart in admira.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of cart that was created.

external_no_valid_space_found

• No valid space was found for the checkout. This can happen if the space parameter is not provided and no spaces are available in admira.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of cart that was created.

cart_add_products_failed

• The products could not be added to the cart in admira. This can happen if the products are not valid or if there is an issue with the cart.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of cart that was created.
  • product_id: The ID of the product that could not be added.
  • space_id: The ID of the space that was used to add the product.

cart_fetch_failed

• The cart could not be fetched from admira. The cart is fetched after the products are added to it, if the local cart system is enabled, so we have a fresh version of the cart locally.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of cart that was created.

Finish Checkout Errors

During the finish of the checkout process, there are several points where errors can occur. These errors will redirect the user to the error_url provided in the query arguments with at least a error code and other parameters if available at that point.

The code and additional data that can be returned passed via the query arguments, along with an explanation, are as follows:

invalid_cart_id

• The cart ID is missing or invalid. This can happen if the cart_id query argument is not provided or is malformed.

failed_to_fetch_cart_on_finish

• The cart could not be fetched from admira using the provided cart ID.
• Additional data:
  • cart_id: The ID of the cart.

invalid_external_data

• The external data is missing or invalid in the cart.
• Additional data:
  • cart_id: The ID of the cart.

invalid_external_data

• Some or all of the external data is missing or invalid in the cart.
• Additional data:
  • cart_id: The ID of the cart.

cart_has_no_status

• The cart does not have a status entry or the status is not valid.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of the cart.
  • transaction_id: The transaction ID of the cart, if available.

cart_not_sold

• The cart's status is not SOLD, meaning the checkout process was not completed successfully.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of the cart.
  • transaction_id: The transaction ID of the cart, if available.

no_transaction_id

• The transaction ID is missing or invalid in the cart.
• Additional data:
  • eti: The external transaction ID that was provided.
  • cart_id: The ID of the cart.

Reserved Keywords in Cart's External Data

In order to protect the integrity of the external checkout process, certain keywords are reserved in the cart's external data. These keywords are used to store essential information about the checkout process.

The following keywords are reserved and should not be used in the external data:

• eti: The external transaction ID.
• success_url: The URL to redirect to on successful checkout.
• error_url: The URL to redirect to on failed checkout.
• products: The products that are being checked out, in the format of an array with product IDs as keys and quantities as values.
• space: The space ID used for the checkout.

Other parameters can be added to the external data, but they should not conflict with these reserved keywords.

Before saving these reserved keywords in the cart's external data, their keys are prefixed with external_checkout_ to avoid conflicts and keep them unique. During the finish checkout process, the keys are stripped of this prefix when handled locally and passed to the query args filter.

This prefix is not applied to any non reserved keywords.