Ascenda allows your user to redeem digital gift cards from many favourite brands. Gift cards are issued instantly and can be used to make purchases immediately.

Gift Cards Overview

Supported countries

A growing range of countries is supported, covering all major markets. Please speak to the Ascenda team about the latest availability for your geography.

Brand categories

Gift cards are available across a wide range of categories to ensure relevance for users:

• Beauty and Health
• Dining
• Electronics
• Entertainment
• Experiences
• Fashion
• Home and Garden
• Jewelry
• Online Shopping
• Transport
• Young Ones
• Malls and Hypermarkets
• Others

Gift card denominations

The range of available denominations for each merchant varies. Ascenda ensures there is a sufficiently broad spectrum of denominations to suit users with different points balances.

Redemption pricing

End-user redemption price: based on the Cost per Point (CPP) for gift cards in the system. The points price displayed to the user is then calculated as follows: Face value of gift card / CPP

Email notification

After every digital gift card redemption, the user receives an email confirming the details of the transaction. Users will also be able to resend the success email through the Order history page.

Check out the full range of email journeys here

Integration Overview

(Steve's overall integration workflow diagram here)

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.

Here’s how a sample API call might look like:

List Gift Cards

Refer to our List Gift Cards API for detailed API specifications. Use the information from each element in the data array to present the list of relevant gift cards to the user.

Note: Each gift card supplier 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.

Recommended Gift Cards Listing Implementation Workflow

Our gift cards endpoint contains all the static information needed to render to your end-users information about each card. Our endpoints contain available cards for redemption, cards may go out of stock and be removed from the listing endpoint (although this is infrequent). In case you're caching gift cards response to optimise for performance, do not cache for more than 1 hour and you must handle the edge case of the gift card being unavailable upon checkout.

Create Fulfilment Order

Design your UI to collect information from your users based on the parameters defined for each gift card supplier. By default we expect your the end-users number (your internal unique User ID), email, first_name and last_name. Some suppliers may require phone_number as well

Ensure your UI respects these limits and provides clear guidance to users. When the end user's redemption of the gift card order is completed, 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 gift card order 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 Gift Card 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 order 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 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 the orders asynchronously.

You should observe for the status field of the gift cards order_items[].status field instead. The status values here are changed whenever the fulfillment state of the gift card order is updated with our suppliers.

• 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.