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 don’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 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, transactions, etc.
• attributes - The fields you are trying to update or create.
• id - The id of the specific resource depending on the type of request. Example: PATCH cards

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 monetary amounts in the API — request value and response fields such as balance, total, and commission.amount — are integers expressed in the currency's minor unit (its smallest denomination, also called its subunit).

Convert a human-readable amount to minor units with:

value = amount × 10^(decimal_digits)

where decimal_digits depends on the currency:

• 2 decimals (most currencies): USD $123.00 → 12300; £1.50 → 150.
• 0 decimals (e.g. JPY): ¥123 → 123 (the yen has no subunit).
• 3 decimals (the dinars, e.g. KWD): KWD 1.234 → 1234.

Responses use the same convention, so a balance of 12300 on a USD card is $123.00. See Supported Currencies for each currency's decimal digits.

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 two 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 requests 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 view your account balance in 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 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 has 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

Balance Resource

Returns your fund balance for purchasing gift cards through the API (available, reserved, and pending amounts). All balance amounts are always in USD, as integers in cents (hundredths of a US dollar). The X-Currency header does not change this; it applies to other parts of the API, not these fields.

GET Balance

EXAMPLE REQUEST

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

EXAMPLE RESPONSE

{
  "data": {
    "type": "balance",
    "id": "c7770f32-0034-4562-b504-a1b46d21072c",
    "attributes": {
      "available_balance": 100000,
      "reserved_balance": 2500,
      "pending_balance": 0
    }
  }
}

GET /business/v2/balance

Balance response

See Error Response for errors.

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.

When creating a transaction for a brand, the X-Country and X-Currency headers must match the brand's country and currency. See Transactions → International Orders for details.

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

This resource provides the list of countries supported by the Raise API, along with each country's default currency and the number of brands available in that country. For how amounts are represented in each currency, see Supported Currencies.

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

Supported Currencies

The Raise API supports the currencies listed below. All monetary amounts are integers expressed in the currency's minor unit (its smallest denomination) — see Currency for the conversion rule.

Convert a human-readable amount to minor units with:

value = amount × 10^(decimal_digits)

Minor units quick reference

The default is 2 decimal digits (multiply the human amount by 100, e.g. USD $123.00 → 12300). The currencies below differ:

Zero-decimal — no subunit; send the whole-unit amount as-is (×1), e.g. JPY ¥123 → 123:

AFN, AMD, BIF, BYR, CLP, COP, CRC, DJF, GNF, HUF, IDR, IQD, IRR, ISK, JPY, KMF, KRW, LAK, LBP, MGA, MMK, MUR, PKR, PYG, RSD, RWF, SOS, SYP, TZS, UGX, UZS, VND, VUV, XAF, XOF, XPF, YER, ZMK, ZMW

Three-decimal — multiply by 1000, e.g. KWD 1.234 → 1234:

BHD, JOD, KWD, LYD, OMR, TND

Full list

Every supported currency, its decimal digits, and the integer to send for one whole unit of that currency.

Transactions Resource

The transaction resource allows you to create, retrieve, and list transactions. Transactions are the core of the Raise API and are used to create gift card orders.

POST /business/v2/transactions

This transaction endpoint creates a new transaction. The transaction value is deducted from the client's account balance.

POST Transaction Enterprise Clients

EXAMPLE POST TRANSACTION REQUEST ENTERPRISE CLIENTS

curl --location --request POST 'https://playground-api.raise.com/business/v2/transactions' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'X-Country: US' \
--header 'X-Currency: USD' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "transactions",
    "attributes": {
      "cards": [{
        "brand_id": "dd231d64-4b34-48e0-b6a7-ca1faab219a1",
        "value": 2500,
        "quantity": 1
      }],
      "customer": {
        "id": "c7770f32-0034-4562-b504-a1b46d21072c"
      },
      "client_order_id": "order-1234"
    }
  }
}'

Transaction Request Enterprise Clients

POST Transaction Web3 Clients

EXAMPLE POST TRANSACTION REQUEST WEB3 CLIENTS

curl --location --request POST 'https://playground-api.raise.com/business/v2/transactions' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'X-Country: US' \
--header 'X-Currency: USD' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "transactions",
    "attributes": {
      "cards": [{
        "brand_id": "dd231d64-4b34-48e0-b6a7-ca1faab219a1",
        "value": 2500,
        "quantity": 1
      }],
      "customer": {
        "id": "c7770f32-0034-4562-b504-a1b46d21072c"
      },
      "payment_details": {
        "crypto_details": {
          "network": "solana",
          "asset": "sol",
          "wallet_address": "somewalletaddresshere"
        }
      },
      "client_order_id": "order-1234"
    }
  }
}'

Transaction Request Web3 Clients

EXAMPLE POST TRANSACTION RESPONSE

{
  "data": {
    "type": "transactions",
    "id": "T1234567890123",
    "attributes": {
      // .. Refer to the Transaction Object
    }
  }
}

International Orders

The Raise API supports international orders. Each brand belongs to a single country and currency (see Brands → International). When you create a transaction, the X-Country and X-Currency headers must match the country and currency of the brand being ordered. For example, to order a brand whose country is GB and currency is GBP, send X-Country: GB and X-Currency: GBP. Amounts such as the card value are expressed in that currency's minor unit — see Currency for the conversion rule.

If either the country or the currency does not match the brand, the request is rejected as a Bad Request (ErrCodeBadRequest).

Idempotency

Idempotency ensures safe retrying of requests without unintended duplicate operations. In case of a connection error, repeating the request with the same client_order_id poses no risk of creating a duplicate transaction.

Raise’s idempotency mechanism stores the status code and body of the initial request made for any given client_order_id, regardless of success or failure. Subsequent requests with the same ID yield the same result, including 500 errors.

Results are saved only after endpoint execution begins. Failed validation or conflicts with concurrent requests prevent the saving of idempotent results, allowing for retrying.

Idempotency facilitates request retrying without creating new transactions. If a request fails, retry it with the same client_order_id for an identical response as the original request.

Transaction Request Cards

Transaction Request Customer

Transaction Request Payment Details

Transaction Request Payment Details Crypto Details

POST Transaction Response

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

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

Transaction Flow

GET Transaction

EXAMPLE GET TRANSACTION REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/transactions/TCYYLJDBCXTE6C' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

EXAMPLE GET TRANSACTION RESPONSE

{
  "data": {
    "type": "transactions",
    "id": "TCYYLJDBCXTE6C",
    "attributes": {
      // .. Refer to the Transaction Object
    }
  }
}

GET /business/v2/transactions/:id

This transaction endpoint retrieves a transaction by its unique identifier. If the transaction is in a failed state, the related error will be returned.

GET Transaction Response

The response will have a data object that contains the Transaction Object.

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

GET Transactions

EXAMPLE GET TRANSACTIONS REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/transactions' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'

EXAMPLE GET TRANSACTIONS RESPONSE

{
  "data": [
    {
      "type": "transactions",
      "id": "TCYYLJDBCXTE6C",
      "attributes": {
        // .. Refer to the Transaction Object
      }
    }
  ],
  "meta": {
    "total_results": 1
  }
}

GET /business/v2/transactions

This transaction endpoint retrieves a list of transactions. The transactions 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. Clients using the Auth Resource will only be able to query by the authenticated customer's transactions.

Search

Date range: omit both parameters to list transactions without a creation-time filter. If you pass either date_range.start or date_range.end, you must pass both. Each value must be a valid RFC 3339 timestamp. Prefer UTC (for example a Z suffix). If you include a numeric offset in the string, the API normalizes the instant to UTC before filtering. date_range.start must not be after date_range.end, and the interval between them must not exceed 90 days.

Pagination

Sorting

GET Transactions Response

The response will have a data array that contains the Transaction 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. It is important to note that the Transaction Objects returned from GetTransactions do not include the cards array. To retrieve the cards array for a specific transaction, you must call the GetTransaction endpoint.

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

Shared Transaction Schemas

Transaction Object

EXAMPLE TRANSACTION OBJECT

{
  "type": "transactions",
  "id": "TCYYLJDBCXTE6C",
  "attributes": {
    "state": "COMPLETED",
    "total": 2500,
    "total_commission": {
      "amount": 100,
      "rate": 400,
      "currency": "USD"
    },
    "escrow_deduction": {
      "usd_amount": 2400,
      "currency": "USD",
      "exchange_rate_1e6": 1000000,
      "local_amount": 2400
    },
    "country": "US",
    "currency": "USD",
    "customer": {
      "id": "c7770f32-0034-4562-b504-a1b46d21072c"
    },
    "cards": [
      {
        "id": "a27c1e40-8c1f-48b7-b366-5c006abea9cd",
        "brand_id": "dd231d64-4b34-48e0-b6a7-ca1faab219a1",
        "brand_name": "Lowe's",
        "balance": 2500,
        "currency": "USD",
        "number": {
          "label": "Card Number",
          "value": "5281 5281 5281 5281",
          "raw": "5281528152815281"
        },
        "csc": {
          "label": "PIN",
          "value": "1234",
          "raw": "1234"
        },
        "url": {
          "raw": "https://www.vcdelivery.com/vcert/b9ec093b-77cf-4c1e-bdf1-30857a8ed943"
        },
        "barcode": {
          "type": "QR_CODE",
          "value": "5281528152815281"
        },
        "expires_at": "",
        "balance_checks_available": 3,
        "balance_checks_supported": true,
        "commission": {
          "amount": 100,
          "rate": 400,
          "currency": "USD"
        }
      }
    ],
    "client_order_id": "order-1234"
  }
}

Transaction Attributes

Transaction State

Customer Object

Commission Object

Escrow Deduction Object

The escrow deduction represents the amount deducted from the client's account balance to fund the transaction. It is present on both the Transaction Object and each Card Object.

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)

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.

Cards Resource

GET Cards

EXAMPLE GET CARDS REQUEST

curl --location --request GET 'https://playground-api.raise.com/business/v2/cards?customer[id]=abc-123' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \

EXAMPLE GET CARDS RESPONSE

{
  "data": [
    {
      "type": "cards",
      "id": "a27c1e40-8c1f-48b7-b366-5c006abea9cd",
      "attributes": {
        // .. Refer to the Card Object
      },
      "relationships": {
        "brands": {
          "data": {
            "type": "brands",
            "id": "id-of-the-brand-associated-with-the-card"
          }
        }
      }
    }
  ],
  "included": [
    {
      "type": "brands",
      "id": "id-of-the-brand-associated-with-the-card",
      "attributes": {
        // .. Refer to the Brand Object
      }
    }
  ],
  "meta": {
    "total_results": 1
  }
}

GET /business/v2/cards

This card endpoint retrieves a list of cards. The cards 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. Clients using the Auth Resource will only be able to query by the authenticated customer's cards.

Search

Pagination

Sorting

GET Cards Response

The response will have a data array that contains the Card 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.

The response may also include an included deduped array that contains the Brand Objects associated with the cards. Which can be referenced from the relationships object on a card.

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

PATCH Card

EXAMPLE PATCH CARD REQUEST

curl --location --request PATCH 'https://playground-api.raise.com/business/v2/cards/a27c1e40-8c1f-48b7-b366-5c006abea9cd' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "type": "cards",
    "id": "a27c1e40-8c1f-48b7-b366-5c006abea9cd",
    "attributes": {
      "action": "BALANCE_CHECK"
    }
  }
}'

EXAMPLE PATCH CARD RESPONSE

{
  "data": {
    "type": "cards",
    "id": "a27c1e40-8c1f-48b7-b366-5c006abea9cd",
    "attributes": {
      // .. Refer to the Card Object
    }
  }
}

PATCH /business/v2/cards/:id

This card endpoint updates a card. The card can be updated with a balance check action.

Card Request

Card Request Action

Shared Card Schemas

Card Object

EXAMPLE CARD OBJECT

{
  "type": "cards",
  "id": "a27c1e40-8c1f-48b7-b366-5c006abea9cd",
  "attributes": {
    "brand_id": "dd231d64-4b34-48e0-b6a7-ca1faab219a1",
    "brand_name": "Lowe's",
    "balance": 2500,
    "currency": "USD",
    "number": {
      "label": "Card Number",
      "value": "5281 5281 5281 5281",
      "raw": "5281528152815281"
    },
    "csc": {
      "label": "PIN",
      "value": "1234",
      "raw": "1234"
    },
    "url": {
      "label": "View Gift Card Details",
      "raw": "https://www.vcdelivery.com/vcert/b9ec093b-77cf-4c1e-bdf1-30857a8ed943"
    },
    "barcode": {
      "type": "QR_CODE",
      "value": "5281528152815281"
    },
    "expires_at": "",
    "balance_checks_available": 3,
    "balance_checks_supported": true,
    "commission": {
      "amount": 100,
      "rate": 400,
      "currency": "USD"
    },
    "escrow_deduction": {
      "usd_amount": 768,
      "currency": "USD",
      "exchange_rate_1e6": 1000000,
      "local_amount": 768
    },
    "state": "ACTIVE",
    "apple_pass_link": "https://commerce-api.raisestaging.com/business/v2/cards/apple/fe1afa62-3630-4136-b6d8-87bab99568c9",
    "google_pass_link": "https://commerce-api.raisestaging.com/business/v2/cards/google/fe1afa62-3630-4136-b6d8-87bab99568c9"
  }
}

Card Attributes

Card Field

Card Barcode Field

Barcode Type

Card State

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

The Raise API uses a consistent error response format on all API endpoints.

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

EXAMPLE ERROR RESPONSE

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

EXAMPLE MULTIPLE ERROR RESPONSE

{
  "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"
    }
  ]
}

Error Object

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

Handling Server Errors & Timeouts (5XX)

When encountering a request timeout or receiving a 5XX server error response, follow these steps:

1. Wait and Retry: Initiate a retry for the request.
2. Incremental Backoff: If the retry request fails, continue retrying, progressively increasing the wait time between retries.
3. Maximum Wait Time: If the retry request still fails, continue to wait for the maximum allowed time between each retry request. Once the maximum wait time is reached, do not increase the wait time further.
4. Cease Retries: Stop retrying requests after reaching the maximum number of retry attempts.
5. If you require further assistance, please email the error response along with the client_order_id to your designated support contact and your Account Manager.

Changelog

Version

Document version: 1781627298