Points Transfer Programs

Ascenda enables your users to transfer their points to a broad range of favorite frequent traveller programs across major airlines and hotel chains.

For most partners, transfers are completed in real-time, while others may take up to 5 business days to process.

List of partners

For a full list of frequent traveller programs that work with Ascenda, please refer to our website.

When you are ready to set up your rewards program, the Ascenda team will help select a set of relevant transfer partners. Activation of each partner for your program is subject to their approval - a process which Ascenda facilitates to make it easy & effortless.

Additional partners can be added over time post launch in collaboration with the Ascenda team.

❗️

Removal of partners

Removing a transfer partner is only possible in exceptional circumstances and requires advanced notice, subject to a minimum holding period post initial launch. Please refer to your Ascenda agreement for details.

Integration Overview

Authentication

Consult this guide for comprehensive instructions on authenticating with our authorization servers to obtain an access token, which is required for making subsequent API calls.

X-Ascenda-Version: 1.3for Fulfilment Orders

An API version can be specified by providing an API header of X-Ascenda-Version. Fulfillment Orders API is supported from API version 1.3 onwards

Most changes to the Ascenda API are backwards compatible (e.g. adding new attributes, new optional request parameters) and will not result in a new API version. However, in cases where a backwards compatible change is not possible, Ascenda will bump the API version to ensure backwards compatibility with your existing platform which might still be integrated with the current lower version.

Get Loyalty Program List & Details

Refer to our List loyalty programs API to retrieve the list of participating loyalty programs. Use the information from each element in the data array to present the loyalty programs to the user.

Note: Each loyalty program has strict requirements regarding how their brand and assets (e.g., name, description, logo) are presented to end users. It is crucial not to modify the content provided in the returned data. Your Customer Success representative will guide you on these parameters.

Our Customer Success team will provide a list of test accounts for each loyalty program to support your development and UAT testing efforts. Each account ID is configured with expected responses (success or failure), enabling you to design and refine your user flow handling accordingly.

Recommended Program Listing Implementation Workflow

Programs contain all the static information needed to render to your end-users information about each loyalty program. You should cache the data rendered to the end-user in your system.

The only data point which may change is the credit processing delay time (which is very infrequent and typically due to maintenance delays). Thus, we recommend a daily cache of the programs polled from the RC List Programs API. Any processing time related change would impact in terms of days. A daily cache is sufficient for getting the latest program availability statuses.

Validate Format of Membership ID submitted by User

Refer to the Validate Membership endpoint specifications to validate the format of the user’s submitted loyalty program membership ID.

If required, we can also provide a list of simple validations (regular expressions) for a simpler implementation of validation logic on the client side. Please reach out to your Customer Success manager for more information.

Recommended Implementation of Memberships Validation

Step (1): Ascenda takes care of changes by the loyalty partner on any change to member ID validation logic

Step (2): The membership validation during Points Transfer order creation is the same as that of the validation endpoint, you shouldn’t receive any membership validation error as long as the ID used is consistent.

Create Fulfilment Order

Design your UI to collect information from your users based on the parameters defined for each loyalty program. Typical points transfer requirements include the end-users loyalty membership number, first_name and last_name.

Ensure your UI respects these limits and provides clear guidance to users. When the end user's selection for the points transfer is collected, refer to Create Fulfillment Order endpoint to create and submit an order.

Recommended Workflow for Connection Timeouts

Sometimes, transactions may timeout, in such a scenario, the transaction may not have been received by Ascenda. We strongly recommend to not fail these transaction for the customer and perform a check on whether this transaction has been received by us.

Here’s how a sample workflow could look like:

Follow our Idempotency guide to ensure a safe management of transient Connection errors in your Points Transfer orders.

Step (1): Customer initiates a checkout to your client system which leads to order creation

Step (2): During order creation, a timeout may happen and we do not wish to fail the transaction for the end-user/ customer immediately. The credit request may/ may not have been received by Ascenda.

Step (3): Using the provisioned list orders endpoint, you check for the presence of the order using your unique reference_id used in creation (also the unique client transaction ID in your system).

Step (4): If the order is found to have been created, you can continue the success flow in your system where the credit has been created (The list order endpoint returns all information including the order ID). Otherwise if no order is forthcoming, that means that you can retry credit creation with Ascenda

Step (5): If the issue persists (e.g. after 5 retries), this suggests a systematic error in our integration. Please reach out to our Ops team at [email protected] and we’ll work with you to resolve the connection issue.

As far as possible, we’d like to ensure a successful transaction for the end-user/ customer, in the event of further errors/ timeouts, please place the transaction as processing and our engineering team will work with you to rectify these issues.

Webhook Notification

Refer to the Order Item Fulfillment Webhook specifications for details on the webhook events and other details.

Guideline: Statuses to observe for order fulfillment outcomes

The status field showcases only the outcomes of the order fulfillment request. It doesn’t yet distinguish the final outcome of an order as we process points transfer fulfillments asynchronously.

You should observe for the status field of the points transfer order_items[].status field instead. The status values here are changed whenever the fulfillment state of the transfer is updated with our loyalty program.

• pending: Initial state of an order item when it is first created and awaiting processing
• processing: Order item is being processed by the system (with our loyalty partners)
• fulfilled: Order item has been successfully processed (points are fulfilled)
• cancelled: Order item was cancelled after the fulfillment
• failed: Order item failed during the checkout process and could not be completed

When verifying whether the points have been successfully fulfilled, you should only observe for the fulfilled status as the only indicator of success. The cancelled and failed status indicates a failure to credit the points to customers and you should refund the end user their own points they used to redeem for the loyalty points.transaction.

When verifying for failed transaction reasoning, look to the order_items[].errors field for the specific error during the fulfillment process. See Section 8B for the most common errors to observe for.