Introduction

Welcome to the Raise API documentation. The Raise API is a powerful tool that enables businesses to integrate digital gift cards seamlessly into their existing business model.

With the Raise API, businesses can instantly drive customer loyalty and reward customers, vendors, and employees while enjoying the flexibility and cost savings of a digital gift card program.

Getting started

Our Playground Environment

Our playground environment is publicly accessible and can be utilized for a Proof of Concept integration prior to any formal agreements being made. We have a Postman collection available upon request that can be provided by your account manager.

You can start playing with the API in Playground. You don't need to register to use the playground.

Our Sandbox & Production Environments

To start using the API please Contact Support to request more information. Your account manager will walk you through the process of getting further access.

Once you have the Client ID and Client Secret, you can start using the API.

You can use the Sandbox environment for testing and development purposes. After you have tested your integration, you can use the Production environment for production purposes.

Obtain Client ID and Client Secret

Contact your account manager to obtain the Client ID and Client Secret to authenticate your requests.

Authenticate requests

Required Headers

| Header      | Value       |
| ----------- | ----------- |
| X-Client    | Client UUID |
| X-Timestamp | Timestamp   |
| X-Signature | Signature   |

To use the Raise API, you must have an Account and a Client ID. If you do not have an account, please contact Raise API Support

To successfully make an API call, you need to authenticate the request. Each request must contain specific headers:

Required Headers

Let's take a look at each header in detail.

X-Client

Use the CLIENT_ID you received from your account manager.

X-Timestamp

Getting the current timestamp

const timestamp = Math.floor(Date.now() / 1000);

Timestamp is the current UTC represented as Unix timestamp.

X-Signature

The value of the X-Signature header is dynamic, and you need to generate it programmatically. Essentially this is a SHA256 hash based on the request details.

To calculate a valid signature, you should combine the following fields.

• Path of the request. (e.g. business/v1/cards)
• Timestamp (Same as X-Timestamp header)
• CLIENT_SECRET (Get this value from your account manager)
• Query parameter values (e.g., 50 from page[number]=50)
• Field values of the request body. You have to take all the values under the attributes field.

Creating a signature is tricky. Let's take an example to understand how to create a signature.

Example: Create signature for a request

Example request

Method: POST
Endpoint: business/v1/cards

Request body

{
  "data": {
    "type": "cards",
    "attributes": {
      "brand_uuid": "1bfd8967-f3fb-4efa-939e-f969d1db4b8a",
      "denomination": 3000,
      "buyer": {
        "external_id": "user_id_1234",
        "email": "buyer@raise.com"
      },
      "metadata": {
        "purchase_source": {
          "kind": "STRING",
          "value": "This item was purchased on Web"
        }
      }
    }
  }
}

Let's say you want to create a card. To do that, you need to send a POST request to the business/v1/cards endpoint. The request body contains all the required fields.

Step 1: Gather all required fields

Step 1: Gather all required fields

const path = "business/v1/cards";
const timestamp = Math.floor(Date.now() / 1000);
const CLIENT_SECRET = "YOUR_OWN_CLIENT_SECRET";

const fields = [
  path,
  timestamp,
  CLIENT_SECRET,

  // all fields below are extracted from the request body (if it's a POST or a PUT request)
  "1bfd8967-f3fb-4efa-939e-f969d1db4b8a", // -> brand_uuid
  3000, // -> denomination
  "user_id_1234", // -> external_id
  "buyer@raise.com", // -> email
  "STRING", // -> kind
  "This item was purchased on Web", // -> value
];

First, gather all values in an array,

Mandatory Fields:

• Path of the request. (e.g. business/v1/cards)
• Timestamp (Same as X-Timestamp header)
• CLIENT_SECRET (Get this value from the developer section of the client portal)

Optional Fields:

• Query parameter values (e.g., 50 from page[number]=50)
• Field values of the request body. You have to take all the values under the attributes field.

Tips: How to get all field values

How to get all field values

function getValues(obj) {
  let values = [];
  for (let key in obj) {
    if (typeof obj[key] === "object") {
      values = values.concat(getValues(obj[key]));
    } else {
      values.push(obj[key]);
    }
  }
  return values;
}

const values = getValues(requestBody.data.attributes);

As the request body is dynamic and can have nested objects, You can use a recursive approach to get all values.

Special Case: Query Parameters

Request with Query Parameters

GET business/v1/brands?page[number]=1&page[size]=5

Fields array for a request with query parameters

const path = "business/v1/brands";
const timestamp = Math.floor(Date.now() / 1000);
const CLIENT_SECRET = "YOUR_OWN_CLIENT_SECRET";

const pageNumber = 1; // the value of page[number] query parameter
const pageSize = 5; // the value of page[size] query parameter

const fields = [path, timestamp, CLIENT_SECRET, pageNumber, pageSize];

We are not including the request body attributes as this is a GET request.

The contents of the field array are slightly different if the request has query parameters.

For example, if you want to list all brands, you need to send a GET request to the business/v1/brands endpoint. The request has two optional query parameters: page[number] and page[size].

If the request has query parameters, you must extract the values from the query parameters.

Step 2: Sort and join the values

Step 2: Sort the values alphabetically, and join them by ";" .

fields = fields.sort();
const request = fields.join(";");

Then, sort the values alphabetically and join them by ";"

Step 3: Generate the signature

Step 3: Generate the signature

const signature = "v1:" + CryptoJS.SHA256(request).toString(CryptoJS.enc.Hex);

Finally, create the SHA256 value of the request, and append v1: with it.

Now you must pass this signature as the value of X-Signature header.

Make the request

Make a request. (Using curl)

curl --location --request POST 'https://sandbox-commerce-api.raise.com/business/v1/cards' \
--header 'X-Client: CLIENT_ID' \
--header 'X-Signature: REQUEST_SIGNATURE' \
--header 'X-Timestamp: TIMESTAMP' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "cards",
    "attributes": {
      "brand_uuid": "1bfd8967-f3fb-4efa-939e-f969d1db4b8a",
      "denomination": 3000,
      "buyer": {
        "external_id": "user_id_1234",
        "email": "buyer@raise.com"
      },
      "metadata": {
        "purchase_source": {
          "kind": "STRING",
          "value": "This item was purchased on Web"
        }
      }
    }
  }
}'

Now you have the signature value of the request, and we are ready to make the API call to create a card.

General Overview

This is a living document intended to help you enjoy working with the Raise API .

The Raise API is organized around REST.

All responses will be in JSON. Input data passed through the request body will be form-encoded or JSON-encoded. If using a JSON body, please specify the Content-Type header as application/json.

Workflow

To use Raise API, you must register your company as one of our business clients.

Each Client has a unique CLIENT_ID and CLIENT_SECRET.

You use these credentials to authenticate your requests.

Dictionary

Common definitions of systems and objects used across the API.

Portal

Once you register your company, you can access the Client Portal. It provides access to both business level statistics and the Client API secrets.

Environments

Raise provides three environments for testing and development purposes.

Playground

You can use the playground environment without registering. We provide a fixed set of credentials to use this API. We have a Postman collection available here.

Playground Credentials

To use the playground environment, you can use the following credentials:

Refer to the Authentication section to learn how to use these credentials to generate the X-Timestamp and the X-Signature headers and make an authenticated request to the API.

Characteristics

• It returns mocked responses for all endpoints.
• Authorization is based on public credentials.

Sandbox

Registered Clients use the Sandbox environment for testing and development purposes. In Sandbox, all operations and data are production-like.

Credentials

To use the sandbox environment, please visit Getting Started. Manage your sandbox credentials by visiting the Raise Sandbox Portal.

Characteristics

• The value of the card minus commissions and fees will be deducted from your sandbox account balance.
• The sandbox environment returns real responses but doesn't generate real gift cards.

Production

Registered Clients use the production environment for production purposes.

Credentials

To use the production environment, please visit Getting Started. Manage your production credentials by visiting the Raise Client Portal.

Characteristics

• The value of the card minus commissions and fees will be deducted from your account balance which can be managed in the Raise Client Portal.
• Requests will generate real gift cards

API Overview

Authentication

For successful authentication, you need to send the following headers with each request.

Refer to the Authentication and Authorization section for more details.

Request Structure

Example request body

{
  "data": {
    "type": "resource_type",
    "attributes": {
      //.. mandatory fields
    }
  }
}

Raise API follows a consistent request structure.

Normal Request Body

The usual request body has a data object with two keys.

• type - The name of the resource you are trying to access. Example: cards, brands, orders, etc.
• attributes - the fields you are trying to update or create.

Request Body with Metadata

Example request body with metadata

{
  "data": {
    "type": "resource_type",
    "attributes": {
      //.. mandatory fields

      "metadata": {
        //.. key-value pairs
      }
    }
  }
}

Metadata is a key-value store that can be used to store additional information about a resource.

The metadata is stored as a JSON object. The keys are strings, and the values are objects with a kind and a value field.

Refer to the metadata section for more information.

Response Structure

Raise API follows a consistent and predictable response structure.

Normal Response Body

Example response body

{
  "data": {
    "type": "resource_type",
    "attributes": {
      //.. mandatory fields
    }
  }
}

The response body is a JSON object with a data field. The data field is an object with a type and an attributes field.

The type field is the name of the resource you are trying to access. The attributes field is what you are trying to update or create.

Array Response Body

Response body for a list of objects

{
  "data": [
    {
      "type": "resource_type",
      "attributes": {
        //.. mandatory fields
      }
    },
    {
      "type": "resource_type",
      "attributes": {
        //.. mandatory fields
      }
    }
  ]
}

If the response returns a list of objects, the response body looks like

Metadata

Example of a single metadata object:

{
  "metadata": {
    "first_example_field": {
      "kind": "STRING",
      "value": "Customized string"
    }
  }
}

Example of multiple metadata objects:

{
  "metadata": {
    "first_example_field": {
      "kind": "STRING",
      "value": "Customized string"
    },
    "second_example_field": {
      "kind": "DATE",
      "value": "2020-05-22T12:33:00+0000"
    }
    // ... additional metadata fields (can be any number of fields).
  }
}

All of the endpoints in the API accept an optional metadata attribute in the request body. Metadata can be used to store additional information about the request.

metadata is defined as a single JSON object or a list of JSON objects,

Each JSON object will be keyed by field_name ( replace field_name with your desired custom name)

see metadata field name restrictions

The JSON object will also have the following attributes.

• kind - identifies the data type of the field value. (See the Supported Field Types).
• value- the value assigned to the field. (See the Supported Field Types).

Supported Field Types

The following table lists the available metadata field types:

Metadata Field Name Restrictions

Metadata field names can be any string value with the following restrictions:

• Metadata field names can contain only alphanumeric characters and underscores.
• Metadata field names cannot begin with an underscore.
• Metadata field names cannot exceed 64 characters in length.

Idempotency

The Raise API supports idempotency for all POST, PATCH, PUT, and DELETE requests.

What is Idempotency?

An idempotent API call produces the same result when called multiple times with the same parameters, enabling someone to execute the API call or operation multiple times without changing the result beyond the initial call.

For example, let's say that the CreateCard method did not require idempotency, and you make a successful request (i.e., Raise successfully creates a new card). However, your connection fails before you receive the success confirmation.

You don't know if the request was successful or not. If you retry the request, Raise will create another card, which is not ideal because you will end up with multiple cards for the same order.

Idempotency allows you to retry the request without creating a new card.

How Raise Supports Idempotency

Example Idempotency key generator (Using UUID)

const { v4: uuidv4 } = require("uuid");
const uuid = uuidv4();

Raise supports idempotency by allowing API operations to provide an optional idempotency key in the X-Client-Request header.

Optionality:

The X-Client-Request header is optional. The API will not check for idempotency if you don't provide it.

Uniqueness:

The key will be a unique alphanumeric string (with a maximum length of 64 characters). You are responsible for creating one.

Example request with idempotency key

curl --location --request POST '{BASE_URL}/business/v1/cards' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Signature: v1:6fc18229c3c1259624c551e101ffc3a4b5ea9046817c227b4e42fbe342bc5b15' \
--header 'X-Timestamp: 1610568277'
--header 'X-Client-Request: 268ad32d49c2c6d90e6432'

--data-raw '{
    //... request body
}'

Reusability:

To retry a request with the same payload, use the same key. The API will return the same response as the original request.

Once you use a key, it becomes invalid. So, you must use a new key whenever you make a new request with a different payload. In the case of the preceding example,

• If you make the same CreateCard request with the same idempotency key, the endpoint identifies it as a duplicate request and returns the same response as the original request.
• If you use the same idempotency key for a different request (for example, specify a different denomination), you get an error indicating that you already used the idempotency key previously.

The support for idempotency ensures that you can execute API calls and operations confidently, knowing that they will always return the same result regardless of the number of retries.

Versioning

The API supports versioning based on the URL path. The URL consists of the domain, the version, and the resource,

ex. https://sandbox-raise.com/business/v1/brands

The above URL means the requests will call version v1 of the brands' resources.

To change the version, replace v1 with the desired version.

Pagination

The Raise API supports pagination for all endpoints that return a list of resources.

Refer to the endpoints section for a list of endpoints that support pagination.

Pagination Parameters

Example URL for paginated data

'https://sandbox-commerce-api.raise.com/business/v1/brands?page[number]=1&page[size]=5'

Returns the brands on page 1, with five brands per page.

You must use query parameters to control the number of resources returned per page and the page number to return.

• page[size]: The number of resources to return per page.

• page[number]: The page number to return.

Pagination Links

Example response of paginated data

{
  "links": {
    "first": "https://sandbox-commerce-api.raise.com/business/v1/brands?page[number]=0&page[size]=5",
    "last": "https://sandbox-commerce-api.raise.com/business/v1/brands?page[number]=0&page[size]=5",
    "next": "https://sandbox-commerce-api.raise.com/business/v1/brands?page[number]=2&page[size]=5",
    "prev": "https://sandbox-commerce-api.raise.com/business/v1/brands?page[number]=0&page[size]=5"
  },
  "data": [
    // ... data
  ]
}

The API will return a links object in the response body containing links to the first, last, next, and previous results pages.

Errors

Any request that did not succeed will return a 4xx or 5xx error. The 4xx range means a problem with the request, like a missing parameter. The 5xx range means that something went wrong on our end.

Refer to the Error Response section for more information about the error response body.

Status codes

The API provides the following HTTP response status codes:

The status codes listed above are defined by RFC 9110

Error codes

The Raise API returns an error response, a combination of an HTTP response status code combined with a JSON response body containing a Raise Error Code and Error Description.

Error Response Body

Error response body

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeInvalidDeviceUUID",
      "title": "Missing device uuid"
    }
  ]
}

Multiple errors example:

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeBadRequest",
      "title": "Request is bad",
      "detail": "Invalid brand uuid in request"
    },
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66a123",
      "code": "ErrCodeInternal",
      "title": "Something went wrong"
    }
  ]
}

The errors field is an array of objects with the following fields:

Testing Integration

Successful integration requires a lot of testing. You must test for different scenarios and ensure the integration works as expected.

So before you go live, we recommend you test the integration in our sandbox environment.

The sandbox environment is a copy of the production environment. It allows you to test the integration without worrying about the security of the cards.

The CreateCard endpoint is an excellent place to start. We will use it to mimic different error scenarios and test the integration.

Simulate Card Generation Errors

Example request body to simulate a slow request for the create card API

{
  "data": {
    "type": "cards",
    "attributes": {
      "denomination": 1002
      // ... other fields
    }
  }
}

Response body for internal server error

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeInternal",
      "title": "Something went wrong, try again later.",
      "detail": "card generation failed"
    }
  ]
}

You can force the CreateCard API to behave in a certain way by passing a particular value in the denomination field in the request body.

1. Slow request

The card generation is almost instant.

If the value of the denomination field ends in 02 ( for example: "denomination": 1002), the request will be slower randomly between 2-20 seconds.

2. Internal error

If the value of the denomination field ends in 03 ( for example: "denomination": 1003), the request will fail with an internal error.

3. Context deadline timeout

If the value of the denomination field ends in 30 ( for example: "denomination": 1030), the request will fail with a context deadline timeout of 30 seconds.

Simulate Card Generation Scenarios

Example request body to create a card with an expiration date

{
  "data": {
    "type": "cards",
    "attributes": {
      "denomination": 1097
      // ... other fields
    }
  }
}

The process is the same as the one described in the Test Card Generation Errors section.

1. Card with an expiration date

If the value of the denomination field ends in 97 ( for example: "denomination": 1097), the response will include an expiration date on the created card.

2. Card without number

If the value of the denomination field ends in 98 ( for example: "denomination": 1098), the response will not include a number on the created card.

3. Card without csc

If the value of the denomination field ends in 99 ( for example: "denomination": 1099), the response will not include a csc on the created card.

400 Bad Request

Example request to produce a 400 error

{
  "data": {
    "type": "cards",
    "attributes": {
      "denomination": 1000
      // ... other fields
    }
  }
}

Response body for a bad request

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeBadRequest",
      "title": "Request is bad",
      "detail": "validating create card params: Denomination invalid, min: 2500, max: 50000, increment: 1"
    }
  ]
}

Each brand allows a certain range of denominations (for example, 2500-50000)

Pass a value outside this range (for example, 1000) to force a BadRequest with a 400 status code.

403 Forbidden

Response body for an unauthenticated request

{
  "errors": [
    {
      "id": "4f9dbc6b-dcb7-49aa-98ca-85163e68e404",
      "code": "ErrCodeUnauthenticated",
      "title": "Could Not Authenticate",
      "detail": "invalid signature"
    }
  ]
}

Pass an invalid X-Signature or missing X-Client header to receive an Unauthenticated error with the 403 status code.

If the signature is invalid, or the client is not authorized to access the API, the API will return this error. Refer to the Authentication section for more information.

409 Conflict

Response body for a duplicate request

{
  "errors": [
    {
      "id": "a6f0b73b-9232-45e5-8bd6-95851efef5df",
      "code": "ErrCodeConflict",
      "title": "Request already processed or in progress.",
      "detail": "Idempotency check failed"
    }
  ]
}

Pass a duplicate X-Client-Request header to receive a Conflict error with the 409 status code.

If the request is a duplicate, the API will return this error. Refer to the Idempotency section for more information.

404 Not Found

Example request body to produce a 404 error

{
  "data": {
    "type": "cards",
    "attributes": {
      "brand_uuid": "aaaaaaaa-aaaa-4444-aaaa-aaaaaaaaaaaa"
      // ... other fields
    }
  }
}

Response body for a not found error

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeNotFound",
      "title": "Requested object has not been found",
      "detail": "failed to get brand: sql: no rows in result set"
    }
  ]
}

Pass an invalid brand id inside the brand_uuid field of the request body to receive a NotFound error with 404 status.

Risk SDK

The Risk SDK enables the collection of device information and behavior biometrics during user sessions on your website.

The data collected is sent to Raise's systems for all device and user interactions on the website where the script is installed.

The information about an individual’s behavior and devices used to access the services helps identify potentially fraudulent transactions.

Integration Summary

You can install the script in two steps.

1. Integrate the script into your front end.
2. Call the create card API with some additional fields and headers.

Step 1: Install the Script

Script for the latest version:

<script>
  const clientId = "YOUR_CLIENT_ID";
  const sessionKey = "USER_SESSION_KEY";
  const isSandbox = false;
  var loader = document.createElement("script");
  loader.async = true;
  loader.src = `https://www.raise.com/static/risk/assets/sdk/raise-risk-sdk-latest.min.js`;
  loader.onload = function () {
    window._Raise.initialize({ clientId, sessionKey, isSandbox });
  };
  var s = document.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(loader, s);
</script>

To install the script on your website, you need three values.

1. clientId: Contact your account manager to get that.

2. sessionKey: Your sessionKey will be a UUID for the user session. This will be a server-generated short-lived key. You have to generate it yourself. You can use the uuid package to generate the UUID.

3. isSandbox: If you want to use the sandbox version of the script, set the isSandbox variable to true.

Next, copy the following script into your website's header section.

Using a specific version

By default, The script loads the latest version.

To use a specific version, you need to update the src of the script.

For example, If you want to use version 1.1.1 of the script:

Replace the following line in the script,

loader.src = https://www.raise.com/static/risk/assets/sdk/raise-risk-sdk-latest.min.js

with,

loader.src = https://www.raise.com/static/risk/assets/sdk/raise-risk-sdk-1.1.1.min.js

Pixel Integration

Script for the pixel integration

<noscript>
  <img
    src="https://www.raise.com/static/risk/assets/pixel/a.png?clientId=<REPLACE-ME>&sessionKey=<REPLACE-ME>&flow=<document.location>&ns=1"
    style="display: none"
  />
</noscript>

Adding a fallback pixel is necessary to ensure we capture all data since some users might attempt to disable Javascript on their browsers. This script is specifically designed to capture data for users who have disabled Javascript.

Copy the following code into the body section of your website.

Step 2: Modify the API request

After installing the script, you need to make some changes to the Create Card request.

1. Include details about the buyer inside the request.
2. Pass an additional header with the requests.

Populate Buyer Details

Request body for card creation:

{
  "data": {
    "type": "cards",
    "attributes": {
      "buyer": {
        "email": "Email address of the customer",
        "email_verified": true,
        "phone_number": "Phone number of the customer",
        "phone_number_verified": true
      }
      // ... other fields
    }
  }
}

You must include some details about the buyer inside the card creation request. An example request can look like the following.

Pass X-Session Header

Pass an additional header with your requests to complete the integration.

After you complete the integration, you can start using the Create Card endpoint. You need to wait some time for the data to be available in the Raise system.

Step 3: Verify the SDK implementation

1. A user session should start immediately upon landing on your website regardless of login status.
2. The same sessionKey should be persisted throughout the users session and should only be reset upon logout or close of the webpage.
3. The sessionKey should be passed in all requests to the API in the header as X-Session: sessionKey.
4. We recommend installing the script in your page header so it is present throughout the website to ensure the user journey and behaviors are properly tracked. If you choose not to put it in the header we recommend that at a minimum the script is present on the following pages:
   1. Login
   2. Sign up
   3. Account Management (where PII data can be updated)
   4. Payment Method Management
   5. All shopping and checkout pages

Objects

Brand

The Brand object describes a single brand. It will be returned by the brands endpoint.

SupportedFeature

CardValueConfig

The Card value config stores the available card configurations which are supported by the brand

RedemptionConfig

The Redemption config describes how the cards can be used

RedemptionKind

RedemptionMethod

RedemptionMethodKind

Category

The Category can be used for display purposes on Client's customer facing endpoint.

Card

Card is the definition of a Gift Card (the main object of the system).

Field

Field is a generic field with a name and a value attached.

BarcodeKind

A list of all supported barcode types:

• CODE128
• PDF417
• DATA_MATRIX
• QR_CODE
• PDF417_COMPACT

Barcode

Barcode contains the type and value of the barcode.

CardDetails

Card details holds more detailed information about the generated card. The details will always have at least one of the number, csc, and/or view_card_url fields populated.

CardBalance

Balance of the card returned by the card balances endpoint.

State

State represents the transaction state.

Person

Person represents the customer or end user. This is also known as the buyer in certain context.

Core Endpoints

Raise API is a set of public-facing endpoints that Raise uses to empower our Clients to build solutions around gift cards.

Raise API has some core API's that enables the client to build a gift card solution.

Brands

Brand is a gift card issuer. Raise API supports a wide range of brands.

List available brands

List all available brands

curl --location --request GET 'https://playground-api.raise.com/business/v1/brands' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Timestamp: 1598382330' \
--header 'X-Signature: v1:268ad32d49c2c6d90e663207da5e8b972fe031e89c7219055da216fefbfc5f6e'

GET /business/v1/brands

This endpoint returns a list of brands. Searching, filtering, sorting, and pagination are supported.

To list all available brands, you can call the endpoint directly, as shown in the example.

Get one brand

Get details of one brand

curl --location --request GET 'https://playground-api.raise.com/business/v1/brands/75433552-3e87-43bb-b792-1dbd31cc912f' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Timestamp: 1618508569' \
--header 'X-Signature: v1:036b972e39486136856fe0cb0d7dbe62aee2f8d52161462e7f3f9be07eb03cd0'

GET /business/v1/brands/:brand_id

It is possible to get one brand. To do this, please append the brand's ID to the URL, as shown in the example.

This endpoint supports filtering. You can filter results by using the query parameter. Below are some examples.

Get recommended brands

Get Top Trending Brands

curl --location --request GET 'https://playground-api.raise.com/business/v1/brands?recommended=TOP_SELLING' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Timestamp: 1618508569' \
--header 'X-Signature: v1:036b972e39486136856fe0cb0d7dbe62aee2f8d52161462e7f3f9be07eb03cd0'

To get Top Selling Brands, replace TOP_SELLING with TOP_TRENDING in the above example.

GET /business/v1/brands?recommended={type}

TOP_TRENDING

Returns brands showing a recent spike in sales volume due to brands' merchandising, sales, and promotional events.

Example - /business/v1/brands?recommended=TOP_TRENDING

TOP_SELLING

Returns brands that are top sellers, updated to reflect seasonal trends.

Example - /business/v1/brands?recommended=TOP_SELLING

Response

Sample response:

{
  "data": [
    {
      "type": "brands",
      "id": "754338c4-d3a9-446a-b1fc-de2ded7e1765",
      "attributes": {
        "brand_name": "BrandName",
        "icon_url": "https://www.raise.com/raise-content/ibi/BrandName-Logo.png",
        "legal_terms": "This card can be used to purchase merchandise only in stores",
        "physical_legal_terms": "This physical card can be used to purchase merchandise only in stores",
        "description": "Buy stuff, buy lots of it.",
        "card_value_config": {
          "increment": 1,
          "max_value": 50000,
          "min_value": 500,
          "variable_load_supported": true
        },
        "redemption_configs": {
          "disclaimer": "Can only use 2 cards",
          "kind": "IN_STORE_OR_ONLINE_ONLY",
          "methods": [
            {
              "kind": "ENTER_ONLINE",
              "info": "Enter the giftcard info online"
            },
            {
              "kind": "SHOW_BARCODE",
              "info": "Show the barcode to the cashier"
            }
          ]
        },
        "categories": [
          {
            "name": "ENTERTAINMENT"
          },
          {
            "name": "ELECTRONICS"
          },
          {
            "name": "COMPUTER_AND_SOFTWARE"
          }
        ]
      }
    }
    // .. more brands
  ]
}

The response will either contain

• A list of brands in the data field - if you requested a list of brands.
• A single object in the data field - if you requested a single brand.

Refer to the Response Structure for more information.

Pagination and sorting

This endpoint supports pagination, sorting, and searching operations.

Search

Pagination

Sorting

Categories

Categories are used to group brands together. For example, all brands that sell electronics are grouped under the ELECTRONICS category.

Get Categories

List all available categories

curl --location --request GET 'https://playground-api.raise.com/business/v1/categories' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Timestamp: 1598382330' \
--header 'X-Signature: v1:268ad32d49c2c6d90e663207da5e8b972fe031e89c7219055da216fefbfc5f6e'

To get Top Selling Brands, replace TOP_SELLING with TOP_TRENDING in the above example.

GET /business/v1/categories

This endpoint returns all brand categories.

Sorting

Response

Sample response:

{
  "data": [
    {
      "type": "categories",
      "id": "ENTERTAINMENT",
      "attributes": {
        "name": "Entertainment",
        "available_brands": 3
      }
    }
    // .. more categories
  ]
}

The response will contain a list of categories in the data field.

Cards

Cards are gift cards that can be purchased through Raise API.

Here is the list of the available methods:

• Create a new Card
• Get a single Card
• Get multiple Cards

Create Card

POST /business/v1/cards

Request object

curl --location --request POST 'https://playground-api.raise.com/business/v1/cards' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Signature: v1:6fc18229c3c1259624c551e101ffc3a4b5ea9046817c227b4e42fbe342bc5b15' \
--header 'X-Timestamp: 1610568277' \
--header 'Content-Type: application/json' \
--data-raw '{
    "data": {
        "type": "cards",
        "attributes": {
            "brand_uuid": "754338c4-d3a9-446a-b1fc-de2ded7e1765",
            "denomination": 2500,
            "buyer": {
                "external_id": "internalID",
                "email": "buyer@example.com"
            },
            "send_email": false,
            "metadata": {
                "purchase_source": {
                    "kind": "STRING",
                    "value": "This item was purchased on Web"
                },
                "user_local_time": {
                    "kind": "DATE",
                    "value": "2020-08-20T05:41:00+02:00"
                }
            }
        }
    }
}'

Cards endpoint allows for the creation of new Gift Cards.

This endpoint accepts a JSON object with the following fields:

Some fields require more details. See the sections below for more information.

Details of Buyer

You must include the buyer's details in the request. The endpoint accepts a JSON object with the following fields:

Response

Sample response

{
  "data": {
    "type": "cards",
    "id": "b837915b-903b-4666-92db-81d0a838dd4c",
    "attributes": {
      "id": "T43C3Q4WJALHS",
      "account_uuid": "fff75433-ffff-4fff-b625-acc0868fffff",
      "owner_uuid": "fff75433-ffff-4fff-b625-696e7fffffff",
      "brand_uuid": "754338c4-d3a9-446a-b1fc-de2ded7e1765",
      "denomination": 2500,
      "card": {
        "brand": {
          "brand_name": "BrandName",
          "icon_url": "https://www.raise.com/raise-content/ibi/BrandName-Logo.png",
          "legal_terms": "This card can be used to purchase merchandise only in stores",
          "physical_legal_terms": "This physical card can be used to purchase merchandise only in stores",
          "description": "Buy stuff, buy lots of it.",
          "card_value_config": {
            "increment": 1,
            "max_value": 50000,
            "min_value": 500,
            "variable_load_supported": true
          },
          "redemption_configs": {
            "disclaimer": "Can only use 2 cards",
            "kind": "IN_STORE_OR_ONLINE_ONLY",
            "methods": [
              {
                "kind": "ENTER_ONLINE",
                "info": "Enter the giftcard info online"
              },
              {
                "kind": "SHOW_BARCODE",
                "info": "Show the barcode to the cashier"
              }
            ]
          },
          "categories": [
            {
              "name": "ENTERTAINMENT"
            },
            {
              "name": "ELECTRONICS"
            },
            {
              "name": "COMPUTER_AND_SOFTWARE"
            }
          ]
        },
        "account_uuid": "fff75433-ffff-4fff-b625-acc0868fffff",
        "number": {
          "label": "number",
          "value": "LLC33GB9FAR4UHK"
        },
        "csc": {
          "label": "csc",
          "value": "value"
        },
        "barcode": {
          "kind": "code128",
          "value": "LLC33GB9FAR4UHK"
        },
        "view_card_url": {
          "label": "View Gift Card Details",
          "value": "https://www.vcdelivery.com/vcert/2f8c9db6-cc12-4898-af01-9a286034b1f8"
        },
        "balance": 2500,
        "archived": false,
        "expired": false,
        "commission": 50,
        "merchant_url": "www.merchant.com"
      },
      "state": 2,
      "buyer": {
        "external_id": "internalID",
        "email": "buyer@example.com"
      },
      "send_email": false,
      "commission": 50
    }
  }
}

The response object will contain details about the purchased card. The card object will contain the card details along with other fields.

Their is a special field called state which shows the status of the card. The possible values are:

The response object will contain the following fields:

The Card object contains details about the card. The card object will contain the following fields:

Get a single Card

Sample request to get a single card:

curl --location --request GET 'https://playground-api.raise.com/business/v1/cards/b837915b-903b-4666-92db-81d0a838dd4c?buyer.id=internalID' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Signature: v1:6fc18229c3c1259624c551e101ffc3a4b5ea9046817c227b4e42fbe342bc5b15' \
--header 'X-Timestamp: 1610568277'

GET /business/v1/cards/:card_id?buyer.id=buyer_internal_id

This functionality allows getting one card specified by the card's unique ID and the customer's ID passed in the request URL.

• card_id: The card's unique ID. It was returned from the response to Create Card request.

• buyer_internal_id: The customer's ID you passed in the buyers details to create the card.

Sample URL:
https://playground-api.raise.com/business/v1/cards/b837915b-903b-4666-92db-81d0a838dd4c?buyer.id=internalID

Get Multiple Cards

Sample request to get multiple cards:

    curl --location --request GET 'https://playground-api.raise.com/business/v1/cards?page[number]=0&page[size]=50&buyer.id=7081317710107280' \
    --header 'X-Client: 359e8708-ee2a-4deb-8c15-0e29fe934cda' \
    --header 'X-Timestamp: 1603793344' \
    --header 'X-Signature: v1:d5d19b2e0d0e63cc940bc5ff25443dd4900ea9e9fc6e7835a6c65488c1b5ee73'

GET /business/v1/cards?buyer.id=buyer_internal_id

This endpoint returns a list of gift cards for a given customer. You have to pass the customer's ID in the request URL.

The customer's ID is the same as the buyer's ID you passed in the buyers details to create the card.

Pagination

This endpoint supports pagination.

Pagination

Sample URL:
https://playground-api.raise.com/business/v1/cards?page[number]=0&page[size]=50&buyer.id=7081317710107280

Response

Sample response (multiple cards):

{
  "data": [
    {
      "type": "cards",
      "id": "b837915b-903b-4666-92db-81d0a838dd4c",
      "attributes": {
        "id": "T43C3Q4WJALHS",
        "account_uuid": "fff75433-ffff-4fff-b625-acc0868fffff",
        "owner_uuid": "fff75433-ffff-4fff-b625-696e7fffffff",
        "brand_uuid": "754338c4-d3a9-446a-b1fc-de2ded7e1765",
        "denomination": 2000,
        "card": {
          "brand": {
            "brand_name": "BrandName",
            "icon_url": "https://www.raise.com/raise-content/ibi/BrandName-Logo.png",
            "legal_terms": "This card can be used to purchase merchandise only in stores",
            "physical_legal_terms": "This physical card can be used to purchase merchandise only in stores",
            "description": "Buy stuff, buy lots of it.",
            "card_value_config": {
              "increment": 1,
              "max_value": 50000,
              "min_value": 500,
              "variable_load_supported": true
            },
            "redemption_configs": {
              "disclaimer": "Can only use 2 cards",
              "kind": "IN_STORE_OR_ONLINE_ONLY",
              "methods": [
                {
                  "kind": "ENTER_ONLINE",
                  "info": "Enter the giftcard info online"
                },
                {
                  "kind": "SHOW_BARCODE",
                  "info": "Show the barcode to the cashier"
                }
              ]
            },
            "categories": [
              {
                "name": "ENTERTAINMENT"
              },
              {
                "name": "ELECTRONICS"
              },
              {
                "name": "COMPUTER_AND_SOFTWARE"
              }
            ]
          },
          "account_uuid": "fff75433-ffff-4fff-b625-acc0868fffff",
          "number": {
            "label": "number",
            "value": "LLC33GB9FAR4UHK"
          },
          "csc": {
            "label": "csc",
            "value": "value"
          },
          "barcode": {
            "kind": "code128",
            "value": "LLC33GB9FAR4UHK"
          },
          "balance": 2000,
          "archived": false,
          "expired": false,
          "commission": 50
        },
        "state": 2,
        "buyer": {
          "external_id": "internalID",
          "email": "buyer@example.com"
        },
        "commission": 50
      }
    }
  ]
}

The response will either contain

• A list of cards in the data field - If you requested multiple cards.
• A single object in the data field - If you requested a single card.

Additional Endpoints

Raise API supports additional endpoints that can be used to enhance the gift card experience. Please work with your account manager on pricing and approval for these additional features.

Card Balance

Example request to get a card's balance

curl --location --request GET 'https://playground-api.raise.com/business/v1/card_balances/b837915b-903b-4666-92db-81d0a838dd4c' \
--header 'X-Client: fff75433-ffff-4fff-b625-c54e684dffff' \
--header 'X-Signature: v1:6fc18229c3c1259624c551e101ffc3a4b5ea9046817c227b4e42fbe342bc5b15' \
--header 'X-Timestamp: 1610568277'

Sample successful response:

{
  "data": {
    "type": "card_balances",
    "id": "c36d0958-7d3a-40c7-81a4-3f448e916b69",
    "attributes": {
      "card_uuid": "c36d0958-7d3a-40c7-81a4-3f448e916b69",
      "balance": 2502
    }
  }
}

Response after all balance checks has been used:

{
  "errors": [
    {
      "id": "ef1a745c-fe31-4df7-a9dd-5893aa66aefe",
      "code": "ErrCodeBadRequest",
      "title": "Request is bad",
      "detail": "balance checks depleted"
    }
  ]
}

GET /business/v1/card_balances/:card_id

This endpoint returns a card's current balance.

Check Card Balance

A sample request is a simple GET with the unique ID of the card created through /business/v1/cards endpoint.

Errors

The endpoint can return the following errors:

Use Cases

Let's get ourselves familiarized with the most common use cases of the Raise API. We'll be using the Raise API Sandbox to test out the API. The sandbox is a testing environment that allows you to test the API without affecting your production environment.

Use Case 1: Generate a Gift Card

This use case is the most common use case for the Raise API.

The process involves generating gift cards for various brands. Here are the three main steps:

Step 1:Retrieve Brands

GET /brands

The first step is to retrieve all available brands. This is done by sending a GET request to the /brands endpoint. The response will include a list of available brands that can be used to create gift cards.

Step 2: Generate Gift Card

POST /cards

The second step is to generate a gift card. To do this, you'll need to send a POST request to the /cards endpoint, along with the desired denomination (which is determined by the available denominations in the brand CardValueConfig object), and the Brand UUID (which you obtained from step 1).

The endpoint will generate a gift card based on the provided information and return a response containing the generated card object.

Step 3: Get Cards for Buyer

GET /cards

The third step is to retrieve all cards associated with a specific buyer. This is done by sending a GET request to the /cards endpoint, along with the buyer identifier that you set on the POST /cards endpoint when you generated the gift card.

The cards will return a list of all cards associated with that buyer. The endpoint also supports pagination, so you can retrieve the cards in batches if there are many of them.

Use Case 2: Get Card Balance

This use case is used to retrieve the balance of a gift card.

The process involves retrieving the balance of a gift card. Here are the two main steps:

Step 1: Retrieve Card

GET /cards/card_id

The first step is to retrieve the card. To do this, you'll need to send a GET request to the /cards/{card_uuid} endpoint, along with the card UUID. The endpoint will return a response containing the card object.

Step 2: Get Card Balance

GET /cards/card_balances/:card_id

The second step is to retrieve the balance of the card. To do this, you'll need to send a GET request to the /cards/{card_uuid}/balance endpoint, along with the card UUID. The endpoint will return a response containing the card object.

Changelog

Overview

Welcome to the Raise API documentation. The Raise API is a powerful tool that enables businesses to integrate digital gift cards seamlessly into their existing business model.

With the Raise API, businesses can instantly drive customer loyalty and reward customers, vendors, and employees while enjoying the flexibility and cost savings of a digital gift card program.

The Raise API is organized around REST. This documentation provides comprehensive guidance on how to interact with our RESTful API, which will always respond in JSON format. Our API allows developers to seamlessly integrate our services into their applications.

If you are a new client or a client migrating from v1 to v2, you can begin with your Initial Integration to get started.

Sandbox & Playground environments are available for testing and development purposes, which doesn’t affect your live data. For more information, refer to the Raise Environments section.

REST

Our API is built on REST principles, providing a standardized approach for communication between clients and servers over the web. By leveraging HTTP methods and status codes, developers can perform CRUD (Create, Read, Update, Delete) operations on resources in a consistent and intuitive manner.

OAuth 2.0 Authentication

The Raise API utilizes OAuth 2.0 for authentication. To authenticate your requests, you will use the Tokens Resource to obtain your token which you will utilize on on all subsequent API calls.

Requests

EXAMPLE REQUEST

{
  "data": {
    "type": "resource_type",
    "id": "resource_id",
    "attributes": {
      //.. fields
    }
  }
}

Raise API follows a consistent request structure.

The usual request body has a data object with two keys.

• type - The name of the resource you are trying to access. Example: cards, brands, orders, etc.
• attributes - The fields you are trying to update or create.

Request with Metadata

EXAMPLE REQUEST WITH METADATA

{
  "data": {
    "type": "resource_type",
    "attributes": {
      //.. mandatory fields

      "metadata": {
        //.. key-value pairs
      }
    }
  }
}

Metadata is a key-value map that can be used to store additional information about a resource.

The metadata is stored as a JSON object in order to save dynamic details on the resource. The keys are strings, and the values are objects with a kind and value field.

Refer to the Transactions Resource for more information.

Responses

EXAMPLE

{
  "data": {
    "type": "resource_type",
    "id": "resource_id",
    "attributes": {
      //.. fields
    }
  }
}

Individual Response

Raise API follows a consistent and predictable response structure.

The response body is a JSON object with a data field. The data field is an object with a type and an attributes field.

The type field is the name of the resource you are trying to access. The attributes field is what you are trying to update or create.

List Response

EXAMPLE LIST RESPONSE

{
  "data": [
    {
      "type": "resource_type",
      "id": "resource_id_1",
      "attributes": {
        //.. fields
      }
    },
    {
      "type": "resource_type",
      "id": "resource_id_2",
      "attributes": {
        //.. fields
      }
    }
  ],
  "meta": {
    "total_results": 2
  }
}

Currency

Raise API supports multiple currencies. The default currency is USD. You can specify the currency in the request headers.

All amounts are an integer type in the appropriate subunit of the currency. For example, USD and EUR are in cents, GBP is in pence, etc.

The only exception to this are Crypto amounts are represented in floating-point numbers.

Initial Integration

Playground

You can start familiarizing yourself with the Raise API in Playground

Sandbox & Production Environments

To begin an official integration with our API please Contact Us to request more information. Your account manager will walk you through the process of getting further access.

The Sandbox environment is used for testing and development purposes utilizing a combination of test and mocked data.

The Production environment is used for live transactions and data.

Guide

To get started, you need to authenticate your requests.

Servers: Utilize the Tokens Resource to obtain your token which you will utilize on all subsequent API calls.

App/Web: Utilize the Auth Resource to obtain your token which you will utilize on all subsequent API calls.

We recommend that you integrate with the resources in the following order:

Raise Environments

Raise provides three environments for testing and development purposes.

Playground Environment

Our playground environment is publicly accessible and can be utilized for a Proof of Concept integration prior to any formal agreements being made. We provide a fixed set of credentials to use this API. A Postman collection is available here.

Playground Credentials

To use the playground environment, you can use the following credentials:

Refer to the Tokens Resource to learn how to use these credentials to make authenticated request to the API.

Characteristics

• It returns mocked responses for all endpoints.
• Authorization is based on public credentials.

Sandbox Environment

Registered Clients use the Sandbox environment for testing and development purposes. In Sandbox, all operations and data are production-like.

Credentials

To start using the sandbox environment, please visit Initial Integration to get started. Manage your sandbox credentials by visiting the Raise Sandbox Portal.

Characteristics

• If you maintain an account balance with Raise, the card value, along with associated fees minus commissions, will be deducted from your sandbox account balance. These funds do not need to be added manually. A virtual balance is automatically created for you.
• The sandbox environment returns real responses but doesn't generate real gift cards.

Production Environment

Registered Clients use the production environment for production purposes.

Credentials

Manage your production credentials by visiting the Raise Client Portal.

Characteristics

• If you maintain an account balance with Raise, the card value, along with associated fees minus commissions, will be deducted from your account balance. You can manage your account balance through the Raise Client Portal.
• Requests will generate real gift cards

Tokens Resource

Token Integration: Integrating with our OAuth2 "tokens" resource is seamless. Follow these steps to incorporate token handling into your application:

1. Authentication: Use your client ID and secret key to authenticate requests to the OAuth2 "tokens" endpoint.
2. Token Retrieval: Upon successful authentication, you'll receive an OAuth2 token from the "tokens" endpoint.
3. Token Usage: Incorporate the obtained token into subsequent API requests by including it in the Authorization header using the Bearer authentication scheme.
4. Token Renewal: Regularly refresh your tokens to maintain their validity prior to their expiration.
   • To refresh your token simply call the POST tokens to request a new token prior to the expiration of your last token. The current expiration time is 15 minutes. This duration may change in the future, therefore it is recommended to refresh your token prior to the expiration time provided.
   • Your token will remain active until the expires_at Unix timestamp in order to enable overlapping tokens.

POST Tokens

EXAMPLE POST TOKEN REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/tokens' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "tokens",
    "attributes": {
      "type": "BEARER"
    }
  }
}'

EXAMPLE POST TOKEN RESPONSE

{
  "data": {
    "type": "tokens",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
      "type": "BEARER",
      "expires_at": 1714494953
    }
  }
}

POST /business/v2/tokens

This endpoint returns a Bearer token that can be used to authenticate requests to the API.

Token Request

Token Type

POST Token Response

A successful response will have a data object that contains the Token Object.

Token Object

Token Attributes

Auth Resource

Key Pair Authentication

Key Pair authentication is a method that allows the mobile app to sign a nonce with the customer's private key which is then verified by Raise using the customer's public key.

EXAMPLE KEY PAIR POST AUTH METHODS REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/auth/methods' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-Country: US' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/methods",
    "attributes": {
      "type": "SR25519_KEY_PAIR",
      "method": "0x8ca7f551da8775159c2ac65b26e3efefad06e9676cbedc3fa05e2c3801b2b87e"
    }
  }
}'

EXAMPLE KEY PAIR POST AUTH METHODS RESPONSE

{
  "data": {
    "type": "auth/methods",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "type": "SR25519_KEY_PAIR", // or RSA_KEY_PAIR
      "nonce": "0x18b021c8d8de3ac1d1fd5500c034df9f5b94567893b70b62324c3e0a784521e4"
    }
  }
}

EXAMPLE TOTP POST AUTH METHODS REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/auth/methods' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-Country: US' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/methods",
    "attributes": {
      "type": "TOTP"
    }
  }
}'

EXAMPLE TOTP POST AUTH METHODS RESPONSE

{
  "data": {
    "type": "auth/methods",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "type": "TOTP",
      "qr_code_image": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAABaElEQVR42mL8//8/AyUY"
    }
  }
}

EXAMPLE SMS POST AUTH METHODS REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/auth/methods' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-Country: US' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/methods",
    "attributes": {
      "type": "SMS",
      "method": "2345678901"
    }
  }
}'

EXAMPLE SMS POST AUTH METHODS RESPONSE

{
  "data": {
    "type": "auth/methods",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "type": "SMS",
      "method": "2345678901"
    }
  }
}

New Key Pair Authentication

Existing Key Pair Authentication

SMS Authentication

SMS authentication is a method that allows customers to receive a verification code via SMS to authenticate themselves.

TOTP Authentication

TOTP authentication is a method that allows customers to receive a qr code image to be saved to an authenticator app, which generates timebound verification codes.

Auth Methods Resource

The auth methods endpoints are used to manage the authentication methods for a customer.

POST Auth Methods

POST /business/v2/auth/methods

This endpoint is used to create a new authentication method for a customer. An error will be returned if the customer already had an authentication method set. Depending on the method type use the appropriate request body SR25519 or RSA Key Pair Auth Method Request, SMS Auth Method Request or TOTP Auth Method Request.

POST Auth Methods Response

A successful response will have a data object that contains the Auth Methods Object.

Reference Error Response for a list of possible errors and their descriptions.

PATCH Auth Methods

EXAMPLE PATCH AUTH METHODS REQUEST

curl --location --request PATCH 'https://playground-api.raise.com/business/v2/auth/methods/fff75433-ffff-4fff-b625-c5423tk90d' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "auth/methods",
    "attributes": {
      "type": "TOTP"
    }
  }
}'

EXAMPLE PATCH AUTH METHODS RESPONSE

{
  "data": {
    "type": "auth/methods",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "type": "TOTP",
      "qr_code_image": "iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAABaElEQVR42mL8//8/AyUY"
    }
  }
}

PATCH /business/v2/auth/methods/:id

This endpoint is used to update the authentication method for a customer. Depending on the method type use the appropriate request body SR25519 or RSA Key Pair Auth Method Request, SMS Auth Method Request or TOTP Auth Method Request.

PATCH Auth Methods Response

A successful response will have a data object that contains the Auth Methods Object.

Reference Error Response for a list of possible errors and their descriptions.

Auth Methods Object

EXAMPLE SR25519 KEY PAIR GENERATION

const { schnorrkel } = require('@polkadot/util-crypto');

function generateKeyPair() {
  // Generate SR25519 key pair
  const { publicKey, secretKey } = await schnorrkel.generateKeypair();

  // Encode public key to hexadecimal string
  const srPublicKeyHex = publicKey.toString("hex");

  return { srPrivateKey: secretKey, srPublicKeyHex };
}

EXAMPLE RSA KEY PAIR GENERATION

const crypto = require("crypto");

// Function to generate RSA key pair and hex encode public key
function generateKeyPair() {
  const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", {
    modulusLength: 2048, // RSA key size in bits
    publicKeyEncoding: {
      type: "spki", // SubjectPublicKeyInfo (SPKI)
      format: "pem", // PEM format
    },
    privateKeyEncoding: {
      type: "pkcs8", // PrivateKeyInfo (PKCS#8)
      format: "pem", // PEM format
    },
  });

  // Encode public key to Hexadecimal
  const publicKeyHex = publicKey.toString("hex");

  // publicKeyHex will then be used as the `method` in the request body
  return { privateKey, publicKey: publicKeyHex };
}

Key Pair Auth Method Request

SMS Auth Method Request

TOTP Auth Method Request

Auth Methods Attributes

Auth Type

Verification Type

Auth Tokens Resource

Token Integration: Integrating with our OAuth2 auth resource is seamless. Follow these steps to incorporate token handling into your application:

1. Authentication: Use your client ID and secret key to authenticate requests to the OAuth2 "auth tokens" endpoint.
2. Ensure you include the ID of your customer in the request headers.
3. Token Retrieval: Upon successful authentication, you'll receive an OAuth2 token from the "auth tokens" endpoint.
4. Token Usage: Incorporate the obtained token into subsequent API requests by including it in the Authorization header using the Bearer authentication scheme.
5. Token Renewal: Regularly refresh your tokens to maintain their validity prior to their expiration.
   • To refresh your token simply call the POST auth refresh to request a new token prior to the expiration of your last token. The current expiration time is 6 months. This duration may change in the future, therefore it is recommended to refresh your token prior to the expiration time provided.
   • Your token will remain active until the expires_at Unix timestamp in order to enable overlapping tokens.

POST Auth Tokens

EXAMPLE SR25519 KEY PAIR NONCE SIGNING

const crypto = require("crypto");
const merlin = require("merlin");

function signChallenge(challengeNonce, privateKey) {
  // Decode challengeNonce from hexadecimal string
  const cn = Buffer.from(challengeNonce, "hex");

  // Create a new transcript
  const transcript = new merlin.Transcript("raise-auth");
  transcript.appendMessage(Buffer.from("challenge-nonce"), cn);

  // Sign the transcript with the private key
  const signature = privateKey.sign(transcript);

  // Encode the signature to hexadecimal string
  const sigHex = signature.toString("hex");

  return sigHex;
}

EXAMPLE RSA KEY PAIR NONCE SIGNING

function signChallenge(challengeNonce, privateKey) {
  const signer = crypto.createSign("RSA-SHA256"); // Use "RSA-SHA256" for RSA signatures
  signer.update(challengeNonce);
  const signature = signer.sign(privateKey, "hex");

  // The signature will be hex encoded, and should be used as the `signed_nonce` in the request body
  return signature;
}

EXAMPLE KEY PAIR GENERATE NONCE POST TOKEN REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/tokens' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-Country: US' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/tokens",
    "attributes": {
      "action": "GENERATE_NONCE"
    }
  }
}'

EXAMPLE KEY PAIR GENERATE NONCE POST TOKEN RESPONSE

{
  "data": {
    "type": "auth/tokens",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "type": "SR25519_KEY_PAIR",
      "nonce": "0x18b021c8d8de3ac1d1fd5500c034df9f5b94567893b70b62324c3e0a784521e4"
    }
  }
}

EXAMPLE KEY PAIR VALIDATE SIGNED NONCE POST TOKEN REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/tokens' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-Country: US' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/tokens",
    "attributes": {
      "action": "VALIDATE_VERIFICATION",
      "signed_nonce": "0x18b021c8d8de3ac1d1fd5500c034df9f5b94567893b70b62324c3e0a784asdfg"
    }
  }
}'

EXAMPLE SMS AND TOTP VALIDATE VERIFICATION POST TOKEN REQUEST

curl --location --request POST 'https://playground-api.raise.com/business/v2/tokens' \
-u 'client-id:sandbox-client-secret-string' \
--header 'Content-Type: application/json' \
--header 'X-CustomerID: 123456' \
--data-raw '{
  "data": {
    "type": "auth/tokens",
    "attributes": {
      "action": "VALIDATE_VERIFICATION",
      "code": "123456"
    }
  }
}'

EXAMPLE VALIDATE VERIFICATION & REFRESH POST TOKEN RESPONSE

{
  "data": {
    "type": "auth/tokens",
    "id": "fff75433-ffff-4fff-b625-c5423tk90d",
    "attributes": {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
      "type": "BEARER",
      "expires_at": 1714494953
    }
  }
}

POST /business/v2/auth/tokens

The initial request to this endpoint with the correct type set will send a verification to the customer's authentication method. The customer will receive a verification code that they will need to provide in the next request to the POST Auth Tokens endpoint.

For customers with a TOTP method, the code should be set on the initial request. Which will then return the token in the response.

This endpoint returns a Bearer token that can be used to authenticate requests to the API.

Auth Token Request

POST Token Response

A successful response will have a data object that contains the Token Object.

Token Object

Token Attributes

Auth Token Action

Auth Token Type

Brands Resource

The brands endpoints support live querying for the most up to date information. However, we recommend caching the brands within your application and refreshing them every hour to ensure the best performance.

You will use this brand to create transactions and allow users to browse available brands.

International

Brands are separated by country and currency. Amazon US is a different brand than Amazon UK. However they will have the same group_id. This is applicable to all brands. The names of the brands will commonly match however country code and currency will be different amongst other country specific attributes.

GET Brand

EXAMPLE GET BRAND REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/brands/a5daa05b-bd95-4d3d-94b5-0ea26480a7e7' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

EXAMPLE GET BRAND RESPONSE

{
  "data": {
    "type": "brands",
    "id": "a5daa05b-bd95-4d3d-94b5-0ea26480a7e7",
    "attributes": {
      //.. reference The Brand Object
    }
  }
}

GET /business/v2/brands/:id

This brand endpoint returns a single brand object, which can be used to display detailed information about the brand.

GET Brand Response

The response will have a data object that contains the Brand Object

Reference Error Response for a list of possible errors and their descriptions.

GET Brands

EXAMPLE GET BRANDS REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/brands' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'X-Country: US' \
--header 'X-Currency: USD'

EXAMPLE GET BRANDS RESPONSE

{
  "data": [
    {
      "type": "brands",
      "id": "a5daa05b-bd95-4d3d-94b5-0ea26480a7e7",
      "attributes": {
        //.. reference The Brand Object
      }
    },
    {
      "type": "brands",
      "id": "a5asdf5b-bd95-4d3d-94b5-0ea26480a7e2",
      "attributes": {
        //.. reference The Brand Object
      }
    }
    // .. more brands
  ],
  "meta": {
    "total_results": 2
  }
}

GET /business/v2/brands

This brand endpoint returns a list of brands. The brands are paginated and can be sorted and searched.

Pagination and sorting

This endpoint supports pagination, sorting, and searching operations. All search and pagination parameters are optional and will utilize the default values if not provided.

Search

Pagination

Sorting

GET Brands Response

The response will have a data array that contains the Brand Objects and a meta object that contains total_results which is the total number of resources. This can be utilized to determine the number of pages available based on the page[size] parameter.

Reference Error Response for a list of possible errors and their descriptions.

Shared Brand Schemas

EXAMPLE BRAND OBJECT

{
  "type": "brands",
  "id": "a5daa05b-bd95-4d3d-94b5-0ea26480a7e7",
  "attributes": {
    "group_id": "2345a05b-bd95-4d3d-94b5-0ea26480a788",
    "icon_url": "https://www.raise.com/raise-content/Raise+Brand+Tiles/64X64/a5daa05b-bd95-4d3d-94b5-0ea26480a7e7.png",
    "name": "Amazon",
    "currency": "USD",
    "country": "US",
    "commission_rate": 400,
    "description": "Amazon.com Gift Cards* never expire and can be redeemed towards millions of items at www.amazon.com",
    "terms": "The Amazon.com Conditions of Use apply. No fees apply to Gift Cards. We reserve the right to require additional verification of your identity, Gift Card or account ownership, or provision of an additional payment instrument, before you are able to apply a Gift Card to your account or your Amazon.com Balance to a purchase. When you purchase, receive, or apply a Gift Card to your account, or your Amazon.com Balance to a purchase, you agree that the laws of the State of Washington, without regard to principles of conflict of laws, will govern these terms and conditions and any dispute that may arise between you and ACI Gift Cards LLC, and its affiliates related to your use of a Gift Card or your Amazon.com Balance. We reserve the right to change these terms and conditions without notice, from time to time at our sole discretion. All terms and conditions are applicable to the extent permitted by law. If any of these terms and conditions are deemed invalid, void, or for any reason unenforceable, that unenforceable term will be deemed severable and will not affect the validity and enforceability of any remaining terms and conditions.",
    "merchant_url": "https://www.amazon.com/",
    "balance_check_url": "https://www.amazon.com/gp/css/gc/balance",
    "redemption_config": {
      "disclaimer": "",
      "methods": [
        {
          "info": "To redeem your gift card, follow these steps:\n1.\tVisit www.amazon.com/redeem\n2.\tEnter the Claim Code when prompted.\n3.\tGift card funds will be applied automatically to eligible orders during the checkout process.\n4.\tYou must pay for any remaining balance on your order with another payment method.\n\nYour gift card claim code may also be entered when prompted during checkout. To redeem your gift card using the Amazon.com 1-Click® service, first add the gift card funds to Your Account.\nIf you have questions about redeeming your gift card, please visit www.amazon.com/gc-redeem.",
          "kind": "ONLINE"
        }
      ]
    },
    "transaction_config": {
      "disclaimer": "Restrictions apply, see [amazon.com/gc-legal](amazon.com/gc-legal)",
      "variable_load": {
        "increment": 1,
        "minimum_amount": 500,
        "maximum_amount": 199999
      }
    },
    "categories": ["ENTERTAINMENT", "HOME"]
  }
}

Brand Object

Brand Attributes

Transaction Config

Note: variable_load and fixed_load are mutually exclusive. A transaction config will have one or the other.

Variable Load

Fixed Load

Redemption Config

Redemption Method

Redemption Kind

Category

Categories Resource

Categories are a way to group brands together. This resource provides a list of categories that are available to the Raise API.

GET Categories

EXAMPLE GET CATEGORIES REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/categories' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'X-Country: US' \
--header 'X-Currency: USD'

EXAMPLE GET CATEGORIES RESPONSE

{
  "data": [
    {
      "type": "categories",
      "id": "ENTERTAINMENT",
      "attributes": {
        "name": "Entertainment",
        "available_brands": 3
      }
    },
    {
      "type": "categories",
      "id": "GROCERY",
      "attributes": {
        "name": "Groceries",
        "available_brands": 10
      }
    }
    // .. more categories
  ],
  "meta": {
    "total_results": 2
  }
}

GET /business/v2/categories

This category endpoint returns a list of categories. The categories can be sorted as needed.

Sorting

GET Categories Response

The response will have a data array that contains the Category Objects and a meta object that contains total_results which is the total number of resources.

Reference Error Response for a list of possible errors and their descriptions.

Category Object

Countries Resource

Countries are a way to group brands together. This resource provides a list of countries that are available to the Raise API.

GET Countries

EXAMPLE GET COUNTRIES REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/countries' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'X-Country: US' \
--header 'X-Currency: USD'

EXAMPLE GET COUNTRIES RESPONSE

{
  "data": [
    {
      "type": "countries",
      "id": "US",
      "attributes": {
        "currency": "USD",
        "available_brands": 832
      }
    },
    {
      "type": "countries",
      "id": "CA",
      "attributes": {
        "currency": "CAD",
        "available_brands": 135
      }
    }
    // .. more countries
  ],
  "meta": {
    "total_results": 2
  }
}

GET /business/v2/countries

This country endpoint returns a list of countries.

GET Countries Response

The response will have a data array that contains the Country Objects and a meta object that contains total_results which is the total number of resources.

Reference Error Response for a list of possible errors and their descriptions.

Country Object