Fees and Rewards

Overview

Synctera supports 2 paths for fee/reward orchestration: 1. Orchestration by FinTech (you):

You use the Synctera Fee API for the setup and orchestration.
You first create a Fee/Reward Template, which is used to specify the type of fee or reward, and to set default values, e.g. an amount or description. Designed for flexibility, you can choose which internal account is used by each template, allowing granular management of your fees and reward programs.
You then create the Fee/Reward, i.e. apply to customer accounts, using the Fee/Reward Template.
This setup is described in the guide below.

2. Orchestration by the Synctera system:

You use the Synctera Console to set up Fee/Reward Products and link to account templates. The Synctera system then automatically applies the fees and rewards to customer accounts based on the setup.
This setup is described in this article in our Learning Center.
NOTE: You can also use the Synctera Fee Product API for the setup, although the Console is recommended as this is typically a one-time or a low-frequency task.

In this guide, you will walk through the steps to set up a simple membership fee and reward program following the first path (orchestration by FinTech). The scenario will be offering two tiers of membership to customers. The first tier charges a $5 monthly fee. The second tier charges a $10 monthly fee but gives the customer cash back on certain types of purchases.

Prerequisites

You have created customers, either personal or business
You have created accounts for these customers.
Internal accounts have been created based on how you want to group your fee and reward transactions. Please ask Synctera Operations to create these.

Important Note!

All fees charged to customers must be clearly disclosed in the initial customer account agreement in a manner consistent with federal law. Prior to changing any fee structure, please consult with Synctera’s compliance team as well as your Sponsor Bank.

Creating Fee and Reward Templates

Create a Fee Template

First, create a fee template for the $5 monthly fee. To do this, use the Create Fee Template endpoint.

curl \
  -X POST \
  $baseurl/v1/fee_templates/ \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "amount":500,
    "currency":"USD",
    "description":"Tier 1 Premium Monthly Fee",
    "internal_account_id": "<INTERNAL_ACCOUNT_ID>",
    "is_enabled":true,
    "subtype":"MAINTENANCE"
  }'

The response will look like this:

{
  "id": "5f9b3b5a-5b0a-4b0a-8b0a-5b0a5b0a5b0a",
  "creation_time": "2021-10-01T00:00:00.000000Z",
  "last_updated_time": "2021-10-01T00:00:00.000000Z",
  "amount": 500,
  "currency": "USD",
  "description": "Tier 1 Premium Fee",
  "internal_account_id": "<INTERNAL_ACCOUNT_ID>",
  "is_enabled": true,
  "subtype": "MAINTENANCE"
}

Note the id field, you will need this later when creating the fees. Also note that the subtype is used as the transaction description on Account Statement / Transaction List. A Tier 2 template can be created using a similar request, but setting the amount to $10, and a different description:

curl \
  -X POST \
  $baseurl/v1/fee_templates/ \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "amount":1000,
    "currency":"USD",
    "description":"Tier 2 Monthly Fee",
    "internal_account_id": "<INTERNAL_ACCOUNT_ID>",
    "is_enabled":true,
    "subtype":"MAINTENANCE"
  }'

Create a Reward Template

Next, create a reward template for cash back on purchases. To do this, use the Create Reward Template endpoint.

curl \
  -X POST \
  $baseurl/v1/reward_templates/ \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "currency":"USD",
    "description":"Tier 2 Cash Back Reward",
    "internal_account_id": "<INTERNAL_ACCOUNT_ID>",
    "is_enabled":true,
    "subtype":"CASHBACK"
  }'

Notice how the reward template does not contain a default amount. Your system will need to calculate the reward amount based on the amount of customer purchases follow the example below for more details.

Setting Up Webhooks

You will need to register a webhook to listen for specific transaction events. These events can notify your system when a transaction occurs, such as TRANSACTION.POSTED.CREATED (such as a successful card purchase) or EXTERNAL_CARD_TRANSFER.CREATED (money transferred from an external source).
For details on how to register webhooks, refer to the webhooks documentation.

Understanding the Webhook Payload

When a TRANSACTION.POSTED.CREATED event occurs, your system will receive a notification with details about the transaction. Here’s an example of a payload for a card purchase webhook event:

{
  "id": 13879,
  "uuid": "8e04f62d-4eea-4217-bf2c-b77f569f5515",
"type": "card",
"subtype": "pos_purchase",  // Point-of-sale purchase
"status": "POSTED",
"reference_id": "63352",
"data": {
  "user_data": {
    "account_id": "189b0d33-3359-485c-8a77-24fa726ca817",  // Unique ID for the user's account
    "amount": 1868,        // Transaction amount in cents (e.g., 1868 cents = $18.68)
    "card_id": "a3041aee-4b97-4dd8-8a8d-c55571fe9953",
    "card_transaction_subtype": "pindebit",
    "currency_code": "USD"
  }
},
"posted_date": "2024-03-08T00:00:00Z",  // Date the transaction was settled
"effective_date": "2024-03-07T00:00:00Z", // Date the transaction took place
"created": "2024-03-07T20:40:51.259048Z", // Date and time the webhook notification was created
"updated": "2024-03-07T20:40:51.040607Z", // Date and time the webhook notification was last updated
  "transaction_time": "2024-03-07T20:40:10.374925Z" // Date and time the transaction occurred
}

Calculating Rewards/Fees

Based on your program’s rules, calculate the amount of reward or fee to be applied. For example, if your program offers a 5% reward on transactions, you would calculate the reward amount as follows: Reward amount = Transaction amount (in cents) x Reward percentage In the example above, the transaction amount is 1868 cents and the reward percentage is 5%. Therefore, the reward amount would be: Reward amount = 1868 cents x 0.05 = 93.4 cents (rounded down to 93 cents)

Applying Rewards/Fees

Once you have the account ID (from the payload) and the calculated reward/fee amount, follow the instructions listed below to apply the reward to a designated reward template.

Apply Fees and Rewards to Accounts

Now that you have created fee and reward templates, you can apply them to customer accounts. To do this, use the Create Fee and Create Reward endpoints. To create the fees, use requests like this:

curl \
  -X POST \
  $baseurl/v1/fees/ \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "account_id": "{CUSTOMER_ACCOUNT_ID}",
    "template_id": "{FEE_TEMPLATE_ID}"
  }'

No amount, currency, or description is needed because the values are set in the template. Applying the reward is very similar but the calculated amount is be required:

curl \
  -X POST \
  $baseurl/v1/rewards/ \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "account_id": "{CUSTOMER_ACCOUNT_ID}",
    "template_id": "{REWARD_TEMPLATE_ID}",
    "amount": "{CALCULATED_AMOUNT}"
  }'

Viewing Applied Fees and Rewards

To query what fees and rewards have been applied, use the List Fees and List Rewards endpoints. Fees and rewards also can also be seen in the transactions list: use the List Posted Transactions endpoint with a transaction type of fee or reward.

Overview

Products

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Overview

Prerequisites

Important Note!

Creating Fee and Reward Templates

Create a Fee Template

Create a Reward Template

Apply Fees and Rewards to Accounts

Viewing Applied Fees and Rewards

​Overview

​Prerequisites

​Important Note!

​Creating Fee and Reward Templates

​Create a Fee Template

​Create a Reward Template

​Apply Fees and Rewards to Accounts

​Viewing Applied Fees and Rewards

Overview

Prerequisites

Important Note!

Creating Fee and Reward Templates

Create a Fee Template

Create a Reward Template

Apply Fees and Rewards to Accounts

Viewing Applied Fees and Rewards