NAV
shell javascript

Introduction

Welcome to the GoRewards API endpoints documentation! This documentation contains a comprehensive list of endpoints, each with an outlined description, accepted parameters, required headers for requests, and expected request and response payloads.

This documentation is continually updated and aims to maintain an up-to-date catalogue of the internal API's functionality and information.

Overview

Response Format

Responses are returned in JSON format.

Authentication

The GoRewards API uses partner-specific API Keys in conjunction with IP allowlisting to authenticate all requests.

All requests must be made through a server-to-server connection to ensure that requests originate from a consistent, repeatable IP address, thereby satisfying the IP allowlisting requirement.

Test keys are provided for use in non-production environments, and are prefixed with gor_test. Live production keys are instead prefixed with gor_live.

Your API keys are directly tied to your organization and contain strong permissions with access to your data. It is your responsibility to ensure these keys are kept secure and not shared in public areas such as your website or repositories. To support this level of security, requests must be made over HTTPS, and requests without a valid key will be denied.

Please contact your program representative in the event your key is compromised or to generate a new key.

Sample request with authentication

curl -X GET "https://api.gorewards.tech/v1/user/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gor_test_lhdCI6MTY5ND...Y4ODAwMCwiZ"

fetch('https://api.gorewards.tech/v1/users/:id', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer gor_test_lhdCI6MTY5ND...Y4ODAwMCwiZ'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

When using these keys, they must be provided as a request header, and follow the key:value pair format of Authorization: Bearer gor_test_lhdCI6MTY5ND...Y4ODAwMCwiZ.

Expandable

Request With Expansion

curl -X GET "https://api.gorewards.tech/v1/transactions/trsn_56006...40998f3d0?expand=debits&expand=chain" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>" \

fetch('https://api.gorewards.tech/v1/transactions/trsn_56006...40998f3d0?expand=debits&expand=chain', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });


{
  "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "user": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "linked_card": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "merchant": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "debit": "debt_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "reward": "pdrw_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "territory": "terr_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "gross_amount_cents": "2000",
  "transaction_currency_iso4217": "840",
  "transaction_currency_gross_amount_cents": "2000",
  "transaction_currency_conversion_rate": "1.000",
  "debit_currency_iso4217": "840",
  "debit_currency_gross_amount_cents": "2000",
  "debit_currency_conversion_rate": "1.000",
  "transaction_date": "174584200",
  "transaction_import_date": "1745842105",
  "state": "settled",
  "fee_percentage": 0.12,
  "fee_cents": 24
}

Full Transaction Object:

{
  "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "user": {
    "id": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "external_id": "1114",
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  },
  "linked_card": {
    "id": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
    "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "card_last_four": "1234",
    "card_alias": "My Visa Card",
    "card_type": "visa",
    "credits_earned_cents": 1000,
    "credits_earned": "10.00",
    "created_at": "1748884662",
    "is_ath": false,
    "state": "active"
  },
  "chain": {
    "id": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "name": "Chili's"
  },
  "merchant": {
    "id": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
    "trade_name": "Chili's Dorado",
    "expires_at": "1780427302",
    "created_at": "1748884662",
    "address_street_number": 3924,
    "address_line_one": "Main Street",
    "address_line_two": "Apartment 304",
    "city": "Dorado",
    "returning_visit_multiplier": 2,
    "base_reward_percent": 0.05
  },
  "debit": {
    "id": "debt_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "amount_cents": "2000",
    "currency_iso4217": "840",
    "state": "debited",
    "debited_at": "1748884662"
  },
  "reward": {
    "id": "pdrw_e1d4bfc2-78a3-41d3-bc8a-2f3a5018d93a",
    "amount_cents": "629",
    "is_double_reward": false,
    "state": "settled",
  },
  "territory": {
    "id": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "iso3166": "PR",
    "iso3": "PRI",
    "iso4217": "840",
    "name": "PUERTO_RICO",
    "display_name": "Puerto Rico"
  },
  "gross_amount_cents": "2000",
  "transaction_currency_iso4271": "840",
  "transaction_currency_gross_amount_cents": "2000",
  "transaction_currency_conversion_rate": "1.000",
  "debit_currency_iso4217": "840",
  "debit_currency_gross_amount_cents": "2000",
  "debit_currency_conversion_rate": "1.000",
  "transaction_date": "174584200",
  "transaction_import_date": "1745842105",
  "state": "settled"
}

Large objects may have fields specially marked as expandable in order to reduce unnecessary data. These fields will have some default value specified and upon request expand into the full data object. Fields with this trait will be labelled expandable beside their normal type declaration, and can be requested through the use of the expand array parameter containing the specific fields you would like.

For simplicity, the expandable path follows the response payload format. For example, when retrieving a list of data, it is contained inside of a data property; to handle this, we can recursively expand using the . separator. If we wanted to expand the debits property in a Transaction Object, then we would provide the request ?expand=debits, instead of the normal ?expand-debits.

You can expand as many objects as you would like in one request by simply including multiple keys in the expand query.

Expandable objects also allow for nested expansions. For example, a Transaction has a Linked Card, and a Linked Card has a user. You could expand the user in two ways with the flexibility to do whatever works best for your use case. Option 1 would be to expand user on the root object transaction. Option 2 would be to expand linked_card.user to expand both the linked_card and the user objects.

Pagination

All top-level API resources have support for bulk fetches through list API methods. These list API methods share a common structure and accept, at a minimum, the following three parameters: per_page and page,

Pagination results are included on all list API endpoints, and are enforced through defaults in the event details have been omitted.

Sample Response with Pagination:

{
  {
    "meta": {
      "pagination": {
        "total_items": 1,
        "item_count": 1,
        "per_page": 20,
        "total_pages": 1,
        "current_page": 1
      }
    },
    "data": [
      {
        "id": "user_df33da06-1b69-4e64-a953-24be54dcdc1c",
        "external_id": "1114",
        "email": "test@local.host",
        "created_at": "1751175815",
        "metadata": {
          "first_name": "Geoff",
          "last_name": "Rewards",
          "locale": null
        }
      },
    ]
}
}
Parameter Description
total_items number The number of items that are available in the response for your current query.
item_count number The number of items that were returned on your current page.
per_page number The number of items that are returned on each page. Defaults to 20 with a minimum of 5 and a maximum of 50.
total_pages number The number of pages that exist for your current query.
current_page number The page you are currently on in the request.

Date Ranges

Numerous API endpoints contain the ability to query based off a date range. All date range queries contain a common set of API parameters that are documented below, and by default are limited to 1 month (31 days) of data at a given time.

In the event that no date range dictionary is provided, the system will default to the last 31 days by default.

Parameter Description
from timestamp A timestamp representing the starting time of your date range.
to timestamp A timestamp representing the ending time of your date range. In the event that a from timestamp is provided without a to, the to will default to exactly 31 days after the from.

Example Usage

This section contains some sample dictionary values provided to the system and their co-responding response values. In the event that you provide a time range as a parameter to a request, you can safely assume you will always be returned a dictionary with the appropriate from and to values that were returned.

When both a from and to are provided and are within 31 days of each other, you will return a full dataset

// Request
{
  "from": "1707509382",
  "to": "1709842182"
}

// Response
{
  "from": "1707509382",
  "to": "1709842182"
}

When both a from and to are provided but are move than 31 days apart, we will take the from and modify the to be within range

// Request
{
  "from": "1709842182",
  "to": "1712693382"
}

// Response
{
  "from": "1709842182",
  "to": "1710187782"
}

When a from is provided with no to, we will return 31 days from the provided from date

// Request
{
 "from": "1709842182"
}

// Response
{
  "from": "1709842182",
  "to": "1710187782"
}

When a to is provided with no from range, we will return 31 days before the provided to date

// Request
{
  "to": "1710187782"
}

// Response
{
  "from": "1709842182",
  "to": "1710187782"
}

Errors

GoRewards utilizes conventional HTTP response codes for all errors encountered inside the API service, alongside a more detailed four digit error code and message to provide further assistance.

Conventional HTTP Errors

Generally:

Code Name Summary
200 OK Generalized action successful
204 No Content Action successful, expect no response content returned
401 Unauthorized No valid API key provided
403 Forbidden Invalid permissions to perform the request
404 Not Found Requested resource does not exist
500 Internal Server Error Encountered an unexpected error

Detailed Errors

{
  "code": 2002,
  "message": "Authentication token is invalid. Request a new one to continue."
}
HTTP Status Code Message
400 1000 Form error: missing or invalid input
400 1002 Card type not found
400 1003 Card type unsupported
400 1009 Card nickname invalid
400 1011 Card limit Exceeded
401 2002 Invalid authorization
401 2100 Token expired
401 2101 Invalid issuer
401 2102 Invalid token structure! Could not be decoded properly
401 2103 Token not found
403 null Unauthorized Access
404 3000 Asset not found in Database
500 5000 Unexpected error. See the response message for details.

Acceptable Card Types

Your GoRewards partner instance may support one or many card types depending on what processor is enabled for your territory.

If Visa is an enabled processor, all Visa cards will be valid within a given territory.

If Evertec is an enabled processor, all cards will be valid within a given territory assuming they are issued with an ATH Co-brand

Users

This object represents a user within your GoRewards partner instance. Use it to update contact information, link cards, view transactions, and view rewards.

Users can additionally be created by adding a new card

The User Object

User Object:

{
  "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "external_id": "1114",
  "created_at": "2023-07-11T19:01:45Z",
  "deleted_at": null,
  "email": "juan_pablo@gorewards.tech",
  "metadata": {
    "first_name": "Juan",
    "last_name": "Pablo",
    "locale": "en_US"
  }
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
external_id string The ID provided by the partner system when the object was created.
created_at timestamp Date and time of when the user was created.
deleted_at timestamp Date and time of when the user was deleted.
email string A valid email that maps to the user in the parent system. This must be unique across the each partner, however it can be updated in the future.
optional metadata dictionary See User Metadata

User Metadata

User metadata is a dictionary that allows you to send data to the GoRewards system to empower us to make better business decisions when interacting with your clients. Items impacted by these include merchant recommendations, default locales, etc.

The following fields are the currently supported elements

Parameter Description
optional first_name string The user's first name
optional last_name string The user's last name
optional locale string An ISO 639-1 locale code. For a full list of available locales, see Locales. In the event that a valid locale is not provided with a user, we will fall back to the default configured per partner.

List all Users

curl -X GET "https://api.gorewards.tech/v1/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/users', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  "page": 2,
  "limit": 10,
  "total": 25,
  "total_pages": 3,
  "data": [
    {
      "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "external_id": "1114",
      "created_at": "2023-07-11T19:01:45Z",
      "deleted_at": null,
      "email": "juan_pablo@gorewards.tech",
      "metadata": {
        "first_name": "Juan",
        "last_name": "Pablo",
        "locale": "en_US"
      }
    },
    {
      "id": "user_b8d71a5c-81de-4e59-87a1-c7725e4b1234",
      "external_id": "1115",
      "created_at": "2023-07-11T19:01:45Z",
      "deleted_at": "2023-07-11T19:01:45Z",
      "email": "lisa.marie@gorewards.tech",
      "metadata": {
        "first_name": "Lisa",
        "last_name": "Marie",
        "locale": "en_GB"
      }
    }
  ]
}

This endpoint retrieves all users.

HTTP Request

GET https://api.gorewards.tech/v1/users

Query Parameters

Parameter Description
page The current page that you wish to be displayed. The total count of pages depends on the limit provided. The maximum number of pages and further pagination details can be found in the sample response.
limit A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Returns

A dictionary with a data property that contains an array of up to limit customers

Retrieve a User

curl -X GET "https://api.gorewards.tech/v1/user/user_b8d71a5c-81de-4e59-87a1-c7725e4b1234?identifier=external" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/users/user_b8d71a5c-81de-4e59-87a1-c7725e4b1234?identifier=external', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  {
    "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
    "external_id": "1114",
    "created_at": "2023-07-11T19:01:45Z",
    "deleted_at": null,
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  }
}

This endpoint retrieves a User Object.

HTTP Request

GET https://api.gorewards.tech/v1/users/:id

Query Parameters

Parameter Description
identifier query The identifier type to use in the request. Available options: external, internal. e will use the ID provided by the partner systems, internal will reference the UUID generated by the GoRewards system. Defaults to external if neither option is provided.

Returns

Returns the User object for the identifier provided.

Create a User

curl -X POST "https://api.gorewards.tech/v1/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "external_id": "1114",
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  }'

fetch('https://api.gorewards.tech/v1/users', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_api_token_here>'
  },
  body: JSON.stringify({
    external_id: '1114',
    email: 'juan_pablo@gorewards.tech',
    metadata: {
      first_name: 'Juan',
      last_name: 'Pablo',
      locale: 'en_US'
    }
  })
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('User created:', data);
  })
  .catch(error => {
    console.error('Error creating user:', error);
  });

Sample Response

{
  {
    "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
    "external_id": "1114",
    "created_at": "2023-07-11T19:01:45Z",
    "deleted_at": null,
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  }
}

This endpoint creates a User Object.

HTTP Request

POST https://api.gorewards.tech/v1/users/:id

Query Parameters

Parameter Description
external_id string A unique ID that maps to the user in the parent system. This must be unique across the entire GoRewards system.
optional email string A valid email that maps to the user in the parent system. This must be unique across each partner, however it can be updated in the future.
optional email metadata dictionary For our recommendations on supported fields, See User Metadata. All metadata is optional, and any defaulting behavior is described in the User Metadata documentation.

Returns

Returns the resulting user from the object created.

Update a User

curl -X PATCH "https://api.gorewards.tech/v1/users/user_560062e6-2ce6-4c4d-8daa-d3540998f3d0" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  }'

fetch('https://api.gorewards.tech/v1/users/user_560062e6-2ce6-4c4d-8daa-d3540998f3d0', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_api_token_here>'
  },
  body: JSON.stringify({
    email: 'juan_pablo@gorewards.tech',
    metadata: {
      first_name: 'Juan',
      last_name: 'Pablo',
      locale: 'en_US'
    }
  })
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('User created:', data);
  })
  .catch(error => {
    console.error('Error creating user:', error);
  });

Sample Response

{
  {
    "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
    "external_id": "1114",
    "created_at": "2023-07-11T19:01:45Z",
    "deleted_at": null,
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  }
}

This endpoint updates a User Object.

Unlike the retrieval endpoints, the update endpoints requires you to use the GoRewards generated uuid.

HTTP Request

PATCH https://api.gorewards.tech/v1/users/:id

Query Parameters

Parameter Description
optional email string A valid email that maps to the user in the parent system. This must be unique across each partner, however it can be updated in the future.
metadata nullable dictionary For our recommendations on supported fields, See User Metadata. All metadata is optional, and any defaulting behavior is described in the User Metadata documentation. Any existing metadata that is omitted from this dictionary will be untouched. If you would like to remove metadata, set the value explicitly to null

Returns

Returns the User object for a valid identifier.

Delete a User

curl -X DELETE "https://api.gorewards.tech/v1/users/user_560062e6-2ce6-4c4d-8daa-d3540998f3d0" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here"

fetch(`https://api.gorewards.tech/v1/users/user_560062e6-2ce6-4c4d-8daa-d3540998f3d0`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    console.log('User deleted successfully');
  })
  .catch(error => {
    console.error('Error deleting user:', error);
  });

Sample Response

{
  {
    "id": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
    "deleted_at": "2023-07-11T19:01:45Z",
  }
}

This endpoint deletes a User Object.

In the event that the user had already been deleted, the original payload will be returned with an unchanged deleted_at timestamp.

HTTP Request

DELETE https://api.gorewards.tech/v1/users/:id

Query Parameters

No Parameters.

Returns

Returns a subset of the main object containing remaining details.

Deleted customers can still be retrieved through the API using our unique UUID. On deletion, the external_id and all other provided data will be obfuscated and no longer retrievable. This is for historical purposes and to aid in a users right to be forgotten.

Should you wish to re-instate a user after their deletion, please submit a request to create a new user.

Cards

Create, Read, List, Update and Delete user linked cards.

The Card Object

Unexpanded Card Object:

{
  "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
  "card_last_four": "1234",
  "card_alias": "My Visa Card",
  "card_type": "visa",
  "credits_earned_cents": 1000,
  "credits_earned": "10.00",
  "created_at": "2023-07-11T19:01:45Z",
  "deleted_at": null,
  "is_ath": false,
  "state": "active"
}

Full Card Object:

{
  "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "user": {
    "id": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "external_id": "1114",
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  },
  "card_last_four": "1234",
  "card_alias": "My Visa Card",
  "card_type": "visa",
  "credits_earned_cents": 1000,
  "credits_earned": "10.00",
  "created_at": "2023-07-11T19:01:45Z",
  "deleted_at": null,
  "is_ath": false,
  "state": "active"
}
Field Description
uuid string Unique identifier of the card.
user string expandable UUID of the user who owns the card. Can be expanded to contain the full User Object
card_last_four string Last four digits of the card number.
card_alias string User-assigned nickname for the card.
card_type string Card brand/type (e.g., "visa").
credits_earned_cents integer Total credits earned, in cents.
credits_earned string Total credits earned, formatted as a currency string.
created_at timestamp Date and time of when the card was linked.
deleted_at timestamp Date and time of when the card was deleted.
is_ath boolean Whether the card is an ATH card.
state string Current status of the card. Can be one of the following values: active, inactive, pending.

Retrieve a Linked Card

Returns details about a specific linked card belonging to the provided user possesing the card_uuid provided.

Example Request

curl -X GET https://api.gorewards.tech/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

fetch('https://api.gorewards.tech/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_access_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Example Response

{
  "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
  "card_last_four": "1234",
  "card_alias": "My Visa Card",
  "card_type": "visa",
  "credits_earned_cents": 1000,
  "credits_earned": "10.00",
  "created_at": "2023-07-11T19:01:45Z",
  "deleted_at": null,
  "is_ath": false,
  "state": "active"
}

HTTP Request

GET https://api.gorewards.tech/v1/cards/:id

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.

Returns

Error Responses

HTTP Status Code Message
401 2002 Invalid authorization
401 2100 Token expired
401 2101 Invalid issuer
401 2102 Authentication token is invalid. Request a new one to continue.
401 2103 Token not found
403 ??? Unauthorized to access the specified card (authorization failure)
404 3000 Asset not found in DB
500 5000 Unexpected error. See the response message for details.

Example Error Response (Authentication Failure)

{
  "code": 2102,
  "message": "Authentication token is invalid. Request a new one to continue."
}

Returns a Card object.

List Linked Cards

Returns all linked cards.

By default, this endpoint will return linked cards for all users. To filter by a specific user ID, please see the user_id parameter.

Example Request

curl -X GET https://api.gorewards.tech/v1/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

fetch('https://api.gorewards.tech/v1/cards', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_access_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Example Response

{
  "page": 2,
  "limit": 10,
  "total": 25,
  "total_pages": 3,
  "data": [
    {
      "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
      "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
      "card_last_four": "1234",
      "card_alias": "My Visa Card",
      "card_type": "visa",
      "credits_earned_cents": 1000,
      "created_at": "2023-07-11T19:01:45Z",
      "deleted_at": null,
      "is_ath": false,
      "state": "active"
    },
    {
      "uuid": "card_j19ps319-3128-44f8-b05a-d70d15d3450e",
      "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
      "card_last_four": "5678",
      "card_alias": "Backup Card",
      "card_type": "mastercard",
      "credits_earned_cents": 500,
      "created_at": "2023-07-11T19:01:45Z",
      "deleted_at": null,
      "is_ath": true,
      "state": "inactive"
    }
  ]
}

HTTP Request

GET https://api.gorewards.tech/v1/cards

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.
user_id query UUID of the user the card is associated with.

Success Response

Error Responses

HTTP Status Code Message
401 2002 Invalid authorization
401 2100 Token expired
401 2101 Invalid issuer
401 2102 Authentication token is invalid. Request a new one to continue.
401 2103 Token not found
404 3000 Asset not found in DB
500 5000 Unexpected error. See the response message for details.

Example Error Response (Authentication Failure)

{
  "code": 2102,
  "message": "Authentication token is invalid. Request a new one to continue."
}

Returns

Returns a list of Cards.

Prepare a New Card

Before making a card creation request, the sensitive data must be encrypted. This endpoint retrieves your one-time usage encryption key, along with a reference id that needs to be additionally provided when creating the card.

curl -X POST "https://api.gorewards.tech/v1/cards/prepare" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here"

fetch('https://api.gorewards.tech/v1/cards/prepare', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_api_token_here>'
  },
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Key retrieved:', data);
  })
  .catch(error => {
    console.error('Error fetching encryption key:', error);
  });

Sample Response

{
  {
    "public_key": "encoded-key",
    "reference_id": "aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "valid_until": "2023-07-11T19:01:45Z"
  }
}

HTTP Request

POST https://api.gorewards.tech/v1/cards/prepare

Query Parameters

No parameters

Returns

Returns the base64 encoded RSA key, the associated reference id, and an epoch timestamp indicating when the key is valid until.

Link a new card for the provided user. This requires the card number to be encrypted using the single-use key given by the prepare endpoint, along with the key's reference id.

curl -X POST "https://api.gorewards.tech/v1/cards" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "user_id": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "card_alias": "New Alias Name",
    "encrypted_card_number": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvxQAriJvXQC3RjBbvmrUchjsZKc9n6yC8GIZmiMb",
    "reference_id": "311"
  }'

fetch('https://api.gorewards.tech/v1/cards', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_api_token_here>'
  },
  body: JSON.stringify({
    user_id: "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    card_alias: "New Alias Name",
    encrypted_card_number: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvxQAriJvXQC3RjBbvmrUchjsZKc9n6yC8GIZmiMb",
    reference_id: "311"
  })
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Card created:', data);
  })
  .catch(error => {
    console.error('Error creating card:', error);
  });

Sample Response

{
  {
    "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
    "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "card_last_four": "1114",
    "card_alias": "My new card",
    "card_type": "visa",
    "credits_earned_cents": 1000,
    "credits_earned": "10.00",
    "created_at": "2023-07-11T19:01:45Z",
    "deleted_at": null,
    "is_ath": false,
    "state": "active"
  }
}

HTTP Request

POST https://api.gorewards.tech/v1/cards

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.
user_id string UUID of the user the card is associated with.
card_alias string User's custom display name for their card.
encrypted_card_number string Full card number encrypted using the RSA key retrieved with a prepare request.
reference_id integer Unchanged reference ID retrieved alongside the RSA key from the prepare request.

Returns

Returns the default card object for the successfully linked card. Unsuccessful linkages will return a detailed error response of 100x.

Update a Linked Card

Updates the alias (nickname) of a specific linked card belonging to the provided user.

Example Request

curl -X PATCH https://api.gorewards.tech/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e?user_id=user_aca5bdb6-848c-4920-a8de-13fb13fb3926 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_alias": "New Alias Name"
  }'

fetch('https://api.gorewards.tech/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e?user_id=user_aca5bdb6-848c-4920-a8de-13fb13fb3926', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your_access_token_here>'
  },
  body: JSON.stringify({
    card_alias: "New Alias Name"
  })
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Card updated:', data);
  })
  .catch(error => {
    console.error('Error updating card:', error);
  });

Example Response

{
  "uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
  "card_last_four": "5305",
  "card_alias": "New Alias Name",
  "card_type": "visa",
  "credits_earned_cents": 8657,
  "credits_earned": "86.57",
  "created_at": "2023-07-11T19:01:45Z",
  "deleted_at": null,
  "is_ath": true,
  "state": "active"
}

HTTP Request

PATCH https://api.gustitosgo.com/v1/cards/:id

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.
card_alias string The new alias (nickname) for the card.

Error Responses

HTTP Status Code Message
400 1000 Form error: missing or invalid input
400 1002 Card type not found
400 1003 Card type invalid
400 1009 Card nickname invalid
401 2002 Invalid authorization
401 2100 Token expired
401 2101 Invalid issuer
401 2102 Authentication token is invalid. Request a new one to continue.
401 2103 Token not found
403 ??? Unauthorized to update the specified card (authorization failure)
404 3000 Asset not found in DB
500 5000 Unexpected error. See the response message for details.

Example Error Response (Form Error)

{
  "code": 1009,
  "message": "Card nickname invalid"
}

Returns

Returns the updated Card.

Delete a Linked Card

Deletes a specific linked card associated with the provided user.

No content is returned for this request.

Example Request

curl -X DELETE https://api.gustitosgo.com/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

fetch('https://api.gorewards.tech/v1/cards/card_f31ef293-3128-44f8-b05a-d70d15d3450e", {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer <your_access_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    console.log('Card deleted successfully');
  })
  .catch(error => {
    console.error('Error deleting card:', error);
  });

Sample Response

{
  {
    "id": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
    "card_last_four": "1234",
    "deleted_at": "2023-07-11T19:01:45Z",
  }
}

HTTP Request

DELETE https://api.gustitosgo.com/v1/cards/:id

Error Responses

HTTP Status Code Message
401 2002 Invalid authorization
401 2100 Token expired
401 2101 Invalid issuer
401 2102 Authentication token is invalid. Request a new one to continue.
401 2103 Token not found
403 ??? Unauthorized to delete the specified card (authorization failure)
404 3000 Asset not found in DB
500 5000 Unexpected error. See the response message for details.

Example Error Response (Authentication Failure)

{
  "code": 2102,
  "message": "Authentication token is invalid. Request a new one to continue."
}

Returns

Returns the deleted Card.

Transactions

This object represents a transaction within your GoRewards partner instance. Use it to determine user behavior, discern loyalty patterns, calculate debit amounts, and view reward distribution.

Transaction amounts are stored in three currencies:

  1. USD -> All transactions are converted and compared against USD as a baseline, always.
  2. Transaction Currency -> The currency that the transaction originated in
  3. Debit Currency -> The primary currency set to the respective merchant territory, and the currency that we will ultimately bill the merchant in.

Transaction locales are included in the form of an ISO 4217 currency code as well as a conversion rate against USD. Conversion rates are updated periodically and the conversion amount is calculated at the time of transaction import.

The Transaction Object

Unexpanded Transaction Object:

{
  "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "user": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "linked_card": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "merchant": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "debit": "debt_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "reward": "pdrw_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "territory": "terr_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "gross_amount_cents": "2000",
  "transaction_currency_iso4217": "840",
  "transaction_currency_gross_amount_cents": "2000",
  "transaction_currency_conversion_rate": "1.000",
  "debit_currency_iso4217": "840",
  "debit_currency_gross_amount_cents": "2000",
  "debit_currency_conversion_rate": "1.000",
  "transaction_date": "174584200",
  "transaction_import_date": "1745842105",
  "state": "settled",
  "fee_percentage": 0.12,
  "fee_cents": 24
}

Full Transaction Object:

{
  "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "user": {
    "id": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "external_id": "1114",
    "email": "juan_pablo@gorewards.tech",
    "metadata": {
      "first_name": "Juan",
      "last_name": "Pablo",
      "locale": "en_US"
    }
  },
  "linked_card": {
    "id": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
    "user": "user_aca5bdb6-848c-4920-a8de-13fb13fb3926",
    "card_last_four": "1234",
    "card_alias": "My Visa Card",
    "card_type": "visa",
    "credits_earned_cents": 1000,
    "credits_earned": "10.00",
    "created_at": "1748884662",
    "is_ath": false,
    "state": "active"
  },
  "chain": {
    "id": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "name": "Chili's"
  },
  "merchant": {
    "id": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
    "trade_name": "Chili's Dorado",
    "expires_at": "1780427302",
    "created_at": "1748884662",
    "address_street_number": 3924,
    "address_line_one": "Main Street",
    "address_line_two": "Apartment 304",
    "city": "Dorado",
    "returning_visit_multiplier": 2,
    "base_reward_percent": 0.05
  },
  "debit": {
    "id": "debt_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "amount_cents": "2000",
    "currency_iso4217": "840",
    "state": "debited",
    "debited_at": "1748884662"
  },
  "reward": {
    "id": "pdrw_e1d4bfc2-78a3-41d3-bc8a-2f3a5018d93a",
    "amount_cents": "629",
    "is_double_reward": false,
    "state": "settled",
  },
  "territory": {
    "id": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "iso3166": "PR",
    "iso3": "PRI",
    "iso4217": "840",
    "name": "PUERTO_RICO",
    "display_name": "Puerto Rico"
  },
  "gross_amount_cents": "2000",
  "transaction_currency_iso4271": "840",
  "transaction_currency_gross_amount_cents": "2000",
  "transaction_currency_conversion_rate": "1.000",
  "debit_currency_iso4217": "840",
  "debit_currency_gross_amount_cents": "2000",
  "debit_currency_conversion_rate": "1.000",
  "transaction_date": "174584200",
  "transaction_import_date": "1745842105",
  "state": "settled"
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
user string expandable UUID of the user who made the transaction. Can be expanded to contain the full User Object
linked_card string expandable UUID of the card object used in the transaction. Can be expanded to contain the full Card Object
chain integer expandable The id of the associated chain. Can be expanded to contain the full Chain Object.
merchant integer expandable The id of the associated merchant. Can be expanded to contain the full Merchant object.
debit nullable object expandable Defaults to null if not expanded. Can be expanded to contain the full Debit Object.
reward string expandable The uuid of the associated reward. Can be expanded to contain the full Reward Object.
gross_amount_cents number The total amount of the transaction as used in the calculation for fees and rewards in USD.
transaction_currency_iso4217 string The ISO 4217 currency code for the currency used when making the purchase.
transaction_currency_gross_amount_cents number The transaction amount, in cents, as it was reported to the GoRewards system. Represented in the currency used during the transaction.
transaction_currency_conversion_rate string The rate used as a conversion base from the transaction currency to USD.
debit_currency_iso4217 string The ISO 4217 currency code for the currency used when debiting the merchant their transaction fees.
debit_currency_gross_amount_cents number The transaction amount, in cents, in the currency used when debiting the merchant.
transaction_currency_conversion_rate string The rate used as a conversion base from the debit currency to USD.
transaction_date string Time at which the transaction was completed.
transaction_import_date string Time at which the transaction was received by the GoRewards system. This is, typically, at least 2 days after the transaction_date, but can be as much as 15 days after.
state string Current state of the transaction. Can be one of the following values: clear, auth, settled.
fee_percentage string The fee percentage collected from the merchant for this transaction. This is an anticipated value as calculated when importing the transaction. For a finalized debit amount, please see the attached debit object.
fee_cents string The fee amount in cents collected from the merchant for this transaction. This is an anticipated value as calculated when importing the transaction. For a finalized debit amount, please see the attached debit object.

List all Transactions

curl -X GET "https://api.gorewards.tech/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/transactions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  "page": 2,
  "limit": 10,
  "total": 25,
  "total_pages": 3,
  "data": [
    {
      "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "user": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "linked_card": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
      "chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
      "merchant": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
      "debit": "debt_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "reward": "pdrw_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "territory": "terr_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
      "gross_amount_cents": "2000",
      "transaction_currency_iso4271": "840",
      "transaction_currency_gross_amount_cents": "2000",
      "transaction_currency_conversion_rate": "1.000",
      "debit_currency_iso4217": "840",
      "debit_currency_gross_amount_cents": "2000",
      "debit_currency_conversion_rate": "1.000",
      "currency_iso4217": "840",
      "transaction_date": "174584200",
      "transaction_import_date": "1745842105",
      "state": "settled",
      "fee_percentage": 0.12,
      "fee_cents": 24
    }
  ]
}

This endpoint retrieves all transactions.

HTTP Request

GET https://api.gorewards.tech/v1/transactions

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.
page integer The current page that you wish to be displayed. The total count of pages depends on the limit provided. The maximum number of pages and further pagination details can be found in the sample response.
limit integer A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
chain_id integer Limits the resulting datasets to transactions at a particular Chain by ID.
chain_name string Limits the resulting datasets to transactions at a particular Chain by name.
merchant_id integer Limits the resulting datasets to transactions at a particular Merchant by ID.
merchant_name string Limits the resulting datasets to transactions at a particular Merchant by name.
user_id string Limits the resulting datasets to transactions by a particular User by UUID.
transacted dictionary Only return transactions that were made during the given date interval.
processed dictionary Only return transactions that were processed by the GoRewards system during the given date interval.
settled dictionary Only return transactions that were settled by the GoRewards system during the given date interval.
rewarded dictionary Only return transactions that were rewarded by the GoRewards system during the given date interval.

Returns

A dictionary with a data property that contains an array of up to limit transactions

Retrieve a Transaction

curl -X GET "https://api.gorewards.tech/v1/transactions/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/transactions/:id', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  "id": "trsn_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "user": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "linked_card": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
  "chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "merchant": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "debit": "debt_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "reward": "pdrw_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "territory": "terr_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
  "gross_amount_cents": "2000",
  "transaction_currency_iso4271": "840",
  "transaction_currency_gross_amount_cents": "2000",
  "transaction_currency_conversion_rate": "1.000",
  "debit_currency_iso4217": "840",
  "debit_currency_gross_amount_cents": "2000",
  "debit_currency_conversion_rate": "1.000",
  "currency_iso4217": "840",
  "transaction_date": "174584200",
  "transaction_import_date": "1745842105",
  "state": "settled",
  "fee_percentage": 0.12,
  "fee_cents": 24
}

This endpoint retrieves a Transaction Object.

HTTP Request

GET https://api.gorewards.tech/v1/transactions/:id

Query Parameters

Parameter Description
expand query Fields to expand into full information. See expandables.

Returns

Returns the Transaction object for a valid identifier. The identifier in this case is the transaction_id as generated by the GoRewards system when the transaction was created.

Merchants

This object represents a merchant within your GoRewards partner instance. Use it to update contact information, link cards, view transactions, and view rewards.

The Merchant Object

Unexpanded Merchant Object:

{
  "id": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "territory": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "trade_name": "Chili's Dorado",
  "expires_at": "1780427302",
  "created_at": "1748884662",
  "address_street_number": 3924,
  "address_line_one": "Main Street",
  "address_line_two": "Apartment 304",
  "city": "Dorado",
  "zip_code": "12345",
  "processors": "visa",
  "returning_visit_multiplier": 2,
  "base_reward_percent": 0.05,
  "categories": ["Pizza", "Restaurant", "Food"]
}

Full Merchant Object:

{
  "id": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "chain": {
    "id": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "name": "Chili's"
  },
  "territory": {
    "id": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
    "iso3166": "PR",
    "iso3": "PRI",
    "iso4217": "840",
    "name": "PUERTO_RICO",
    "display_name": "Puerto Rico"
  },
  "trade_name": "Chili's Dorado",
  "expires_at": "1780427302",
  "created_at": "1748884662",
  "address_street_number": 3924,
  "address_line_one": "Main Street",
  "address_line_two": "Apartment 304",
  "city": "Dorado",
  "zip_code": "12345",
  "processors": "visa",
  "returning_visit_multiplier": 2,
  "base_reward_percent": 0.05,
  "categories": ["Pizza", "Restaurant", "Food"]
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
chain integer expandable The id of the associated chain. Can be expanded to contain the full Chain Object.
trade_name string The name of the merchant.
expires_at timestamp Time at which the object will expire. Measured in seconds since the Unix epoch.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
address_street_number integer Street number of the merchant.
address_line_one string Address line one of the merchant.
address_line_two string Address line two of the merchant.
city string City of the merchant.
zip_code integer Zip code of the merchant.
returning_visit_multiplier float Multiplier for rewards earned for a returning visit at the merchant. 2 indicates that return visits within the same calendar month will generate double rewards.
base_reward_percent float Base percentage of transaction amount to be given as rewards for the merchant.
categories list All categories that have been assigned to the merchant.

Get all Merchants

curl -X GET "https://api.gorewards.tech/v1/merchants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/merchants', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  "page": 2,
  "limit": 10,
  "total": 25,
  "total_pages": 3,
  "data": [
    {
        "id": 10,
        "trade_name": "CSV 9",
        "expires_at": "2024-07-19T15:04:29.670Z",
        "created_at": "2023-07-19T15:04:29.670Z",
        "google_place_id": "null",
        "address_street_number": 3924,
        "address_line_one": "Main Street",
        "address_line_two": "Apartment 304",
        "city": "Dorado",
        "zip_code": "12345",
        "processors": "visa",
        "returning_visit_multiplier": 2,
        "base_reward_percent": 0.05
    },
    {
        "id": 10,
        "trade_name": "CSV 9",
        "expires_at": "2024-07-19T15:04:29.670Z",
        "created_at": "2023-07-19T15:04:29.670Z",
        "google_place_id": "null",
        "address_street_number": 3924,
        "address_line_one": "Main Street",
        "address_line_two": "Apartment 304",
        "city": "Dorado",
        "zip_code": "12345",
        "processors": "visa",
        "returning_visit_multiplier": 2,
        "base_reward_percent": 0.05
    }
  ]
}

This endpoint retrieves all merchants.

HTTP Request

GET https://api.gorewards.tech/v1/merchants

Query Parameters

Parameter Description
territory_id integer The ID of the country to pull merchants from.
chain_id integer The ID of the chain to retrieve associated merchants.
account_types string The type of users to retrieve.
trade_name string The trade name of the merchant to search for.
page integer The page number of results to return.
per_page integer The number of results to return per page.

Returns

A dictionary with a data property that contains an array of up to limit merchants

Get a Specific Merchant

curl -X GET "https://api.gorewards.tech/v1/merchants/:id" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_api_token_here>"

fetch('https://api.gorewards.tech/v1/merchants/:id', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your_api_token_here>'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log('Data received:', data);
  })
  .catch(error => {
    console.error('Error fetching data:', error);
  });

Sample Response

{
  "id": 10,
  "trade_name": "CSV 9",
  "expires_at": "2024-07-19T15:04:29.670Z",
  "created_at": "2023-07-19T15:04:29.670Z",
  "google_place_id": "null",
  "address_street_number": 3924,
  "address_line_one": "Main Street",
  "address_line_two": "Apartment 304",
  "city": "Dorado",
  "zip_code": "12345",
  "processors": "visa",
  "returning_visit_multiplier": 2,
  "base_reward_percent": 0.05
}

This endpoint retrieves a specific merchant.

HTTP Request

GET https://api.gorewards.tech/v1/merchants/:id

Query Parameters

No Parameters.

Returns

Returns the Transaction object for a valid identifier. The identifier in this case is the merchant_id.

Chains

This object represents a chain of merchants within your GoRewards partner instance. A chain can be used to related multiple merchants to each other, and every merchant has a chain; regardless of whether the merchant is a conglomerate or a stand alone entity.

A chain can have merchants that span multiple territories within your GoRewards partner instance.

The Chain Object

Unexpanded Chain Object:

"chain": {
  "id": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "name": "Chili's",
  "created_at": "1748884662"
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
name string The name of the chain.
created_at timestamp Time at which the object was created. Measured in seconds since the Unix epoch.

Territories

The concept of a territory within GoRewards applies to any partner who has a multi-country presence, or a unique presence in area that supports multiple currencies.

An example of a territory would be an international company who has a presence in both France and Germany, yet would like the program to be attached. Each territory in this example would have unique configurations, operate in unique currencies, etc.

Certain elements like chains exist across all territories within a partners organization.

USD (ISO-4217 840) is the primary currency used by the GoRewards system. In the event a primary currency for a territory differs from USD, GoRewards will maintain a conversion rate (updated periodically) and automatically convert all transaction values. Transaction values will be provided in both USD and the currency chosen for a territory.

The Territory Object

Unexpanded Territory Object:

{
  "id": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "iso3166": "PR",
  "iso3": "PRI",
  "iso4217": "840",
  "name": "PUERTO_RICO",
  "display_name": "Puerto Rico"
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
iso3166 string The 2 digit ISO 3166-2 code that exists for the territory.
iso3 string The 2 digit ISO 3166-1 alpha-3 code that exists for the territory.
iso4217 string The 2 digit ISO 4217 code that exists to denote the primary currency within the territory. This will be the primary currency used when generating rewards and
name string A slugified representation of the territory name
display_name string A human readable representation of the territory name

Debits

This object represents a debit within your GoRewards partner instance. A debit is how fees are collected from a merchant.

In the event fees are collected via ACH, a debit and a settled transaction indicate fees that should have been realized to your bank account. In all other collection instances, a debit and a settled transaction represent the creation and transmission of a debit, but no guarantee that funds have changed hands.

The Debit Object

Unexpanded Chain Object:

"debit": {
  "id": "debt_1b9e326f-cf53-4720-aa05-955a61f5e76e",
  "amount_cents": "2000",
  "currency_iso4217": "840",
  "state": "debited",
  "debited_at": "1748884662"
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
amount_cents string The total amount debited from the merchant.
currency_iso4217 string The ISO 4217 currency code used when debiting the merchant.
state timestamp The current state the debit exists in. Can be one of the following values: pending, failed, nothing_to_debit, ready_to_debit, debited.

Rewards

This object represents the reward that was distributed from a qualifying transaction. Use it to help determine how a reward amount was calculated.

The Reward Object

Full Reward Object:

{
  "id": "pdrw_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
  "amount_cents": 100,
  "retries": 0,
  "state": "Settled",
  "is_double_reward": true,
  "reward_cents": 100,
  "reward_currency_iso4217": 840,
  "reward_currency_conversion_rate": 1.00
}
Parameter Description
id string A unique ID for the object generated by the GoRewards system.
amount_cents number The total reward that was distributed, in USD.
retries number The number of retries used when attempting to communicate with a partner webhook endpoint. A reward will be retried 25 times before manual intervention is required.
state string Current status of the Reward. Can be one of the following values: pending, failed, settled.
is_double_reward boolean True if this reward was doubled as a return visit to a merchant in calendar month, false otherwise
reward_currency_amount_cents number The total reward that was distributed, in the primary currency configured for the respective territory.
reward_currency_iso4217 string The ISO 4217 currency code for the currency used when distributing the reward amount.
reward_currency_conversion_rate string The rate used as a conversion base from USD to the reward currency.

Webhooks

Webhooks are the primary way that GoRewards communicates important data events back to the implementing partner. They convey details like card activation, user registration, transaction processing, and even indicate how many rewards should be given to a user after a transaction.

Webhooks are categorized into Event Types. Webhook events are currently supported for Linked Cards, Users, Transactions.

Webhooks will, by default, attempt to sent their payload 25 times with an exponential backoff on failed attempts. A webhook must receive a 200 response from the partner to prevent additional retries.

GoRewards cannot guarantee the uniqueness of data received through the webhook, and recommend that all partners implement an idempotent endpoint to receive the payload.

Linked Card Event Keys

Event Key Description
linked_cards.added Triggered when a user successfully links a new card, active or not. "linked_cards.active" will also be triggered when the card initially becomes active
linked_cards.removed Triggered when a user removes a linked card
linked_cards.updated Triggered when a linked card is updated
linked_cards.inactive Triggered when the user removes their last linked card
linked_cards.active Triggered when a card becomes active in all available processors
linked_cards.activation_failed Triggered when a card fails activation after all retries

Webhook Payload

Sample Payload

{
  "key": "event-key",
  "payload": {
    "external_user_id": "abc123",
    "linked_card_id": "card-uuid",
    "linked_card_alias": "Old Card",
    "linked_card_last_four": "5678",
    "linked_card_type": "mastercard",
    "user_id": "user-uuid",
    "active_card_count": "1",
    "created_at": "2025-03-15T12:30:00Z"
  }
}
Request Value Description
key string Webhook Event Key
external_user_id string External system ID for the user (e.g., Gustazos ID)
linked_card_id string UUID of the linked card
linked_card_alias string User-defined name or alias for the card
linked_card_last_four string Last 4 digits of the card number
linked_card_type string Card brand or type (e.g., "visa", "mastercard")
user_id string UUID of the internal user record
active_card_count string Number of remaining active cards for the user after the event
created_at string ISO8601 timestamp of when the card was originally linked

User Event Keys

Event Key Description
users.created Triggered when a user is created
users.updated Triggered when a user is updated
users.deleted Triggered when a user is deleted

users.created

Sample Payload

{
  "key": "users.created",
  "payload": {
    "external_user_id": "abc123",
    "email": "newuser@example.com",
    "user_id": "user-uuid",
    "created_at": "2025-04-29T22:00:00Z"
  }
}
Request Value Description
key string Webhook Event Key
external_user_id string External system ID for the user (e.g., Gustazos ID)
email string A valid email that maps to the user in the parent system. This must be unique across the entire GoRewards system, however it can be updated in the future.
user_id string Unique identifier generated for the record by the GoRewards system
created_at string ISO8601 timestamp of when the user was created
metadata dictionary Initial user metadata. See User Metadata

users.updated

{
  "key": "users.updated",
  "payload": {
    "user_id": "user-uuid",
    "updated_at": "2025-05-01T15:42:00Z"
  }
}
Request Value Description
key string Webhook Event Key
user_id string Unique identifier generated for the record by the GoRewards system
updated_at string ISO8601 timestamp of when the user was last updated

users.deleted

{
  "key": "users.deleted",
  "payload": {
    "user_id": "user-uuid",
    "deleted_at": "2025-05-02T10:00:00Z"
  }
}
Request Value Description
key string Webhook Event Key
user_id string Unique identifier generated for the record by the GoRewards system
deleted_at string ISO8601 timestamp of when the user was deleted

Transaction Event Keys

Event Key Description
transactions.auth Triggered when a transaction is authorized (via real-time ITN)
transactions.clear Triggered when a transaction is validated and recorded in batch
transactions.settled Triggered when a transaction is fully settled (debit confirmed)

Webhook Payload

Sample Payload

{
  "key": "transactions.clear",
  "payload": {
    "merchant_transaction_id": "txn-uuid",
    "merchant_id": "merchant-uuid",
    "user_id": "user-uuid",
    "external_user_id": "abc123",
    "card_id": "card-uuid",
    "card_type": "visa",
    "card_last_four": "4242",
    "gross_total_cents": "9500",
    "gross_total": "$95.00",
    "transaction_date": "2025-04-29T18:00:00Z",
    "chain_id": "chain-uuid",
    "chain_name": "La Parrilla",
    "merchant_trade_name": "La Parrilla Grill",
    "merchant_legal_name": "La Parrilla S.A.",
    "merchant_city": "Buenos Aires",
    "merchant_zip_code": "C1000",
    "merchant_latitude": "-34.6037",
    "merchant_longitude": "-58.3816",
    "merchant_visit_count_total": "4",
    "merchant_visit_count_current_month": "1",
    "created_at": "2025-04-29T18:00:00Z"
  }
}
Request Value Description
key string Webhook Event Key
merchant_transaction_id string UUID of the merchant transaction (**only for clear and settled)
merchant_transaction_notification_id string UUID of the transaction notification (**only for auth)
merchant_id string UUID of the merchant
user_id string UUID of the user
external_user_id string External ID of the user (e.g., Gustazos ID)
card_id string UUID of the linked card
card_type string Card type (e.g., "visa", "mastercard")
card_last_four string Last four digits of the card number
gross_total_cents string Transaction amount in cents
gross_total string Transaction amount formatted in currency (e.g., "$95.00")
transaction_date string ISO8601 timestamp when the transaction occurred
chain_id string UUID of the chain the merchant belongs to
chain_name string Name of the chain
merchant_trade_name string Display/trade name of the merchant
merchant_legal_name string Legal business name of the merchant
merchant_city string City where the merchant is located
merchant_zip_code string ZIP/postal code of the merchant
merchant_latitude string Latitude of the merchant location
merchant_longitude string Longitude of the merchant location
merchant_visit_count_total string Total lifetime visits by this user to this merchant
merchant_visit_count_current_month string Visits by this user to this merchant in the current calendar month
created_at string ISO8601 timestamp of the transaction record creation

Examples

The Examples section aims to ease with some of the more complex API operations by providing comprehensive exmaples.

Card Enrollment

Not provided. Please view the example in Javascript

// Helper functions to aid with the required encoding and decoding process
function base64ToArrayBuffer(base64) {
  const binary = atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes.buffer;
}

function arrayBufferToBase64(buffer) {
  const bytes = new Uint8Array(buffer);
  let binary = "";
  for (let b of bytes) {
    binary += String.fromCharCode(b);
  }
  return btoa(binary);
}

// The Base64 encoded RSA Public key as provided by the GoRewards system
const base64Key = `MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvxQAriJvXQC3RjBbvmrUchjsZKc9n6yC8GIZmiMb+ZTQiO00M+IQNa1CdK5KBbCyLouM2AinXpbu/NvX4QvG3yHhZV2Ey/9HOKCuyUTNLD/5vMu090TvRdkIdTAqdAUxUdVJu12sp/GljYHbEwzEdTAEbIr53/VmICDoG+sJr6Fr9+YV8sQ+dGtH/RuEcny1QuEck12O/W25AugKIupTkIP9Z1lKDa4sqoHPMNq3Ae3Q1ufMlBYlW4huBQLiO7mZJVMNOs4j0jQOlJ4SZyA9xT4QLIBiX1thIcCdOJakn5uZCzq8P6huYpK4+zlJuPYE2knLHzyc6yPjkOoY7uJ1GwIDAQAB`;

// The card PAN as provided by the end user
const message = "4111111111111111";

const keyBuffer = base64ToArrayBuffer(base64Key);

crypto.subtle.importKey(
  "spki",
  keyBuffer,
  {
    name: "RSA-OAEP",
    hash: "SHA-256"
  },
  false,
  ["encrypt"]
).then(publicKey => {
  const encoder = new TextEncoder();
  const data = encoder.encode(message);

  return crypto.subtle.encrypt(
    { name: "RSA-OAEP", hash: "SHA-256" },
    publicKey,
    data
  );
}).then(encrypted => {
  // The encrypted payload that can be sent to the GoRewards backend
  const encryptedBase64 = arrayBufferToBase64(encrypted);
}).catch(console.error);

Enrolling a new card is a 2-step process that ensures the secure transmission of data between your system and the GoRewards processing system.

In addition to enhanced security, the 2-step system ensures that PCI Compliance standards are followed in both your platform and the GoRewards system through the use of a 1-time use key for card encryption; allowing requests to be sent to your backend without any direct reference to a card PAN or the means of which to decrypt.

To begin, a request must be made to our prepare card endpoint. The response from this endpoint will return 2 distinct pieces of information:

The public key provided by the GoRewards prepare endpoint in conjunction with the SubleCrpyto Javascript support will allow the secure transmission of the card pan to the GoRewards system.

After the card PAN is encrypted and Base64 encoded, it must be transmitted securely to the GoRewards system via your backend using a server-to-server connection.

shell javascript