Currency Alliance API Documentation (3.0)

Download OpenAPI specification:Download

Introduction

The Currency Alliance API facilitates various use cases for Loyalty Commerce. Our API allows our Partners to:

  • Manage Loyalty Currencies in the Cloud
  • Access Popular Loyalty Currencies from other Brands
  • Sell and Distribute your Loyalty Currency to Partners
  • Issue, Transfer, Redeem, or Exchange any loyalty currency via API
  • Pull Transaction History Details into 3rd Party Platforms
  • Enable the Exchange of Loyalty Currencies into Gift Cards and other Redemption Products in many fiat currencies To benefit from the Currency Alliance platform, you do not need to use all of these features. While there are many Endpoints for specific use cases, most Partners end up using only a few Endpoints.

Architecture

The Currency Alliance API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Calls to the API have to be properly authenticated using your public and secret API keys. The keys are available in the 'CREDENTIALS' section of the "Loyalty API" module in the Management Dashboard. These keys MUST never be exposed to the public or any unauthorized person.

The API is designed for a server to server communication. If you want to communicate with the API from a client it must be through a server environment, to protect the integrity of the requests and the API keys, and not expose them on front-end platforms.

Authentication

The API authenticates every request based on two elements - Credential and Signature. Every request must include an Authorization header with the following two elements. Credential=<public-key>, Signature=<calculated-signature>

Credential

In this parameter, the API requires you to provide the <public-key> that is unique to your account. Your keys are available in the 'CREDENTIALS' section of the "Loyalty API" module in the Management Dashboard.

Signature

How is the Signature calculated?

The signature is a HMAC-SHA256 hash in hexadecimal of the request content, using the private_key as the key. Keep in mind that the string you use to generate the signature and the string you send to the API has to be exactly the same. This includes newlines and spaces. If you compress the JSON body of your request, after generating the signature, the request will be rejected.

POST/PUT/PATCH HTTP methods

These types of requests use the string representation of the body to calculate the signature.

For example, for the request with body: {"foo": "bar"} the signature calculated using sec_12345 as the private key would be 4d84ba663b9c6179dd98023087da5baa8a4e3eb59ba45284935261350ba70742

GET HTTP method

This type of request uses the query string to calculate the signature. Take into account that the "?" character must not be included while calculating the signature.

For example, for the request with query string: ?foo=bar the signature calculated using sec_12345 as the private key would be 88d64dfcb542c35dc22bae059bd5f5a5d038572a7b391dfc4cd5f3a5530c1760 which is the hash for the string "foo=bar"

To generate the signature of a GET request without any parameters, simply encode an empty string.

Security

The API uses asymmetric cryptography to authenticate requests using the API keys we provide. This provides the following assurances:

  • Requester identification: Every request requires your public key to be sent, in conjunction with a signature generated with your secret key.
  • Protection against man-in-the-middle (MITM) attacks: The request signature is calculated using the body of the request, which means that any request that has been tampered with during the transport will be rejected by the Currency Alliance platform, since the signature received will not match the request contents.

The API only supports requests over HTTPS.

Idempotency

The API supports idempotent requests to safely retry requests without having to worry about doing the same operation more than once. For example, if there's a connection error generating a gift card, you can retry the request with the same idempotency key without having to worry about creating multiple gift cards.

To send an idempotent request, include an additional Idempotency-Key: <key> header in the request. An Idempotency Key <key> is a unique identifier generated by the client with a length between 1 and 255 characters. While this can be any type of unique key, we recommend a UUID to avoid collisions. An Idempotency key expires 8 hours after the initial request.

In a repeated request the response will always have the response body of the original request, along with the same status and 400 errors, if any. The response will also include the header Idempotency-Repeated: true. In the rare instances where a request is repeated while the first one has not been completed yet, the API will respond with a 409 - Conflict status.

The API supports idempotency on POST and PATCH requests. Since GET, PUT and DELETE are idempotent by default, the Idempotency-Key header will be ignored.

Common Use cases

Our API can be used for numerous Loyalty Commerce use cases. Some of the most common use cases are mentioned below along with the information on which Endpoints to use for each use case. There are auxiliary Endpoints that could be used to enhance your integration and customer experience. For example, you could pull all transaction history out via the API into your Business Intelligence or data staging environments or you could validate the member details before issuing Loyalty Currency Units.

Accrual/Issue/Top-up

The underlying objective of this use case is to “give Loyalty Currency Units to a member” for one reason or another. The reason could be a purchase of a product, their birthday, completion of a survey, referral, customer service issue, etc. Furthermore, you may want to give the member units of your own Loyalty Currency or one of your Partners’ Loyalty Currency.

You should use Accruals Endpoints for this use case. There are three Endpoints that can be used for issuing your or a Partner’s currency. You can use any one of the Endpoints or a combination of them to issue Loyalty Currency Units to the member.

Direct Accruals

This Endpoint is to be used when you know the exact number of Loyalty Currency Units to give to a member. In this scenario, you are calculating the number of Loyalty Currency Units in your environment and providing the exact number of units in the endpoint.

Purchase Rules

This Endpoint is to be used when you would like to give the number of Loyalty Currency Units based on Purchase Rule(s) defined in the Currency Alliance system. For example, giving points worth 1% of the fiat transaction amount. In this case, your application does not need to know how to calculate the number of Loyalty Currency Units or even the cost of the Loyalty Currency Units in any of your Partners' programs.

Activity Rules

This Endpoint is to be used when you would like to issue the number of Loyalty Currency Units based on pre-defined Activity Rule(s) in the system. For example, you might offer 200 points for posting a product review or referring a friend.

Currency Exchange

Our API provides tools for quick collaboration among brands to enable their respective members to exchange loyalty units between programs. The exchange could be one-way only, or both directions – in and out – of the programs. Use the Loyalty Currency Exchange Endpoints to implement this use case. There are 2 Endpoints that can be used to enable exchange between partners.

Simulate an exchange

This Endpoint allows you to simulate how many Loyalty Currency units the member would receive of a Partner’s Loyalty Currency in exchange. This can be used to show the member how many points in one or more programs they could get if completing the exchange.

Execute an exchange

This Endpoint allows you to comlete the exchange Loyalty Currency units to the Partner’s Loyalty Currency.

Tip: You could use the Partners Endpoints to get the list of Exchange Partners and automatically display the fields required for each program to complete the exchange. This will be necessary for loyalty programs that require more member validation fields than just the membership number.

Redemption/Pay with Points

Our Redemption Endpoints have standardized the redemption process across various types of loyalty programs and underlying loyalty systems. This shields you from needing to understand the underlying complexity to integrate into a new loyalty system or modifying the existing integration for a different set of parameters for a new partner.

You should use Standard Redemption Endpoints for this use case. There are four Endpoints that can be used for allowing a Partner’s Loyalty Currency as a form of payment. You can use any one of the Endpoints or a combination of them depending on your customer journey. Although not necessary, we highly recommend you use the “Lookup a Member” Endpoint to validate if the member exists and if they have enough balance to complete the payment before submitting the payment transaction.

Strictly speaking, Loyalty Exchange and Exchange for Gift Cards are also redemptions, but we provide explicit Endpoints for those actions due to the very high occurrence of those use cases in the industry. Standard Redemptions refers to any other redemptions where the Partners have allowed the member to redeem (exchange) their Loyalty Currency Units for your Products and Services. The products and services may range from flower delivery to booking a trip, buying an insurance plan, topping up their mobile plan, paying at a restaurant, buying concert tickets, or even applying points toward the purchase of a car.

Simulate a Redemption

To simulate the redemption action and provide information to the member such as the number of points required to complete the action, cancellation allowed, etc. without actually deducting the points from their balance or completing the transaction.

Execute a Redemption

Deduct points from the member’s account in exchange for the product or service offered.

Adjust a Redemption

If allowed by the Partner, you may use this Endpoint to notify of any modification in an already completed Redemption. The system will automatically identify if more points are to be redeemed or points are to be refunded to the member.

Cancel a Redemption

If allowed by the Partner, you may use this Endpoint to cancel an already completed Redemption to refund the points.

Members

Member Endpoints can be used to create a new member, look up information on a member, retrieve a member's details to your system, or update any member's details. Only the Currency Owner i.e. the loyalty program to which the member belongs has access to create a member or update a member.

The Partners could look up a member to confirm if the member exists, check the member account balance, or other details of the member record based on permissions granted by the Currency Owner.

Currency Alliance has standardized these Endpoints and orchestrates the calls to various Loyalty programs to validate a member, get member details, etc. if the Currency Alliance platform is not the primary data store for the relevant loyalty program.

The Member object

The Member Object represents a member record. For the loyalty programs where Currency Alliance is not the primary data store for their members, the system will connect with the loyalty program system to fetch the member information and present it in the following format.

additional_information
object
address_line1
string

Address line 1 (e.g. building, apartment, suite, unit, street)

address_line2
string

Address line 2 (e.g. community, neighborhood)

balance
integer

Member’s balance in number of Loyalty Currency Units. The field will be null if the Currency Owner has not granted access to member’s balance.

birth_date
string <YYYY-MM-DD>

Member’s date of birth

city
string

City, district, suburb, town, or village.

country
string

ISO 3166-1 alpha-3 of the country

email
string

Member’s email address

first_name
string

Member’s First Name

gender
string
Enum: "male" "female" "other"
id
string

Unique internal Currency Alliance identifier generated by the system for each member.

last_name
string

Member's Last Name

loyalty_currency
string

This unique identifier represents the loyalty program currency to which the member belongs. It is a unique shortcode Identifier assigned by the system to each loyalty currency. It can be found in the 'My Currency' section under the 'About My Currency' screen in the Management Dashboard. For the Currency Identifier of your partners' currencies refer to the Currency Symbol field in the 'My Partners' section in the Management Dashboard or Endpoints to obtain Partners' information.

loyalty_program_identifiers
object

This parameter requires you to send the loyalty_program_identifiers of the member. Each Loyalty Program may have a different set of identifiers that together uniquely identifies a member. For example, one loyalty program may only require the membership id but another loyalty program may require a combination of membership id and last name.

phone_number
string

Member's contact number.

postal_code
string

ZIP or postal code.

state
string

State, county, province, or region.

object
{
  • "additional_information": null,
  • "address_line1": "3532 Hidden Valley Road",
  • "address_line2": "Williamsburg, Brooklyn",
  • "balance": 38250,
  • "birth_date": "2000-01-01",
  • "city": "New York City",
  • "country": "USA",
  • "email": "foo@bar.com",
  • "first_name": "Barbara",
  • "gender": "female",
  • "id": "mp_abc123",
  • "last_name": "Drennen",
  • "loyalty_currency": "EXAMPLE_POINTS",
  • "loyalty_program_identifiers": {
    • "id": "M12334532"
    },
  • "phone_number": "+443031237300",
  • "postal_code": "011219",
  • "state": "New York",
  • "tier": {
    • "id": "gold",
    • "level": 1,
    • "name": "gold"
    }
}

Create a member

This Endpoint is only accessible by Currency Owners to create a member record if Currency Alliance is the main points bank i.e. the single source of truth for the loyalty program.

Each member object is associated with one loyalty currency. Thus, the same person associated with two different loyalty programs would have two member objects, each with a different corresponding loyalty_program_identifiers and loyalty_currency.

An important attribute is returned in all successful responses - loyalty_program_identifiers, which is a unique internal identifier for a member object across the entire Currency Alliance platform.