Core resources

Transactions

6min

In the  system, eligible transactions that meet the offer's terms are converted to rewards. The transaction object represents a single transaction linked to a single offer in the Publisher's system. The object contains details such as amount, date, merchant, and more, which allows the  system to calculate rewards for each transaction based on the rules configured for each offer﻿ linked to brands﻿ in the publisher's system.
The table below outlines the available API call and action for the transaction object.
Action
API call
Description
﻿Get transactions for a user﻿ 
GET /transactions
Retrieves rewards related transactions within the Publisher's platform for all users or for a specific user. 
﻿GET /transactions
Retrieves all rewards related transactions within the Publisher's platform. To retrieve transactions for a specific user, enter a value for the publisher_user_id. See Get transactions﻿ to test the API.
Query parameters
﻿
Name
Data type
Description
publisher_user_id
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
search_text
string
String search field to filter transactions. Currently supports Advertiser name and transaction uuid.
start_date
string

2024-06-12T20:43:00
Transaction start date and time in ISO8601 format: yyyy-MM-dd'T'HH:mm:ss. Search results are inclusive of this date and time.
All time values are in the Coordinated Universal Time (UTC) time zone.
end_date
string

2024-06-12T20:43:00
Transaction end date and time in ISO8601 format: yyyy-MM-dd'T'HH:mm:ss. Search results are inclusive of this date and time.
All time values are in the Coordinated Universal Time (UTC) time zone.
Pageable
﻿
Responses
﻿
HTTP status 200
Returns an array of Transaction objects with a 200 response code, if successful. For more information, see Status and response codes﻿. 
﻿
PagedResponse
See Pageable response﻿ for more information on the returned paginated response.
﻿
data
Name
Data type
Description
publisher_user_id
string
Publisher's unique identifier for the user. This ID is sent by the Publisher to  to identify a user in the publisher’s system.
transaction_date_time
string <date-time>
Date and time of when the transaction took place. The format of this string is: yyyy-MM-dd'T'HH:mm:ss
This is an important attribute that determines if the offer was or was not valid for this transaction.
All time values are in the Coordinated Universal Time (UTC) time zone.
reward_type
string
This is the type of reward made available by the brand. Possible values with their definitions:
DISCOUNT_DOLLAR- Dollar amount that is deducted from the subtotal of a transaction
DISCOUNT_PERCENTAGE- Percentage amount that is deducted from the subtotal of a transaction
CASHBACK_DOLLAR- Dollar amount earned as cashback rewards
CASHBACK_PERCENTAGE- Percentage of a subtotal that is earned as cashback rewards
offer_type
array of strings
Type of the offer. Possible values with their definitions:
CARD_LINKED - Offers that provide rewards for card linked transactions
AFFILIATE - Offers where the user gets a reward for making a purchase through an affiliate link
GIFT_CARD - Offers that provide rewards for when a user purchases gift cards
VOUCHER_CODE - Offers that provide rewards in the form of voucher codes 
user_cashback
number
Cashback amount earned by the user for this transaction. Precision is up to two decimal places.
﻿IMPORTANT: If the Publisher distributes rewards or cashback to users with funds from  (i.e. cashback earned from user's transactions are paid directly to the Publisher), then the Publisher's commission is determined by subtracting the user_cashback amount from the publisher_share amount.
transaction_amount
number <double>
A positive number representing the amount that is intended to be transacted. The amount value supports up to two digits in precision, for example, $24.99. The minimum amount supported is 0 and there is no limit on the maximum amount, however, each offer﻿ has limits on maximum amounts eligible for rewards. 
For example, 5% cashback up to $1000. Only United States Dollar (USD) and British Pound Sterling (GBP) supported currently depending on the region covered by the Publisher.
currency_code
string
Type of currency, for example: USD which indicates United States Dollar
status
string
Status of a transaction which determines reward availability to the user. 
Possible values:
PENDING - A transaction in which rewards are not available yet. Pending transactions can be cancelled and refunded.  
EARNED - A transaction that has passed the pending state. This status indicates that the rewards have been released to the user for redemption. Earned transactions cannot be canceled or refunded.
CANCELLED - A transaction that is ineligible to have rewards redeemed by the user.
offer_uid
string
Unique identifier for the offer in the UUID4 format. Can be used to retrieve additional details for the offer. 
offer_name
string
Name of the offer﻿ used to generate the reward linked to the transaction.
advetiser_name
﻿
Name of the advertiser that is promoting this offer. The advertiser name or the brand name is available to link the transaction to a valid offer.
transaction_uid
string
Unique identifier for the transaction.
publisher_share
number
The commission amount that a Publisher earns from a transaction. 

IMPORTANT: The method of calculating this commission depends on the Publisher’s chosen approach to distributing rewards or cashback to their users. Refer to the options below to accurately interpret the value in the publisher_share field:
Option 1: If the Publisher opts for Finfare to distribute cashback directly to the users, the publisher_share amount reflects the Publisher's commission.
Option 2: If the Publisher distributes rewards or cashback to users with funds from Finfare (i.e. cashback earned from user's transactions are paid directly to the Publisher), then the Publisher's commission is determined by subtracting the user_cashback amount from the publisher_share  amount.
brand_uid
string
Unique identifier for a brand. This can then be used to retrieve details about a specific brand.
card
string
Last 4 digits of the card linked to the transaction. The rewards calculated for this transaction are linked to this card.
location_address
string
Address of the transaction location, if available. This will be used to determine location-based offers in the future.
﻿

Action	API call	Description
Get transactions for a user	GET /transactions	Retrieves rewards related transactions within the Publisher's platform for all users or for a specific user.

Name	Data type	Description
publisher_user_id	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
search_text	string	String search field to filter transactions. Currently supports Advertiser name and transaction uuid.
start_date	string 2024-06-12T20:43:00	Transaction start date and time in ISO8601 format: yyyy-MM-dd'T'HH:mm:ss. Search results are inclusive of this date and time. All time values are in the Coordinated Universal Time (UTC) time zone.
end_date	string 2024-06-12T20:43:00	Transaction end date and time in ISO8601 format: yyyy-MM-dd'T'HH:mm:ss. Search results are inclusive of this date and time. All time values are in the Coordinated Universal Time (UTC) time zone.

Name	Data type	Description
publisher_user_id	string	Publisher's unique identifier for the user. This ID is sent by the Publisher to to identify a user in the publisher’s system.
transaction_date_time	string <date-time>	Date and time of when the transaction took place. The format of this string is: yyyy-MM-dd'T'HH:mm:ss This is an important attribute that determines if the offer was or was not valid for this transaction. All time values are in the Coordinated Universal Time (UTC) time zone.
reward_type	string	This is the type of reward made available by the brand. Possible values with their definitions: DISCOUNT_DOLLAR- Dollar amount that is deducted from the subtotal of a transaction DISCOUNT_PERCENTAGE- Percentage amount that is deducted from the subtotal of a transaction CASHBACK_DOLLAR- Dollar amount earned as cashback rewards CASHBACK_PERCENTAGE- Percentage of a subtotal that is earned as cashback rewards
offer_type	array of strings	Type of the offer. Possible values with their definitions: CARD_LINKED - Offers that provide rewards for card linked transactions AFFILIATE - Offers where the user gets a reward for making a purchase through an affiliate link GIFT_CARD - Offers that provide rewards for when a user purchases gift cards VOUCHER_CODE - Offers that provide rewards in the form of voucher codes
user_cashback	number	Cashback amount earned by the user for this transaction. Precision is up to two decimal places. IMPORTANT: If the Publisher distributes rewards or cashback to users with funds from (i.e. cashback earned from user's transactions are paid directly to the Publisher), then the Publisher's commission is determined by subtracting the user_cashback amount from the publisher_share amount.
transaction_amount	number <double>	A positive number representing the amount that is intended to be transacted. The amount value supports up to two digits in precision, for example, $24.99. The minimum amount supported is 0 and there is no limit on the maximum amount, however, each offer has limits on maximum amounts eligible for rewards. For example, 5% cashback up to $1000. Only United States Dollar (USD) and British Pound Sterling (GBP) supported currently depending on the region covered by the Publisher.
currency_code	string	Type of currency, for example: USD which indicates United States Dollar
status	string	Status of a transaction which determines reward availability to the user. Possible values: PENDING - A transaction in which rewards are not available yet. Pending transactions can be cancelled and refunded. EARNED - A transaction that has passed the pending state. This status indicates that the rewards have been released to the user for redemption. Earned transactions cannot be canceled or refunded. CANCELLED - A transaction that is ineligible to have rewards redeemed by the user.
offer_uid	string	Unique identifier for the offer in the UUID4 format. Can be used to retrieve additional details for the offer.
offer_name	string	Name of the offer used to generate the reward linked to the transaction.
advetiser_name		Name of the advertiser that is promoting this offer. The advertiser name or the brand name is available to link the transaction to a valid offer.
transaction_uid	string	Unique identifier for the transaction.
publisher_share	number	The commission amount that a Publisher earns from a transaction. IMPORTANT: The method of calculating this commission depends on the Publisher’s chosen approach to distributing rewards or cashback to their users. Refer to the options below to accurately interpret the value in the publisher_share field: Option 1: If the Publisher opts for Finfare to distribute cashback directly to the users, the publisher_share amount reflects the Publisher's commission. Option 2: If the Publisher distributes rewards or cashback to users with funds from Finfare (i.e. cashback earned from user's transactions are paid directly to the Publisher), then the Publisher's commission is determined by subtracting the user_cashback amount from the publisher_share amount.
brand_uid	string	Unique identifier for a brand. This can then be used to retrieve details about a specific brand.
card	string	Last 4 digits of the card linked to the transaction. The rewards calculated for this transaction are linked to this card.
location_address	string	Address of the transaction location, if available. This will be used to determine location-based offers in the future.

Users

Offers and Brands

Transactions

﻿GET /transactions

Query parameters

Responses

GET /transactions