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);
});
{
"data": {
"uuid": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253",
"gross_amount_cents": 19107,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19107,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "214",
"debit_currency_gross_amount_cents": 1142598,
"debit_currency_conversion_rate": "59.8",
"transaction_date": "2026-05-03T17:07:17Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1577,
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"linked_card": "card_51720bd3-7359-4ea3-8bb4-9efeb10dd503",
"chain": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"merchant": "mcht_2b1e24dd-5702-4cb3-a0b2-fdb0a2fd29a1",
"debit_detail": "debd_7d66c2bf-35d9-4205-9eac-54fcf7fe0b2c",
"reward": "pdrw_3d1279da-142f-402a-90b8-cb4cd52f1fe2",
"territory": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224"
}
}
Full Transaction Object:
{
"data": {
"uuid": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253",
"gross_amount_cents": 19107,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19107,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "214",
"debit_currency_gross_amount_cents": 1142598,
"debit_currency_conversion_rate": "59.8",
"transaction_date": "2026-05-03T17:07:17Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1577,
"user": {
"uuid": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"external_id": "1141927",
"email": "user@local.host",
"created_at": "2026-05-29T19:27:36Z",
"locale": "es_pr"
},
"linked_card": {
"uuid": "card_51720bd3-7359-4ea3-8bb4-9efeb10dd503",
"card_last_four": "0004",
"deleted_at": null,
"created_at": "2026-05-29T19:27:36Z",
"card_alias": "My Ath",
"card_type": "ath",
"credits_earned_cents": 0,
"is_ath": true,
"state": "active",
"processor_states": {
"evertec": {
"state": "active"
}
},
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9"
},
"chain": {
"uuid": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"name": "Chilli's",
"created_at": "2026-05-29T19:27:36Z"
},
"merchant": {
"uuid": "mcht_2b1e24dd-5702-4cb3-a0b2-fdb0a2fd29a1",
"chain": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"territory": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224",
"trade_name": "Chilli's 0",
"expires_at": "2036-05-29T19:27:36Z",
"created_at": "2026-05-29T19:27:36Z",
"address_street_number": "9",
"address_line_one": "First Ave",
"address_line_two": null,
"city": "Dorado",
"zip_code": "90210",
"processors": [
"evertec"
],
"returning_visit_multiplier": "2.0",
"base_reward_percent": "0.05",
"categories": [
"Restaurant"
],
"state": "expiring"
},
"debit_detail": {
"uuid": "debd_7d66c2bf-35d9-4205-9eac-54fcf7fe0b2c",
"amount_cents": 94304,
"currency_iso4217": "214",
"state": "failed",
"debited_at": null,
"merchant_debit": "debt_c6fb6025-2b0c-48ef-b61e-98a6bd8f4f07",
"transaction": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253"
},
"reward": {
"uuid": "pdrw_3d1279da-142f-402a-90b8-cb4cd52f1fe2",
"amount_cents": 2293,
"retries": 1,
"state": "failed",
"is_double_reward": true,
"reward_cents": 2293,
"reward_currency_iso4217": "840",
"reward_currency_conversion_rate": "1.0"
},
"territory": {
"uuid": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224",
"iso3166": "DO",
"iso3": "DOM",
"iso4217": null,
"name": "DOMINICAN REPUBLIC",
"display_name": "Dominican Republic"
}
}
}
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. Additionally, you can expand as many objects as you would like in one request by simply including multiple keys in the expand query, for example: ?expand=chain,territory.
Expandable objects also allow for nested expansions, with a maximum of 3 nested expansions, for example, debit_detail.merchant_debit.debit_batch. 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 wo parameters: per_page and page,
Pagination results are included on all list API endpoints, and are enforced through defaults in the event that details have been omitted.
Sample Response with Pagination:
{
"meta": {
"current_page": 1,
"per_page": 25,
"page_count": 1,
"total": 4
},
"data": [
{
"uuid": "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 number | The number of items that are available in the response for your current query. |
| per_page number | The number of items that are returned on each page. Defaults to 25 with a maximum of 100. |
| page_count 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
fromandtoare provided and are within 31 days of each other, you will return a full dataset
// Request
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-08-11T19:01:45Z"
}
// Response
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-08-11T19:01:45Z"
}
When both a
fromandtoare provided but are move than 31 days apart, we will take thefromand modify thetobe within range
// Request
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-09-15T19:01:45Z"
}
// Response
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-08-11T19:01:45Z"
}
When a
fromis provided with noto, we will return 31 days from the providedfromdate
// Request
{
"from": "2023-07-11T19:01:45Z"
}
// Response
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-08-11T19:01:45Z"
}
When a
tois provided with nofromrange, we will return 31 days before the providedtodate
// Request
{
"to": "2023-08-11T19:01:45Z"
}
// Response
{
"from": "2023-07-11T19:01:45Z",
"to": "2023-08-11T19:01:45Z"
}
Errors
GoRewards utilizes conventional HTTP response codes for all errors encountered inside the API service, alongside more detailed internal codes and messages to provide further assistance.
Conventional HTTP Errors
Generally:
2xxcode indicates a success.4xxcode indicates an error related to the information provided5xxcode indicates an error on the server's side
| 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
{
"error": {
"code": "encryption_key_invalid",
"message": "Encryption key is invalid",
"retryable": false
}
}
| HTTP Status | Code | Message |
|---|---|---|
| 400 | validation_errors | Invalid request parameters |
| 422 | invalid_date_range | Invalid date range, from must be greater than to |
| 422 | invalid_expansion_depth | Invalid expansion depth, maximum depth per item is 3 |
| 422 | card_type_not_found | Card type not found |
| 422 | card_type_invalid | Card type unsupported |
| 422 | card_alias_invalid | Card nickname invalid |
| 422 | card_limit_exceeded | Card limit Exceeded |
| 422 | encryption_key_invalid | Encryption key is invalid |
| 404 | user_not_found | User not found |
| 409 | email_taken | A user with that email already exists |
| 409 | external_id_taken | A user with that external_id already exists |
| 422 | invalid_user_locale | Invalid user locale provided |
| 422 | invalid_user_create | Invalid user attributes |
| 422 | invalid_user_update | Invalid user attributes |
| 403 | invalid_authorization | Invalid authorization |
| 401 | invalid_access_token | Invalid Access Token |
| 401 | authorization_missing | Authorization header is required |
| 404 | record_not_found | Resource not found |
| 500 | internal_server_error | Internal Server error |
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.
The User Object
User Object:
{
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"external_id": "1114",
"created_at": "2023-07-11T19:01:45Z",
"email": "juan_pablo@gorewards.tech",
"metadata": {
"first_name": "Juan",
"last_name": "Pablo",
"locale": "en_us"
}
}
Deleted User Object
{
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"deleted_at": "2023-07-11T19:01:45Z",
"card_last_four": "7223"
}
| 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
{
"meta": {
"current_page": 1,
"per_page": 25,
"total": 2,
"total_pages": 1
},
"data": [
{
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"external_id": "1114",
"created_at": "2023-07-11T19:01:45Z",
"email": "juan_pablo@gorewards.tech",
"metadata": {
"first_name": "Juan",
"last_name": "Pablo",
"locale": "en_us"
}
},
{
"uuid": "user_b8d71a5c-81de-4e59-87a1-c7725e4b1234",
"external_id": "1115",
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": null,
"email": "lisa.marie@gorewards.tech",
"metadata": {
"first_name": "Lisa",
"last_name": "Marie",
"locale": "es_pr"
}
}
]
}
This endpoint retrieves all undeleted 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 per_page provided. The maximum number of pages and further pagination details can be found in the sample response. |
| per_page | A limit on the number of objects to be returned in each page. Limit can range between 1 and 100, and the default is 25. |
Returns
A dictionary with a data property that contains an array of up to per_page customers
Retrieve a User
curl -X GET "https://api.gorewards.tech/v1/user/user_b8d71a5c-81de-4e59-87a1-c7725e4b1234?identifier=internal" \
-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=internal', {
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
{
"data": {
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"external_id": "1114",
"created_at": "2023-07-11T19:01:45Z",
"email": "juan_pablo@gorewards.tech",
"metadata": {
"first_name": "Juan",
"last_name": "Pablo",
"locale": "en_us"
}
}
}
This endpoint retrieves a User Object. It may also return the same object as a Deleted User, depending on the user's state.
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. eexternal 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. |
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 404 | user_not_found | User not found |
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
{
"data": {
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"external_id": "1114",
"created_at": "2023-07-11T19:01:45Z",
"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 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. |
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 409 | email_taken | A user with that email already exists |
| 409 | external_id_taken | A user with that external_id already exists |
| 422 | invalid_user_locale | Invalid user locale provided |
| 422 | invalid_user_create | Invalid user attributes |
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
{
"data": {
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"external_id": "1114",
"created_at": "2023-07-11T19:01:45Z",
"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 an empty string "" |
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 409 | email_taken | A user with that email already exists |
| 422 | invalid_user_locale | Invalid user locale provided |
| 422 | invalid_user_update | Invalid user attributes |
| 404 | user_not_found | User not found |
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
{
"data": {
"uuid": "user_560062e6-2ce6-4c4d-8daa-d3540998f3d0",
"deleted_at": "2023-07-11T19:01:45Z",
"card_last_four": "7223"
}
}
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.
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 404 | user_not_found | User not found |
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,
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": null,
"is_ath": false,
"state": "active",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"state": "active"
}
}
}
Full Card Object:
{
"uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
"user": {
"uuid": "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,
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": null,
"is_ath": false,
"state": "active",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"state": "active"
}
}
}
Deleted Card Object:
{
{
"uuid": "card_f31ef293-3128-44f8-b05a-d70d15d3450e",
"card_last_four": "1234",
"deleted_at": "2023-07-11T19:01:45Z",
}
}
Encryption Key Object:
{
{
"public_key": "encoded-key",
"reference_id": "aca5bdb6-848c-4920-a8de-13fb13fb3926",
"valid_until": "2023-07-11T19:01:45Z"
}
}
| 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 of your currency. |
| 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, processing. |
| processor_states dictionary | The current state of the card in each specific processor, being one of: created, active, inactive, failed, pending_deactivation. |
| public_key string | Public RSA key used to encrypt a card number |
| reference_id string | Reference ID matching the RSA key used to encrypt a card number |
| valid_until string | Expiry date of the RSA key used to encrypt a card number |
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
{
"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",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"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
- 200 OK – A single linked card object.
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
{
"meta": {
"current_page": 1,
"per_age": 25,
"total": 2,
"page_count": 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",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"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": "visa",
"credits_earned_cents": 500,
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": "2023-07-11T19:01:45Z",
"is_ath": true,
"state": "active",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"state": "active"
}
}
}
]
}
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
- 200 OK – A list of the user’s linked cards. The array may be empty.
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 404 | user_not_found | User not found |
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
{
"data": {
"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 a timestamp indicating when the key is valid until.
Link a New Card
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
{
"data": {
"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,
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": null,
"is_ath": false,
"state": "active",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"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. |
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 422 | card_type_not_found | Card type not found |
| 422 | card_type_invalid | Card type unsupported |
| 422 | card_alias_invalid | Card nickname invalid |
| 422 | card_limit_exceeded | Card limit Exceeded |
| 422 | encryption_key_invalid | Encryption key is invalid |
| 404 | user_not_found | User not found |
Returns
Returns the default card object for the successfully linked card. Unsuccessful linkages will return a detailed error.
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
{
"data": {
"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,
"created_at": "2023-07-11T19:01:45Z",
"deleted_at": null,
"is_ath": true,
"state": "active",
"processor_states": {
"visa": {
"state": "active"
},
"evertec": {
"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. |
Unique Error Responses
| HTTP Status | Code | Message |
|---|---|---|
| 422 | card_type_not_found | Card type not found |
| 422 | card_type_invalid | Card type unsupported |
| 422 | card_alias_invalid | 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
{
"data": {
"uuid": "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
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:
- USD -> All transactions are converted and compared against USD as a baseline, always.
- Transaction Currency -> The currency that the transaction originated in
- 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:
{
"data": {
"uuid": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253",
"gross_amount_cents": 19107,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19107,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "214",
"debit_currency_gross_amount_cents": 1142598,
"debit_currency_conversion_rate": "59.8",
"transaction_date": "2026-05-03T17:07:17Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1577,
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"linked_card": "card_51720bd3-7359-4ea3-8bb4-9efeb10dd503",
"chain": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"merchant": "mcht_2b1e24dd-5702-4cb3-a0b2-fdb0a2fd29a1",
"debit_detail": "debd_7d66c2bf-35d9-4205-9eac-54fcf7fe0b2c",
"reward": "pdrw_3d1279da-142f-402a-90b8-cb4cd52f1fe2",
"territory": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224"
}
}
Full Transaction Object:
{
"data": {
"uuid": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253",
"gross_amount_cents": 19107,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19107,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "214",
"debit_currency_gross_amount_cents": 1142598,
"debit_currency_conversion_rate": "59.8",
"transaction_date": "2026-05-03T17:07:17Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1577,
"user": {
"uuid": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"external_id": "1141927",
"email": "user@local.host",
"created_at": "2026-05-29T19:27:36Z",
"locale": "es_pr"
},
"linked_card": {
"uuid": "card_51720bd3-7359-4ea3-8bb4-9efeb10dd503",
"card_last_four": "0004",
"deleted_at": null,
"created_at": "2026-05-29T19:27:36Z",
"card_alias": "My Ath",
"card_type": "ath",
"credits_earned_cents": 0,
"is_ath": true,
"state": "active",
"processor_states": {
"evertec": {
"state": "active"
}
},
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9"
},
"chain": {
"uuid": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"name": "Chilli's",
"created_at": "2026-05-29T19:27:36Z"
},
"merchant": {
"uuid": "mcht_2b1e24dd-5702-4cb3-a0b2-fdb0a2fd29a1",
"chain": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"territory": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224",
"trade_name": "Chilli's 0",
"expires_at": "2036-05-29T19:27:36Z",
"created_at": "2026-05-29T19:27:36Z",
"address_street_number": "9",
"address_line_one": "First Ave",
"address_line_two": null,
"city": "Dorado",
"zip_code": "90210",
"processors": [
"evertec"
],
"returning_visit_multiplier": "2.0",
"base_reward_percent": "0.05",
"categories": [
"Restaurant"
],
"state": "expiring"
},
"debit_detail": {
"uuid": "debd_7d66c2bf-35d9-4205-9eac-54fcf7fe0b2c",
"amount_cents": 94304,
"currency_iso4217": "214",
"state": "failed",
"debited_at": null,
"merchant_debit": "debt_c6fb6025-2b0c-48ef-b61e-98a6bd8f4f07",
"transaction": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253"
},
"reward": {
"uuid": "pdrw_3d1279da-142f-402a-90b8-cb4cd52f1fe2",
"amount_cents": 2293,
"retries": 1,
"state": "failed",
"is_double_reward": true,
"reward_cents": 2293,
"reward_currency_iso4217": "840",
"reward_currency_conversion_rate": "1.0"
},
"territory": {
"uuid": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224",
"iso3166": "DO",
"iso3": "DOM",
"iso4217": null,
"name": "DOMINICAN REPUBLIC",
"display_name": "Dominican Republic"
}
}
}
| Parameter | Description |
|---|---|
| uuid string | A unique ID for the object generated by the GoRewards system. |
| 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 USD to the transaction currency. |
| 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 USD to the debit currency. |
| 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, 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 number | 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. |
| 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 string expandable | The id of the associated chain. Can be expanded to contain the full Chain Object. |
| merchant string expandable | The id of the associated merchant. Can be expanded to contain the full Merchant object. |
| debit_detail string expandable | The id of the associated debit. Can be expanded to contain the full DebitDetail Object. |
| reward string expandable | The uuid of the associated reward. Can be expanded to contain the full Reward Object. |
| territory string expandable | The uuid of the associated territory. Can be expanded to contain the full Territory 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
{
"meta": {
"current_page": 1,
"per_page": 25,
"total": 1,
"total_pages": 1,
"transacted_at": {
"from": "2026-05-01T15:53:42Z",
"to": "2026-06-01T15:53:42Z"
},
"processed_at": {
"from": "2026-05-01T15:53:42Z",
"to": "2026-06-01T15:53:42Z"
},
"settled_at": {
"from": "2026-06-01T12:53:42Z",
"to": "2026-06-01T15:53:42Z"
}
},
"data": [
{
"uuid": "trsn_8758bb40-c6e1-498c-855a-e08ec13e17b0",
"gross_amount_cents": 3225,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 3225,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "840",
"debit_currency_gross_amount_cents": 3225,
"debit_currency_conversion_rate": "1.0",
"transaction_date": "2026-05-30T20:59:00Z",
"transaction_import_date": "2026-05-29T19:27:49Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 267,
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"linked_card": "card_b90cf5d0-d141-490b-b5db-71dab8d9189d",
"chain": "chin_61eb13bc-a4be-4330-811a-0d05e45e11e9",
"merchant": "mcht_b9024369-c99f-49f1-897e-d0455e39ce9f",
"debit_detail": "debd_d709dc4c-00fb-4aae-a5b3-295d393719f6",
"reward": null,
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9"
}
]
}
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 per_page provided. The maximum number of pages and further pagination details can be found in the sample response. |
| per_page integer | A limit on the number of objects to be returned in each page. Limit can range between 1 and 100, and the default is 25. |
| chain_id string | Limits the resulting datasets to transactions at a particular Chain by ID. Mutually exclusive with chain_name. |
| chain_name string | Limits the resulting datasets to transactions at a particular Chain by name. Mutually exclusive with chain_id. |
| merchant_id string | Limits the resulting datasets to transactions at a particular Merchant by ID. Mutually exclusive with merchant_name. |
| merchant_name string | Limits the resulting datasets to transactions at a particular Merchant by name. Mutually exclusive with merchant_id. |
| user_id string | Limits the resulting datasets to transactions by a particular User by UUID. |
| state string | Limits the resulting datasets to transactions in a current state: cleared or settled |
| transacted dictionary | Only return transactions that were made during the given date interval. See Date Ranges for help with usage. |
| processed dictionary | Only return transactions that were processed by the GoRewards system during the given date interval. See Date Ranges for help with usage. |
| settled dictionary | Only return transactions that were settled by the GoRewards system during the given date interval. See Date Ranges for help with usage. |
| rewarded dictionary | Only return transactions that were rewarded by the GoRewards system during the given date interval. See Date Ranges for help with usage. |
Returns
A dictionary with a data property that contains an array of up to per_page 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
{
"data": {
"uuid": "trsn_9605af3b-abff-4e09-b661-ea1e78f56253",
"gross_amount_cents": 19107,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19107,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "214",
"debit_currency_gross_amount_cents": 1142598,
"debit_currency_conversion_rate": "59.8",
"transaction_date": "2026-05-03T17:07:17Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1577,
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"linked_card": "card_51720bd3-7359-4ea3-8bb4-9efeb10dd503",
"chain": "chin_5d63b69c-b3fb-4376-8283-9350991a33b5",
"merchant": "mcht_2b1e24dd-5702-4cb3-a0b2-fdb0a2fd29a1",
"debit_detail": "debd_7d66c2bf-35d9-4205-9eac-54fcf7fe0b2c",
"reward": "pdrw_3d1279da-142f-402a-90b8-cb4cd52f1fe2",
"territory": "terr_b30952c5-8f9a-497e-a9fc-48fabd345224"
}
}
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 uuid 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:
{
"uuid": "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": "2023-08-11T19:01:45Z",
"created_at": "2023-07-11T19:01:45Z",
"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.0",
"base_reward_percent": "0.05",
"categories": ["Pizza", "Restaurant", "Food"],
"state": "expiring"
}
Full Merchant Object:
{
"uuid": "mcht_7ab5bbfd-71d3-4c76-91d1-98b8efdc49a1",
"chain": {
"uuid": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
"name": "Chili's",
"created_at": "2023-07-11T19:01:45Z"
},
"territory": {
"uuid": "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": "2023-07-11T19:01:45Z",
"created_at": "2023-07-11T19:01:45Z",
"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.0",
"base_reward_percent": "0.05",
"categories": ["Pizza", "Restaurant", "Food"],
"state": "expiring"
}
| Parameter | Description |
|---|---|
| uuid string | A unique ID for the object generated by the GoRewards system. |
| chain string expandable | The id of the associated chain. Can be expanded to contain the full Chain Object. |
| territory string expandable | The id of the associated territory. Can be expanded to contain the full Territory Object. |
| trade_name string | The name of the merchant. |
| expires_at timestamp | Time at which the object will expire. |
| created_at timestamp | Time at which the object was created. |
| address_street_number string | 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 string | Zip code of the merchant. |
| processors list | All processors the merchant has been activated in. |
| returning_visit_multiplier string | 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 string | Base percentage of transaction amount to be given as rewards for the merchant. |
| categories list | All categories that have been assigned to the merchant. |
| state string | Current state of the merchant, one of: expired, expiring, new, active in order of priority. A merchant may belong to multiple, but the highest priority one will be displayed and it will show up in queries requesting any it belongs to. |
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
{
"meta": {
"current_page": 1,
"per_page": 25,
"total": 2,
"total_pages": 1
},
"data": [
{
"uuid": "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": "2023-08-11T19:01:45Z",
"created_at": "2023-07-11T19:01:45Z",
"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.0",
"base_reward_percent": "0.05",
"categories": ["Pizza", "Restaurant", "Food"],
"state": "expiring"
},
{
"uuid": "mcht_4c6fb2b1-107f-4588-bd97-11f4a60fda89",
"chain": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
"territory": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
"trade_name": "Chili's Dorado 2",
"expires_at": "2023-08-11T19:01:45Z",
"created_at": "2023-07-11T19:01:45Z",
"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.0",
"base_reward_percent": "0.05",
"categories": ["Pizza", "Restaurant", "Food"],
"state": "expiring"
}
]
}
This endpoint retrieves all merchants.
HTTP Request
GET https://api.gorewards.tech/v1/merchants
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
| territory_id string | The UUID of the country to pull merchants from. |
| chain_id string | The UUID of the chain to retrieve associated merchants. |
| state string | The current state of the merchants: expired, expiring, new, active. A merchant may show up in multiple different state queries even if it only displays one, following the same priority system as the returned state data. |
| trade_name string | The trade name of the merchant to search for. |
| page integer | The current page that you wish to be displayed. The total count of pages depends on the per_page provided. The maximum number of pages and further pagination details can be found in the sample response. |
| per_page integer | A limit on the number of objects to be returned in each page. Limit can range between 1 and 100, and the default is 25. |
Returns
A dictionary with a data property that contains an array of up to per_page 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
{
"data": {
"uuid": "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": "2023-08-11T19:01:45Z",
"created_at": "2023-07-11T19:01:45Z",
"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.0",
"base_reward_percent": "0.05",
"categories": ["Pizza", "Restaurant", "Food"],
"state": "expiring"
}
}
This endpoint retrieves a specific merchant.
HTTP Request
GET https://api.gorewards.tech/v1/merchants/:id
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
Returns
Returns the Merchant object for a valid identifier. The identifier in this case is the uuid.
DebitDetails
This object represents a debit detail within your GoRewards partner instance. A debit detail is linked directly to a user's transaction, and is a record of the fee that will be charged to the merchant for that transaction. These are collected into merchant debit batches, representing the actual charge to each merchant.
The DebitDetail Object
Unexpanded DebitDetail Object:
{
"data": {
"uuid": "debd_3e97d007-e18b-48d1-8d36-77b714fa9695",
"amount_cents": 1588,
"currency_iso4217": "840",
"state": "debited",
"debited_at": "2026-06-01T14:58:33.250Z",
"merchant_debit": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"transaction": "trsn_b2d8d27a-b9d3-4f60-8185-42813965a764"
}
}
Expanded DebitDetail Object:
{
"data": {
"uuid": "debd_3e97d007-e18b-48d1-8d36-77b714fa9695",
"amount_cents": 1588,
"currency_iso4217": "840",
"state": "debited",
"debited_at": "2026-06-01T14:58:33.250Z",
"merchant_debit": {
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
},
"transaction": {
"uuid": "trsn_b2d8d27a-b9d3-4f60-8185-42813965a764",
"gross_amount_cents": 19155,
"transaction_currency_iso4217": "840",
"transaction_currency_gross_amount_cents": 19155,
"transaction_currency_conversion_rate": "1.0",
"debit_currency_iso4217": "840",
"debit_currency_gross_amount_cents": 19155,
"debit_currency_conversion_rate": "1.0",
"transaction_date": "2026-05-16T05:49:02Z",
"transaction_import_date": "2026-05-29T19:27:37Z",
"state": "settled",
"fee_percentage": "0.09",
"fee_cents": 1588,
"user": "user_a34af8c1-d5be-42f1-80ef-de028c642ff9",
"linked_card": "card_b90cf5d0-d141-490b-b5db-71dab8d9189d",
"chain": "chin_61eb13bc-a4be-4330-811a-0d05e45e11e9",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_detail": "debd_3e97d007-e18b-48d1-8d36-77b714fa9695",
"reward": "pdrw_c385cab9-a924-40b9-8e6e-e229ccafc567",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9"
}
}
}
| Parameter | Description |
|---|---|
| uuid string | A unique ID for the object generated by the GoRewards system. |
| amount_cents integer | The total amount debited for this transaction. |
| 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. |
| debited_at timestamp | Time at which the debit was settled. This will be the same across each debit_batch. |
| merchant_debit string expandable | The id of the associated merchant_debit. Can be expanded to contain the full MerchantDebit Object. |
| transaction string expandable | The id of the associated transaction. Can be expanded to contain the full Transaction Object. |
Get a Specific Debit Detail
curl -X GET "https://api.gorewards.tech/v1/debit_details/:id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_api_token_here>"
fetch('https://api.gorewards.tech/v1/debit_details/: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
{
"data": {
"uuid": "debd_3e97d007-e18b-48d1-8d36-77b714fa9695",
"amount_cents": 1588,
"currency_iso4217": "840",
"state": "debited",
"debited_at": "2026-06-01T14:58:33.250Z",
"merchant_debit": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"transaction": "trsn_b2d8d27a-b9d3-4f60-8185-42813965a764"
}
}
This endpoint retrieves a specific debit detail.
HTTP Request
GET https://api.gorewards.tech/v1/debit_details/:id
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
Returns
Returns the Debit Detail object for a valid identifier. The identifier in this case is the uuid.
MerchantDebits
This object represents a merchant debit within your GoRewards partner instance. A merchant debit is a compiled batch of debit details corresponding to a specific merchant, and is a record of what the merchant will be charged as part of our fee collection.
In the event fees are collected via ACH, a debit and a settled transaction indicate fees that should have been realized to the 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 MerchantDebit Object
Unexpanded MerchantDebit Object:
{
"data": {
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
}
}
Expanded MerchantDebit Object:
{
"data": {
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": {
"uuid": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"amount_cents": 262038,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33Z",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"merchant_debits": 5
},
"merchant": {
"uuid": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"chain": "chin_61eb13bc-a4be-4330-811a-0d05e45e11e9",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"trade_name": "Walgreens 2",
"expires_at": "2036-05-29T19:27:37Z",
"created_at": "2026-05-29T19:27:37Z",
"address_street_number": "9",
"address_line_one": "Luke Place",
"address_line_two": null,
"city": "Levittown",
"zip_code": "90210",
"processors": [
"evertec"
],
"returning_visit_multiplier": "2.0",
"base_reward_percent": "0.05",
"categories": [
"Restaurant"
],
"state": "expiring"
},
"debit_details": [
{
"uuid": "debd_3e97d007-e18b-48d1-8d36-77b714fa9695",
"amount_cents": 1588,
"currency_iso4217": "840",
"state": "debited",
"debited_at": "2026-06-01T14:58:33.250Z",
"merchant_debit": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"transaction": "trsn_b2d8d27a-b9d3-4f60-8185-42813965a764"
},
{
"uuid": "debd_13180c5a-6372-436f-a7f0-9d3fa98c9954",
"amount_cents": 1168,
"currency_iso4217": "840",
"state": "debited",
"debited_at": "2026-06-01T14:58:33.250Z",
"merchant_debit": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"transaction": "trsn_16ca9fe6-5f52-4149-90ec-eb580acdef83"
}
]
}
}
| Parameter | Description |
|---|---|
| uuid string | A unique ID for the object generated by the GoRewards system. |
| amount_cents integer | The total amount debited to this merchant for all transactions contained. |
| 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. |
| debited_at timestamp | Time at which the debit was settled. This will be the same across each debit_batch. |
| debit_batch string expandable | The id of the associated debit_batch. Can be expanded to contain the full DebitBatch Object. |
| merchant string expandable | The id of the associated merchant. Can be expanded to contain the full Merchant Object. |
| debit_details numberexpandable | The number of individual debit details contained inside this merchant batch. Can be expanded to contain a list of the full DebitDetail Objects. |
Get all Merchant Debits
curl -X GET "https://api.gorewards.tech/v1/merchant_debits" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_api_token_here>"
fetch('https://api.gorewards.tech/v1/merchant_debits', {
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
{
"meta": {
"current_page": 1,
"per_page": 25,
"total": 2,
"total_pages": 1
},
"data": [
{
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
},
{
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
}
]
}
This endpoint retrieves all merchant debits.
HTTP Request
GET https://api.gorewards.tech/v1/merchant_debits
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
| merchant_id string | The UUID of the merchant to find debits for. |
| state string | TThe current state the debit exists in. Can be one of the following values: pending, failed, nothing_to_debit, ready_to_debit, debited. |
| debited_at dictionary | Only return merchant debits that were debited during the given date interval. See Date Ranges for help with usage. |
| page integer | The current page that you wish to be displayed. The total count of pages depends on the per_page provided. The maximum number of pages and further pagination details can be found in the sample response. |
| per_page integer | A limit on the number of objects to be returned in each page. Limit can range between 1 and 100, and the default is 25. |
Returns
A dictionary with a data property that contains an array of up to per_page merchant debits
Get a Specific Merchant Debit
curl -X GET "https://api.gorewards.tech/v1/merchant_debits/:id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_api_token_here>"
fetch('https://api.gorewards.tech/v1/merchant_debits/: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
{
"data": {
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
}
}
This endpoint retrieves a specific merchant debit.
HTTP Request
GET https://api.gorewards.tech/v1/merchant_debits/:id
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
Returns
Returns the Merchant Debit object for a valid uuid.
DebitBatches
This object represents a debit batch within your GoRewards partner instance. A debit batch is a compiled batch of merchant debits within a singular territory.
These debit batches serve as the parent of both merchant debits and debit details, as the debits in each territory are processed all at once in a singular debit batch. As such, this is also where the state and debited_at originates from for both merchant debit and debit detail objects.
The DebitBatch Object
Unexpanded DebitBatch Object:
{
"data": {
"uuid": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"amount_cents": 262038,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33Z",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"merchant_debits": 5
}
}
Expanded DebitBatch Object:
{
"data": {
"uuid": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"amount_cents": 262038,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33Z",
"territory": {
"uuid": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"iso3166": "PR",
"iso3": "PRI",
"iso4217": "840",
"name": "PUERTO RICO",
"display_name": "Puerto Rico"
},
"merchant_debits": [
{
"uuid": "debt_1caeef5f-eed0-4dd7-851f-be7f5bfc415b",
"amount_cents": 48954,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_40a0a164-7c1a-4793-ba4e-54594fe4f518",
"debit_details": 57
},
{
"uuid": "debt_c1b1f895-117a-4358-bbe5-3ca5de03e389",
"amount_cents": 60715,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:25Z",
"debited_at": "2026-06-01T14:58:33.250Z",
"debit_batch": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"merchant": "mcht_d6c613db-b920-4284-8ee9-d3d8cc5240b3",
"debit_details": 61
}
]
}
}
| Parameter | Description |
|---|---|
| uuid string | A unique ID for the object generated by the GoRewards system. |
| amount_cents integer | The total amount debited to this merchant for all transactions contained. |
| 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. |
| created_at timestamp | Time at which the debit was created. |
| debited_at timestamp | Time at which the debit was settled. This will be the same across each debit_batch. |
| territory string expandable | The id of the associated territory. Can be expanded to contain the full Territory Object. |
| debit_details numberexpandable | The number of individual merchant debits contained inside this debit batch. Can be expanded to contain a list of the full MerchantDebit Objects. |
Get all Debit Batches
curl -X GET "https://api.gorewards.tech/v1/debit_batches" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_api_token_here>"
fetch('https://api.gorewards.tech/v1/debit_batches', {
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
{
"data": [
{
"uuid": "mdbt_b13ca608-a5dd-4f6b-9f98-d576271009d3",
"amount_cents": 4410,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-30T00:27:02Z",
"debited_at": "2026-06-01T14:58:36Z",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"merchant_debits": 1
},
{
"uuid": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"amount_cents": 262038,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33Z",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"merchant_debits": 5
}
],
"meta": {
"current_page": 1,
"per_page": 25,
"page_count": 1,
"total": 2,
"debited_at": {
"from": "2026-06-01T12:53:42Z",
"to": "2026-07-02T12:53:42Z"
}
}
}
This endpoint retrieves all debit batches.
HTTP Request
GET https://api.gorewards.tech/v1/debit_batches
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
| merchant_id string | The UUID of the merchant to find debits for. |
| state string | The current state the debit exists in. Can be one of the following values: pending, failed, nothing_to_debit, ready_to_debit, debited. |
| debited_at dictionary | Only return debit batches that were debited during the given date interval. See Date Ranges for help with usage. |
| page integer | The current page that you wish to be displayed. The total count of pages depends on the per_page provided. The maximum number of pages and further pagination details can be found in the sample response. |
| per_page integer | A limit on the number of objects to be returned in each page. Limit can range between 1 and 100, and the default is 25. |
Returns
A dictionary with a data property that contains an array of up to per_page debit batches
Get a Specific Debit Batch
curl -X GET "https://api.gorewards.tech/v1/debit_batches/:id" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your_api_token_here>"
fetch('https://api.gorewards.tech/v1/debit_batches/: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
{
"data": {
"uuid": "mdbt_331cd481-4076-4775-ba9c-71ce0d3baf79",
"amount_cents": 262038,
"currency_iso4217": "840",
"state": "debited",
"created_at": "2026-05-29T19:33:24Z",
"debited_at": "2026-06-01T14:58:33Z",
"territory": "terr_201e39a0-3ec2-4ac2-a4de-b28bf612d8a9",
"merchant_debits": 5
}
}
This endpoint retrieves a specific debit batch.
HTTP Request
GET https://api.gorewards.tech/v1/debit_batches/:id
Query Parameters
| Parameter | Description |
|---|---|
| expand query | Fields to expand into full information. See expandables. |
Returns
Returns the Debit Batch object for a valid uuid.
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:
{
"uuid": "chin_1b9e326f-cf53-4720-aa05-955a61f5e76e",
"name": "Chili's",
"created_at": "2023-07-11T19:01:45Z"
}
| Parameter | Description |
|---|---|
| uuid 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. |
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:
{
"uuid": "terr_1b9e326f-cf53-4720-aa05-955a61f5e76e",
"iso3166": "PR",
"iso3": "PRI",
"iso4217": "840",
"name": "PUERTO_RICO",
"display_name": "Puerto Rico"
}
| Parameter | Description |
|---|---|
| uuid 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 |
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:
{
"uuid": "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 |
|---|---|
| uuid 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 based on the operation they relate to.
Webhooks will, by default, attempt to sent their payload 10 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. With that being said, each subsequent attempt in sending a webhook will include the same id value, allowing it's identification across requests.
Webhook Structure
Webhooks all follow the same structure, providing key details about the webhook on the top-level and a payload dictionary containing the event's information. Each event section will document it's specific payload details.
Example Payload Structure
{
"id":"evt_6f425ad7-a1fd-48e5-9e76-9d79ea5976e6",
"key":"event_key.action",
"created_at":"2026-06-08T18:05:59Z",
"payload":{}
}
| Parameter | Description |
|---|---|
| id string | A unique ID for the webhook instance generated by the GoRewards system. This will be consistent across subsequent attempts. |
| key string | The string code detailing which event is contained inside the payload dictionary, such as transactions.clear. |
| created_at timestamp | The time that this webhook was initially scheduled. |
| payload dictionary | The information for this event. Follows the structure of whichever key is referenced. |
Linked Card Events
The Linked Card webhook serves to provide updates on the current state of your user's card in the GoRewards system.
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 linked card is fully deactivated |
| 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
Linked Card Payload
{
"id":"evt_6f425ad7-a1fd-48e5-9e76-9d79ea5976e6",
"key":"linked_cards.updated",
"created_at":"2026-06-08T18:05:59Z",
"payload":{
"id":"card_07ea3c4a-5d55-4d9d-846b-e77aeb2f9d1d",
"user_id":"user_5f34eedb-98dd-4ecf-a450-593d5e3a191b",
"card_type":"visa",
"card_alias":"linked card2",
"created_at":"2026-04-02T17:09:56Z",
"deleted_at":null,
"processors":[
"evertec",
"visa"
],
"activated_at":"2026-04-02T17:10:07Z",
"card_last_four":"4911",
"deactivated_at":null,
"processor_states":{
"visa":{
"state":"active"
},
"evertec":{
"state":"active"
}
},
"co_brand_provider":"ath"
}
}
| Request Value | Description |
|---|---|
| id string | UUID of the card |
| user_id string | UUID of the user |
| card_type string | Identified branding of the card |
| card_alias string | User's provided alias for the card |
| created_at timestamp | Time that the card was created in the GoRewards system and scheduled to be linked |
| deleted_at timestamp | Time that the card was scheduled for deactivation |
| processors array | Array of the processor names that the card is associated with |
| activated_at timestamp | Time that the card was activated in all processors |
| card_last_four string | Last four digits of the card's PAN |
| deactivated_at timestamp | Time that the card was deactivated in all processors |
| processor_states dictionary | Details on the state of the card in each processor |
| processor_states.{processor_name} dictionary | Dynamic key matching the processor's name |
| processor_states.{processor_name}.state string | The state of the card in this processor. Matches those returned in the Linked Card Object |
| co_brand_provider string | The cobrand provider of the card. Null if the card is not cobranded with a recognized provider |
Transaction Events
The Transaction webhook is used to communicate the state of actual user transactions in the GoRewards system. When the system has received and begun processing a transaction, we will send a transactions.clear event. These represent confirmed records from our processors, are usually delayed, and are considered totally separate from an ITN record. For real-time data that is not involved with our debit and rewards systems, you should utilize ITNs (Transaction Notifications).
Transaction Event Keys
| Event Key | Description |
|---|---|
| transactions.clear | Triggered when a transaction is validated and recorded in a batch |
| transactions.settled | Triggered when a transaction is fully settled (debit confirmed) |
Webhook Payload
Transaction (Clear/Settled) Payload
{
"id":"evt_09e6d0fd-5db4-4bb0-93dc-b27976b99375",
"key":"transactions.settled",
"created_at":"2026-06-08T18:10:05Z",
"payload":{
"id":"trsn_5ee2621b-6d3c-4968-8021-29ff8b3f402b",
"flags":{
"is_debit_card":false
},
"state":"settled",
"card_id":"card_4e76c97d-e6c3-4957-9266-1a46b29c30ed",
"user_id":"user_a9cfddca-f756-49ee-92d5-1c57350ad5a8",
"chain_id":"chin_c219c8b3-eade-4590-a452-7dfc1399aabb",
"processor":{
"name":"visa",
"merchant_caid":"4549102820024",
"transaction_id":"1780862400:4944310809:1164"
},
"reward_id":"pdrw_57e4c385-c407-49ea-ac2b-af87ba96d1a3",
"created_at":"2026-06-07T20:00:07Z",
"settled_at":"2026-06-07T20:00:07Z",
"updated_at":"2026-06-07T20:00:07Z",
"merchant_id":"mcht_c9a4e5d0-66b0-497f-bcd1-172189460e89",
"territory_id":"terr_34d1c210-4af3-40c1-ab0a-967ef189c4d5",
"debit_currency":{
"iso4217":"840",
"fee_percent":"0.0",
"fee_amount_cents":0,
"net_amount_cents":1116,
"gross_amount_cents":1195,
"conversion_rate_from_usd":"1.0"
},
"transaction_date":"2026-06-07T20:00:00Z",
"transaction_currency":{
"iso4217":"214",
"net_amount_cents":1116,
"tax_amount_cents":79,
"gross_amount_cents":956,
"conversion_rate_from_usd":"1.25"
}
}
}
| Request Value | Description |
|---|---|
| id string | UUID of the associated ITN in GoRewards |
| flags dictionary | Additional details about the card used |
| flags.is_debit_card boolean | Whether or not the card utilized was a debit card |
| state string | The state of the transaction, either 'settled' or 'cleared', matching the event key. |
| card_id string | UUID of the card |
| user_id string | UUID of the user |
| chain_id string | UUID of the chain |
| processor dictionary | Details about how the transaction was processed |
| processor.name string | The processor that is handling the transaction |
| processor.merchant_caid string | The ID of the associated merchant in the processor's records. |
| processor.transaction_id string | A unique ID generated for each transaction received |
| reward_id nullable string | UUID of the reward record. This will be null for clear events. |
| created_at timestamp | The date the transaction was received by GoRewards |
| settled_at timestamp | The date the transaction was settled |
| updated_at timestamp | The date the transaction was modified by GoRewards |
| merchant_id string | UUID of the merchant in the GoRewards system |
| territory_id string | UUID of the territory |
| debit_currency dictionary | Details about the currency the debit is being processed in |
| debit_currency.iso4217 string | Currency code for the debit |
| debit_currency.fee_percent string | Debit fee percentage |
| debit_currency.fee_amount_cents number | Fee to be charged to merchant based on net_amount_cents |
| debit_currency.net_amount_cents number | Remaining cents from gross_amount_cents after-tax, used to calculate the merchant's fee. |
| debit_currency.gross_amount_cents number | Amount spent in the corresponding currency |
| debit_currency.conversion_rate_from_usd string | The conversion rate at the time of the debit |
| transaction_date timestamp | The date the transaction was made by the user |
| transaction_currency dictionary | Details about the currency the transaction was made in |
| transaction_currency.iso4217 string | Currency code for the transaction |
| transaction_currency.net_amount_cents number | Remaining cents from gross_amount_cents after-tax, used to calculate the merchant's fee. |
| transaction_currency.tax_amount_cents number | Amount taken from gross_amount_cents to account for taxes. Used to calculate net_amount_cents |
| transaction_currency.gross_amount_cents number | Amount spent in the corresponding currency |
| transaction_currency.conversion_rate_from_usd string | The conversion rate at the time of the transaction |
Transaction Notification Events
The Transaction Notification webhook is a real-time notification of when your user has made a purchase at a participating merchant. These can be utilized to provide real-time feedback to your users, but are not a part of our rewards processing. Confirmed transactions used to begin GoRewards processing are delayed, and will send a separate Transaction Webhook.
Transaction Notification Event Keys
| Event Key | Description |
|---|---|
| transactions.auth | Triggered when a transaction is authorized (via real-time ITN) |
Webhook Payload
ITN Payload
{
"id":"evt_ffc847db-5cb5-46af-b711-f512a2970d26",
"key":"transactions.auth",
"created_at":"2026-06-08T18:02:36Z",
"payload":{
"id":"trnc_484dd7e9-37ee-4432-a264-ad3e680c96d1",
"flags":{
"is_debit_card":false
},
"state":"authorized",
"card_id":"card_ea8a0ac2-3f5e-487d-8a4b-5e8baf7609e3",
"user_id":"user_5f34eedb-98dd-4ecf-a450-593d5e3a191b",
"chain_id":"chin_c219c8b3-eade-4590-a452-7dfc1399aabb",
"processor":{
"name":"visa",
"merchant_caid":3,
"transaction_id":"1772817240:5b2ec328-32b2-4550-a5a5-d7c3113c680c:1773"
},
"created_at":"2026-04-06T17:16:28Z",
"updated_at":"2026-04-06T17:16:28Z",
"merchant_id":"mcht_57812b2b-b892-4f21-86fb-936fa63c4d65",
"territory_id":"terr_34d1c210-4af3-40c1-ab0a-967ef189c4d5",
"transaction_date":"2026-03-06T17:14:00Z",
"transaction_currency":{
"iso4217":"840",
"gross_amount_cents":53500,
"conversion_rate_from_usd":"1.0"
}
}
}
| Payload Value | Description |
|---|---|
| id string | UUID of the associated ITN in GoRewards |
| flags dictionary | Additional details about the card used |
| flags.is_debit_card boolean | Whether or not the card utilized was a debit card |
| state string | The state of the transaction. For ITNs, this will always be authorized |
| card_id string | UUID of the card |
| user_id string | UUID of the user |
| chain_id string | UUID of the chain |
| processor dictionary | Details about how the transaction was processed |
| processor.name string | The processor that is handling the transaction |
| processor.merchant_caid string | The ID of the associated merchant in the processor's records. |
| processor.transaction_id string | A unique ID generated for each transaction received |
| created_at timestamp | The date the ITN was received by GoRewards |
| updated_at timestamp | The date the ITN was modified by GoRewards |
| merchant_id string | UUID of the merchant in the GoRewards system |
| territory_id string | UUID of the territory |
| transaction_date timestamp | The date the transaction was made by the user |
| transaction_currency dictionary | Details about the currency the transaction was made in |
| transaction_currency.iso4217 string | Currency code for the transaction |
| transaction_currency.gross_amount_cents number | Amount spent in the corresponding currency |
| transaction_currency.conversion_rate_from_usd string | The conversion rate at the time of the transaction |
Debit Events
The Debit webhook provides details about the processing of debit batches for each territory your program is activated within.
Debit Event Keys
| Event Key | Description |
|---|---|
| debits.created | Triggered when a debit batch is first created |
| debits.settled | Triggered when a debit batch has been settled |
| debits.failed | Triggered when a debit batch has failed |
Webhook Payload
Debit Payload
{
"id":"evt_f3dbe051-2cb2-4ac1-93d3-91b6208500e0",
"key":"debits.settled",
"created_at":"2026-06-08T18:15:24Z",
"payload":{
"id":"mdbt_20d6dec7-601f-46f2-a976-41cb9f9b6670",
"failed_at":null,
"merchants":[
{
"id":"mcht_561c251f-a76a-475b-aec7-6fce6715f860",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":3124
},
{
"id":"mcht_76e427b1-28bc-4e06-a0c9-62f4a7e462fb",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":517
},
{
"id":"mcht_e65ee3ca-5d3c-4a3b-8433-8ea043a7d83c",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":25250
},
{
"id":"mcht_dd60d3e8-92c2-4ddf-8309-7e1208f45065",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":35409
},
{
"id":"mcht_b900c83e-313a-45e7-b9d3-df90694e9ba9",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":632
},
{
"id":"mcht_2781a239-217f-46ac-8580-a2466a8abb47",
"ends_at":"2026-06-08T18:15:24Z",
"starts_at":"2026-06-06T22:00:07Z",
"fee_amount_cents":574
}
],
"created_at":"2025-01-24T22:00:00Z",
"settled_at":"2025-01-24T22:00:08Z",
"territory_id":"terr_34d1c210-4af3-40c1-ab0a-967ef189c4d5",
"debit_currency":{
"iso4217":"840",
"fee_amount_cents":65506,
"conversion_rate_from_usd":"1.0"
}
}
}
| Payload Value | Description |
|---|---|
| id string | UUID of the associated Debit Batch |
| failed_at timestamp | Time the debit batch failed, if applicable |
| merchants array | Condensed array of merchants involved in the batch |
| merchants.id string | UUID of merchant |
| merchants.ends_at timestamp | End date of the debit period |
| merchants.starts_at string | Start date of the debit period |
| merchants.fee_amount_cents string | Debit fee in this merchant batch |
| created_at timestamp | Time that the debit batch was created |
| settled_at timestamp | Time that the debit batch was settled |
| territory_id string | UUID of the territory |
| debit_currency dictionary | Details about the debit_currency used in this batch |
| debit_currency.iso4217 string | Currency code |
| debit_currency.fee_amount_cents string | Total fees collected in this batch |
| debit_currency.conversion_rate_from_usd string | Conversion rate used at the time of creation |
Merchant Events
The Merchant webhook provides updates on any changes to merchants involved in your partnership.
Merchant Event Keys
| Event Key | Description |
|---|---|
| merchants.created | Triggered when a merchant is first created |
| merchants.updated | Triggered when a merchant is updated in any way. This can happen along-side activated and deactivated events |
| merchants.activated | Triggered when a merchant is activated for the first time |
| merchants.deactivated | Triggered when a deactivated |
Webhook Payload
Merchant Payload
{
"id":"evt_0b2f78cb-f9c2-472a-921c-85c2e8cdc53e",
"key":"merchants.updated",
"created_at":"2026-06-08T00:04:06Z",
"payload":{
"id":"mcht_a012624e-98ea-4cf4-827d-a4aa3f37665f",
"email":"email@test.com",
"flags":{
"hidden":false
},
"status":{
"active":true,
"expires_at":null,
"activated_at":"2024-03-21T15:48:25Z"
},
"chain_id":"chin_4b1fa6fd-f2c0-4716-83e4-f4b5985cdd58",
"location":{
"city":"San Juan",
"latitude":13.44507935544125,
"zip_code":"21921",
"longitude":-60.06715794692003,
"address_line_one":"Address",
"address_line_two":null,
"address_street_number":null
},
"created_at":"2024-03-21T15:48:25Z",
"legal_name":"Imports LLC",
"processors":[
"evertec"
],
"trade_name":"Merchant Imports",
"updated_at":"2024-03-21T15:48:25Z",
"debit_config":{
"debit_method":"accrual",
"debit_period_seconds":86400,
"minimum_processable_debit_accrual_cents":500,
"transaction_notification_alert_period_seconds":604800
},
"phone_number":"1234567890",
"tax_category":{
"id":"taxc_3345b574-a8d3-4656-a66b-43e98101352d",
"category":"Category 1",
"tax_rate":"0.07"
},
"territory_id":"terr_34d1c210-4af3-40c1-ab0a-967ef189c4d5",
"reward_config":{
"base_reward_percent":"0.05",
"returning_visit_multiplier":"1.0"
},
"contact_last_name":"Contact_Lastname",
"contact_first_name":"Contact_Firstname"
}
}
| Payload Value | Description |
|---|---|
| id string | UUID of the associated Merchant |
| email string | Merchant's email |
| flags dictionary | Additional details about the merchant's state |
| flags.hidden boolean | If the merchant is hidden in the program. If this is true, then the merchant is also deactivated. |
| status dictionary | Context on the current status of the merchant |
| status.active boolean | Whether the merchant is currently active |
| status.expires_at timestamp | Time that the merchant will expire and deactivate |
| status.activated_at timestamp | Time that the merchant was activated |
| chain_id string | UUID of the chain |
| location dictionary | Location data for the merchant |
| location.city string | Merchant's city |
| location.latitude string | Merchant's geo-graphical latitude |
| location.zip_code string | Merchant's zip code |
| location.longitude string | Merchant's geo-graphical longitude |
| location.address_line_one string | Merchant's address |
| location.address_line_two string | Merchant's address |
| location.address_street_number string | Merchant's address |
| created_at timestamp | Time the merchant was created |
| legal_name string | Merchant's legal name |
| processors array | Processors that the merchant utilizes |
| trade_name string | Merchant's trade name to be displayed |
| updated_at timestamp | The date the merchant was last modified by GoRewards |
| debit_config dictionary | Configuration of how the merchant receives debits |
| debit_config.debit_method string | How the system determines when to debit the merchant: accural, weekly, weekly_and_accural. If using weekly_and_accural, then both conditions must be satisfied |
| debit_config.debit_period_seconds number | How often to debit the merchant when using a weekly method, otherwise this will be 0 |
| debit_config.minimum_processable_debit_accrual_cents number | Threshold to debit the merchant when using an accural method, otherwise this will be 0 |
| debit_config.transaction_notification_alert_period_seconds number | Time without a transaction that admins will be alerted of a potential inactive merchant |
| phone_number string | Merchant's phone number |
| tax_category dictionary | Merchant's tax information |
| tax_category.id string | UUID of Tax Category |
| tax_category.category string | Name of Tax Category |
| tax_category.tax_rate string | Applicable tax rate for the category |
| territory_id string | UUID of territory |
| reward_config dictionary | Configuration of reward rates |
| reward_config.base_reward_percent string | Base percentage of rewards users earn at this merchant. Further increased by options such as co-brand offers and returning multipliers |
| reward_config.returning_visit_multiplier string | Multiplier for returning visits by the user in the current month |
| contact_last_name string | Name of contact on record |
| contact_first_name string | Name of contact on record |
Reward Events
The Reward webhook provides details about the processing of user rewards.
The rewards.settled event is unique as it signals when a user in your program should be credited rewards. Due to the importance of this webhook, it can be configured to be sent to a different endpoint.
Reward Event Keys
| Event Key | Description |
|---|---|
| rewards.created | Triggered when a reward is first created |
| rewards.settled | Triggered when a reward has been settled |
| rewards.failed | Triggered when a reward has failed to settle |
Webhook Payload
Reward Payload
{
"id":"evt_fc350e2c-a6dc-40d1-9a9b-00b61dd3d611",
"key":"rewards.settled",
"created_at":"2026-06-08T18:17:11Z",
"payload":{
"id":"pdrw_557bde5f-cc16-4d6f-b0d0-5e3b23db3dfa",
"card_id":"card_1493afc9-7262-4f26-a074-051ebf3c7e8e",
"user_id":"user_7d5c020d-9559-43f4-a0a1-4dd514516f0b",
"failed_at":null,
"created_at":"2026-06-07T20:00:42Z",
"settled_at":"2026-06-07T20:00:43Z",
"merchant_id":"mcht_dd60d3e8-92c2-4ddf-8309-7e1208f45065",
"territory_id":"terr_34d1c210-4af3-40c1-ab0a-967ef189c4d5",
"transaction_id":"trsn_6cfd4a60-5c09-44d7-affe-b7abaa3d06cb",
"reward_behavior":{
"is_double_reward":false,
"base_reward_percent":"0.05",
"effective_reward_percent":"0.06",
"returning_visit_multiplier":"2.0"
},
"reward_currency":{
"iso4217":"840",
"reward_cents":63,
"conversion_rate_from_usd":"1.0"
},
"awarded_credit_id":"sdrw_161fe9e4-f1c7-4190-a62b-b2be29c81f11"
}
}
| Payload Value | Description |
|---|---|
| id string | UUID of the associated Reward |
| card_id string | UUID of the user's card |
| user_id string | UUID of the user |
| failed_at timestamp | Time that the reward failed, if applicable |
| created_at timestamp | Time that the reward was created or began being processed |
| settled_at timestamp | Time that the reward was settled |
| merchant_id string | UUID of the merchant |
| territory_id string | UUID of the territory |
| transaction_id string | UUID of the transaction |
| reward_behavior dictionary | Details of how the reward was calculated |
| reward_behavior.is_double_reward string | Whether the reward was multiplied following the reward_behavior.returning_visit_multiplier |
| reward_behavior.base_reward_percent string | Base percentage used to calculate the reward, matches the merchant the transaction was made at |
| reward_behavior.effective_reward_percent string | Final reward percentage calculated |
| reward_behavior.returning_visit_multiplier string | Merchant's multiplier for subsequent transactions in the same month |
| reward_currency dictionary | Details of the currency that the reward was calculated in |
| reward_currency.iso4217 string | Currency code |
| reward_currency.reward_cents number | Credits earned by the user in the configured currency |
| reward_currency.conversion_rate_from_usd string | Conversion rate used at the time of calculation |
| awarded_credit_id string | UUID of the awarded credit |
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:
- A request ID that must be passed back to the GoRewards system when you enroll the card
- A Base64 encoded SHA-256 public key that can be used to encrypt a card PAN on your frontend prior to any network request.
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.