REWORTH rewards API
Documentation Powered by ReDoc

REWORTH rewards API (0.12.10)

Download OpenAPI specification:Download

John P. Falcón, CTO, co-founder REWORTH: integrate@reworth.co

REWORTH rewards REST API specification according to the standard OpenApi 3.0.0

The following document details the current-state of the endpoints for the API, as well as the operations available and parameters that can be sent to each of them. The document also provides additional sections with available dynamic flags and filtering parameters on some of the endpoints.

The authentication endpoint returns a jwt (access token) valid for 1 week. With this token you can perform further calls to the service as long as your user role is authorized to access that resource and/or own that same resource.

  • Financial institutions have broad access to our public resources and are subject to ownership rules across the system. For a financial institution to perform requests directly to the API, an account has to be approved first by one of REWORTH's integration engineers. Once activated, the sandbox key/secret credentials can be generated directly on https://fi-sandbox.reworth.app by going to Account settings > API keys.

  • Guests have limited to no access to the API, and can only perform read operations, such as the public offer directory or the initial authentication.

For any issues related with the integration of the rewards API please contact integrate@reworth.co

Authentication

httpBearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Health

General API status and service health as well as the version you are currently running

Ping check

Ping the API to check for connectivity issues. This endpoint doesn't perform any operations to the database, although it serves the purpose of checking API health status.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "These are not the droids you're looking for...",
  • "data": {
    }
}

Auth

Authentication with the API and token validation type of operations

Authenticate

Attempt to authenticate with the API. Use the credentials generated via your FI sandbox dashboard.

If the validation is successful, the response will contain an access token under data.jwt, to be used in further requests.

Request Body schema: application/json
key
required
string
secret
required
string

Responses

Request samples

Content type
application/json
{
  • "key": "4b3588a8648202a1f503e9...20ea2dd830c41a235efc10a",
  • "secret": "$2a$08$v685soRwvux2F...rbnGPWcUS0ZKT.isyOe"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "status": 200,
  • "message": "Welcome! You have now authenticated to the REWORTH API",
  • "data": {
    }
}

Validate token [server-side]

Check an access token for validity on the server side. Remember if you're trying to figure out if the token has expired you could optionally use a local JWT implementation to validate it. If your implementation performs the authentication on every launch of your client application, it's recommended to run this request first to avoid getting TokenNotValid Error if it's already expired.

Authorizations:
httpBearer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Your JWT is valid until February 17, 2022 5:37 PM",
  • "data": {
    }
}

Refresh access token

Ask for a new token regardless of the expiration of the current one. A new token will only be provided if the expiration date is less or equal than two hours for usage reasons. If you’re trying to figure out if your token is still valid, please use the previous endpoint .../auth/validate

Authorizations:
httpBearer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Your JWT is valid until February 17, 2022 5:37 PM",
  • "data": {
    }
}

Directory

Available features on the public offer rewards namespace

Rewards directory

Fetch our data driven rewards directory to display promotions on your host application. Each object in the array contains values ready to display (formatted values), you can identify these by the prefix dv_ for example dv_category To perform search by the name of the business use the attribute 'name' or apply up to three of our available filters: geolocation, category, popularity, rating, price_range to get more accurate recommendations for your customer. After the filters are applied, the resulting collection can be sorted and paginated for accessibility. Since 0.12.9.* the directory comes powered with a recommender system based on a unique used id shared on your request and the offers displayed for that user will improve as they keep earning cashback

query Parameters
uuid
required
string
Example: uuid=C08409803

Add uuid (should match the one sent in transaction payload) to fetch personalized recommendations from our profiling algorithm. The more transactional data we gather from each anonymized customer, we'll improve targeted recommendations for them.

filters
string
Enum: "geo" "category" "popularity" "rating"
Example: filters=geo

Apply filters to the request to get more precise results. This parameter receives a string or a comma separated value if multiple filters are applied. Filter stacking is limited to 3 and they are applied in the order of submittion. Send separated by comma like: geo,category

price
integer
Enum: 1 2 3 4 5
Example: price=1

REQUIRED if price is included on the filters stack

geo_payload
string
Example: geo_payload=19.360274,-99.166253

REQUIRED if geo is included on the filters stack. The right format is lat,lng otherwise the service will return an error.

category_payload
string
Enum: "restaurants-bars" "food-beverages" "electronics-software" "telecom-internet" "entertainment-events-tickets" "books-games-movies-music" "clothing-store" "fitness-sports" "health-beauty" "education" "culture" "tourism-hotels-accommodation" "pet-related" "stationery-office" "home" "services" "other"
Example: category_payload=education

REQUIRED if category is included on the filters stack

popularity_payload
string
Enum: "ASC" "DESC"
Example: popularity_payload=ASC

REQUIRED if popularity is included on the filters stack

rating_payload
string
Enum: "ASC" "DESC"
Example: rating_payload=ASC

REQUIRED if rating is included on the filters stack

sort
string
Enum: "ASC" "DESC"
Example: sort=ASC

Sort the resulting collection in ascending or descending order

epp
integer
Example: epp=10

Number of elements per page to fetch per request. See other pagination parameters 'p'. *Default value for 'epp' is 10 items. See pagination flags (pages, page, hasNextPage, hasPrevPage) included as part of the response to facilitate integration with most pagination UI solutions.

p
integer
Example: p=1

Number of elements per page to fetch per request. See other pagination parameters 'epp'. *Default value for 'p' is 1.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": null,
  • "data": [
    ],
  • "pages": 1,
  • "page": 1,
  • "hasPrevPage": false,
  • "hasNextPage": true
}

Transactions

Contains operations available for the transactioning micro-service

Process cashback transaction(s)

Send a new batch or single transaction to the rewards system for processing and find out if there are applicable rewards. This operation posts the transactions to the REWORTH system but doesn't withraw the amount from the merchant's pocket, please see Transaction validation process. Periodicity and validation times for conciliation must be set directly with the REWORTH integrations team integrate@reworth.co. We recommend to send a max of 1000 (one thousand) elements per request to get a quick response, although 5 times that will still give you a response time under 3s

Request Body schema: application/json
requestId
required
string
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "requestId": 1644474347,
  • "transactions": [
    ]
}

Response samples

Content type
application/json
Example
processTransactionResponse
processTransactionResponse
noNewEntitiesResponse
{
  • "success": true,
  • "processedTransactions": 1,
  • "requestId": 1644474347,
  • "data": [
    ]
}

Fetch batch of transactions to review it's status with REWORTH at any time. It requres the requestId you set when posting the transaction in the previous step

Fetch transactions by the requestId you set when posting the transactions in the previous step

path Parameters
requestId
required
string
Example: 1644474347

REWORTH identifier of the transaction provided in the response of the POST endpoint

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "This requestId has already been processed",
  • "data": [
    ]
}

Webhooks

Contains operations available for the configuration of webhooks to receive statuses

My FI

Contains operations available for the authenticated institution

Fetch profile information

Fetch information about the authenticated company, useful to populate a profile page or to fetch and keep a local copy of the user non-sensitive data. This endpoint includes a nested contact object by default

Authorizations:
httpBearer
query Parameters
populate
boolean
Example: populate=true

Submit value as false to avoid populating the contact nested object

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "lastLogin": 0,
  • "data": {
    }
}

Webhook

Set up callback url for dispersion response

You will need to provide REWORTH with a redemptions callback url. refreshRate can have the following values: [0: weekly conciliation, 1: daily conciliation]

Request Body schema: application/json
callback
required
string
refreshRate
integer <int32>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "callbackUrl stored successfully",
  • "data": null
}

Set up callback url for commissions report

You will need to provide REWORTH with a commissions callback url.

Request Body schema: application/json
callback
required
string
refreshRate
integer <int32>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "callbackUrl stored successfully",
  • "data": null
}