{
  "aid": "currencyalliance.com:main-3.0",
  "name": "Currency Alliance API Documentation",
  "type": "Index",
  "description": "# Introduction\n\nThe Currency Alliance API facilitates various use cases for Loyalty Commerce. Our API allows our Partners to:\n - Manage Loyalty Currencies in the Cloud\n - Access Popular Loyalty Currencies from other Brands\n - Sell and Distribute your Loyalty Currency to Partners\n - Issue, Transfer, Redeem, or Exchange any loyalty currency via API\n - Pull Transaction History Details into 3rd Party Platforms\n - Enable the Exchange of Loyalty Currencies into Gift Cards and other Redemption Products in many fiat currencies\nTo 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.\n\n# Architecture\nThe 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.\n\nCalls 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.\n\nThe 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.\n\n# Authentication\nThe API authenticates every request based on two elements - Credential and Signature. Every request must include an `Authorization` header with the following two elements.\n`Credential=<public-key>, Signature=<calculated-signature>`\n\n## Credential\nIn 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.\n\n## Signature\n### How is the Signature calculated?\n  The signature is a [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) hash in hexadecimal of the request content, using the `private_key` as the key.\n  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.\n\n### POST/PUT/PATCH HTTP methods\n  These types of requests use the string representation of the body to calculate the signature.\n\n  For example, for the request with body: `{\"foo\": \"bar\"}` the signature calculated using `sec_12345` as the private key would be `4d84ba663b9c6179dd98023087da5baa8a4e3eb59ba45284935261350ba70742`\n\n### GET HTTP method\n  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.\n\n  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\"\n\n  To generate the signature of a GET request without any parameters, simply encode an empty string.\n\n# Security\nThe API uses asymmetric cryptography to authenticate requests using the API keys we provide. This provides the following assurances:\n  - **Requester identification:** Every request requires your public key to be sent, in conjunction with a signature generated with your secret key.\n  - **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.\n\nThe API only supports requests over HTTPS.\n\n# Idempotency\nThe API supports [idempotent](https://en.wikipedia.org/wiki/Idempotence) requests to safely retry requests without having to worry about doing the same operation more than once.\nFor 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.\n\nTo 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.\n\nIn 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.\n\nThe API supports idempotency on POST and PATCH requests. Since GET, PUT and DELETE are idempotent by default, the `Idempotency-Key` header will be ignored.\n\n\n# Key fields\nCurrency Alliance acts as a connectivity bridge between various partners using its standardized APIs and interface, hence, shielding each partner from the complexity, nuances, and customizations of hundreds of loyalty systems and merchant partners. However, the interacting partners need to have a common reference for a transaction in their own system for easy reconciliation as well as for customer support purposes.\nIn this section, you will find information on some key fields and attributes that are used through our API and on different objects. This information will help you understand how to use these key fields.\n\n## External Reference\nThe field `external_reference` is used for each transaction request to provide a unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field.\n\n## Loyalty System Id\nThe field `loyalty_system_id` is returned by our system on each transaction and it provides the unique identifier in the partner loyalty system. This ID is not generated by Currency Alliance but is provided by the partner loyalty program and hence could be used as a common field for reconciliation between your system and the partner's system.\n\n## Loyalty System Data\nSometimes, a loyalty program requires you to send some additional data to connect. For example, user_id, application_id, partner_code, etc. You will be able to provide the data in this field for all the transactions with the partner loyalty program. To check if and what additional data is required by the partner loyalty program, refer to the Partners Endpoint.\n\n\n# Common Use cases\nOur 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.\n\n## Accrual/Issue/Top-up\nThe 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.\n\nYou 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.\n\n### Direct Accruals\nThis 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.\n\n### Purchase Rules\nThis 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.\n\n### Activity Rules\nThis 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.\n\n## Currency Exchange\nOur 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.\n\n### Simulate an exchange\nThis 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.\n\n### Execute an exchange\nThis Endpoint allows you to comlete the exchange Loyalty Currency units to the Partner’s Loyalty Currency.\n\n**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.\n\n## Redemption/Pay with Points\nOur 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.\n\nYou 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.\n\nStrictly 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.\n\n### Simulate a Redemption\nTo 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.\n\n### Execute a Redemption\nDeduct points from the member’s account in exchange for the product or service offered.\n\n### Adjust a Redemption\nIf 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.\n\n### Cancel a Redemption\nIf allowed by the Partner, you may use this Endpoint to cancel an already completed Redemption to refund the points.\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/currencyalliance.com/main/3.0/apis.json",
  "tags": [
    "currencyalliance.com",
    "main"
  ],
  "created": "2026-04-01",
  "modified": "2026-04-01",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "currencyalliance.com:main-3.0",
      "name": "Currency Alliance API Documentation",
      "description": "# Introduction\n\nThe Currency Alliance API facilitates various use cases for Loyalty Commerce. Our API allows our Partners to:\n - Manage Loyalty Currencies in the Cloud\n - Access Popular Loyalty Currencies from other Brands\n - Sell and Distribute your Loyalty Currency to Partners\n - Issue, Transfer, Redeem, or Exchange any loyalty currency via API\n - Pull Transaction History Details into 3rd Party Platforms\n - Enable the Exchange of Loyalty Currencies into Gift Cards and other Redemption Products in many fiat currencies\nTo 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.\n\n# Architecture\nThe 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.\n\nCalls 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.\n\nThe 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.\n\n# Authentication\nThe API authenticates every request based on two elements - Credential and Signature. Every request must include an `Authorization` header with the following two elements.\n`Credential=<public-key>, Signature=<calculated-signature>`\n\n## Credential\nIn 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.\n\n## Signature\n### How is the Signature calculated?\n  The signature is a [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) hash in hexadecimal of the request content, using the `private_key` as the key.\n  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.\n\n### POST/PUT/PATCH HTTP methods\n  These types of requests use the string representation of the body to calculate the signature.\n\n  For example, for the request with body: `{\"foo\": \"bar\"}` the signature calculated using `sec_12345` as the private key would be `4d84ba663b9c6179dd98023087da5baa8a4e3eb59ba45284935261350ba70742`\n\n### GET HTTP method\n  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.\n\n  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\"\n\n  To generate the signature of a GET request without any parameters, simply encode an empty string.\n\n# Security\nThe API uses asymmetric cryptography to authenticate requests using the API keys we provide. This provides the following assurances:\n  - **Requester identification:** Every request requires your public key to be sent, in conjunction with a signature generated with your secret key.\n  - **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.\n\nThe API only supports requests over HTTPS.\n\n# Idempotency\nThe API supports [idempotent](https://en.wikipedia.org/wiki/Idempotence) requests to safely retry requests without having to worry about doing the same operation more than once.\nFor 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.\n\nTo 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.\n\nIn 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.\n\nThe API supports idempotency on POST and PATCH requests. Since GET, PUT and DELETE are idempotent by default, the `Idempotency-Key` header will be ignored.\n\n\n# Key fields\nCurrency Alliance acts as a connectivity bridge between various partners using its standardized APIs and interface, hence, shielding each partner from the complexity, nuances, and customizations of hundreds of loyalty systems and merchant partners. However, the interacting partners need to have a common reference for a transaction in their own system for easy reconciliation as well as for customer support purposes.\nIn this section, you will find information on some key fields and attributes that are used through our API and on different objects. This information will help you understand how to use these key fields.\n\n## External Reference\nThe field `external_reference` is used for each transaction request to provide a unique identifier from your system that can be used as a reference during the reconciliation process. This could be a GUID, internal transaction identifier, invoice number, booking number, itinerary number, or any other unique number in your system that can be used to uniquely identify the action. Even though this is not a required field, it is strongly recommended that you provide value in this field.\n\n## Loyalty System Id\nThe field `loyalty_system_id` is returned by our system on each transaction and it provides the unique identifier in the partner loyalty system. This ID is not generated by Currency Alliance but is provided by the partner loyalty program and hence could be used as a common field for reconciliation between your system and the partner's system.\n\n## Loyalty System Data\nSometimes, a loyalty program requires you to send some additional data to connect. For example, user_id, application_id, partner_code, etc. You will be able to provide the data in this field for all the transactions with the partner loyalty program. To check if and what additional data is required by the partner loyalty program, refer to the Partners Endpoint.\n\n\n# Common Use cases\nOur 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.\n\n## Accrual/Issue/Top-up\nThe 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.\n\nYou 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.\n\n### Direct Accruals\nThis 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.\n\n### Purchase Rules\nThis 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.\n\n### Activity Rules\nThis 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.\n\n## Currency Exchange\nOur 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.\n\n### Simulate an exchange\nThis 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.\n\n### Execute an exchange\nThis Endpoint allows you to comlete the exchange Loyalty Currency units to the Partner’s Loyalty Currency.\n\n**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.\n\n## Redemption/Pay with Points\nOur 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.\n\nYou 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.\n\nStrictly 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.\n\n### Simulate a Redemption\nTo 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.\n\n### Execute a Redemption\nDeduct points from the member’s account in exchange for the product or service offered.\n\n### Adjust a Redemption\nIf 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.\n\n### Cancel a Redemption\nIf allowed by the Partner, you may use this Endpoint to cancel an already completed Redemption to refund the points.\n",
      "image": "",
      "baseURL": "https://api.currencyalliance.com/public/v3.0",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/currencyalliance.com/main/3.0",
      "version": "3.0",
      "tags": [
        "currencyalliance.com",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/currencyalliance.com/main/3.0/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/currencyalliance.com/main/3.0"
        }
      ]
    }
  ]
}