Fees and Rewards (Beta)

Overview

Fees and Rewards are a mechanism for debiting and crediting customer accounts based on your service charges and rewards programs. Templates are 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 rewards programs.

In this guide, you will walk through the steps to set up a simple membership fee and reward program. 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.

Comparison with Transaction Fees

As this feature is for Fintech defined fees and rewards, it is distinct from fees that are charged as part of a transaction. For example, credit card interchange and currency conversion fees are part of the card transaction data, not a separate fee transaction.

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. During the beta phase, please ask Synctera Operations to create these.

📘

Important Note!

All fees charged 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.

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.

1. 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.

2. 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:

JSON
{
  "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
}

3. 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)

4. 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": "{FEE_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.