Bonus/Discount on Remittance

Read on building bonus and discount features for your remittance service

Overview

During transaction creation, you can apply a bonus or discount to a particular transaction. Our clients have used this feature to improve their customer acquisition and retention strategies. Based on how you build your application, you can support multiple different use cases for bonus and discount offers. In general, bonus features can be implemented by providing a value for the “bonus_amount” field in the Create Transaction API.

On the Machnet system, the criteria required for transaction creation remains the same for transactions with bonus similar transactions without bonus. However, Clients can build different criteria on their system to provide bonuses based on their use case. The most common implementations are listed below with details on how to build them.

Implementation 1: Bonus provided to the Receive User

This implementation allows a transaction to be created with a bonus amount where the bonus amount is provided to the receive user. You can choose to build logics on when to provide this bonus. It could be a first time user or a loyal user who has created 10 transactions already. When your bonus criteria is met, just be sure to include the bonus amount in the “from_amount” field and provide the bonus amount in the “bonus_amount” field as well in the Create Transaction API. Detailed examples are below.

Example 1

Bonus amount in sending currency

Amount entered by sender: USD 100

Bonus provided by the client USD 5

Field	Amount	Description
from_amount	USD 105	Amount entered by sender ($100) + Bonus amount ($5)
fee_amount	USD 2	Fee to be added, if applicable
bonus_amount	USD 5	Bonus provided to the receiver
Total amount deducted from sender’s account	USD 102	from_amount + fee_amount - bonus_amount
exchange_rate	14	Exchange rate (USD 1=GHS 14)
Total amount received by the receiver	GHS 1470	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":105,
"exchange_rate": 14,
"to_amount":1470,
"fee_amount": 2,
"bonus_amount": 5,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}'

Example 2

Bonus amount in receiving currency

Amount entered by sender: USD 100

Discount provided by the client: GHS 140

Field	Amount	Description
from_amount	USD 110	Amount entered by sender (100) + Bonus amount (10)
fee_amount	USD 2	Fee to be added, if applicable
bonus_amount	USD 10	Discount to be provided to the sender: Discount provided by Client (GHS 140)/Exchange rate (14)
Total amount deducted from sender’s account*	USD 102	from_amount + fee_amount - bonus_amount
exchange_rate	14	Exchange rate (USD 1=GHS 14)
Total amount received by the receiver	GHS 1540	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":110,
"exchange_rate": 14,
"to_amount":1540,
"fee_amount": 2,
"bonus_amount": 10,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}' 

Implementation 2: Discount provided to the Send user

This implementation allows a transaction to be created where a discount equal to the bonus amount is provided to the send user. You can choose to build logics on when to provide this discount to your user. It could be a first time user or a loyal user who has created 10 transactions already. When a criteria is met, just be sure to send us the amount you would like to discount in the “bonus_amount” field in the Create Transaction API.

Example 1

Discount provided to the send user

Amount entered by sender: USD 100

Discount provided by the client: USD 5

Field	Amount	Description
from_amount	USD 100	Amount entered by sender
fee_amount	USD 2	Fee to be added, if applicable
bonus_amount	USD 5	Discount to be provided to the sender
Total amount deducted from sender’s account*	USD 97	from_amount + fee_amount - bonus_amount
exchange_rate	14	Exchange rate (USD 1=GHS 14)
Total amount received by the receiver	GHS 1400	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":100,
"exchange_rate": 14,
"to_amount":1400,
"fee_amount": 2,
"bonus_amount": 5,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}'

Implementation 3: Bonus FX rate

You can provide a bonus FX rate to your users to remain competitive in the market. When you create a transaction, you will have to provide us the FX rate applicable to the specific transaction which should include the bonus FX.

Example 1

Provide higher FX to the user

Amount entered by sender: USD USD 100

Exchange rate: USD 1 = GHS 14

Bonus FX provided by the client for the user: USD 1=GHS 20

Field	Amount	Description
from_amount	USD 100	Amount entered by sender
fee_amount	USD 2	Fee to be added, if applicable
bonus_amount	-	Bonus provided to the receiver
Total amount deducted from sender’s account*	USD 102	from_amount + fee_amount - bonus_amount)
exchange_rate	20	Exchange rate including bonus FX (USD 1=GHS 20)
Total amount received by the receiver	GHS 2000	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":100,
"exchange_rate": 20,
"to_amount":2000,
"fee_amount": 2,
"bonus_amount": 0,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}'

Implementation 4: Waive fees of a transaction

As a marketing offer, you can also waive fees fully or partially for a user’s transaction. In order to do so, you will have to provide "bonus_amount" equal to the total fees or equal to the partial discount you are providing on the fees.

Example 1

Waive partial fees for a transaction

Amount entered by sender: USD 100

Fees: USD 5

Discount on fees provided by the Client to the user: USD 2

Field	Amount ($)	Description
from_amount	USD 100	Amount entered by sender
fee_amount	USD 3	Fee to be added after discount on fees (USD 5-USD 2)
bonus_amount	0	Bonus provided to the receiver
Total amount deducted from sender’s account*	USD 103	from_amount + fee_amount - bonus_amount
exchange_rate	14	Exchange rate including bonus FX (USD 1=GHS 14)
Total amount received by the receiver	GHS 1400	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":100,
"exchange_rate": 14,
"to_amount":1400,
"fee_amount": 3,
"bonus_amount": 0,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}'

Example 2

Waive full fees for a transaction

Amount entered by sender: USD 100

Fees: USD 5

Discount on fees provided by the Client to the user: USD 5

Field	Amount	Description
from_amount	USD 100	Amount entered by sender
fee_amount	USD 0	Fee to be added after discount on fees (USD 5-USD 5)
bonus_amount	0	Bonus provided to the receiver
Total amount deducted from sender’s account*	USD 100	from_amount + fee_amount - bonus_amount
exchange_rate	14	Exchange rate including bonus FX (USD 1=GHS 14)
Total amount received by the receiver	GHS 1400	from_amount*exchange_rate

Sample Request

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
"from_amount":100,
"exchange_rate": 14,
"to_amount":1400,
"fee_amount": 0,
"bonus_amount": 0,
"note": "Sample Note",
"to_currency":"GHS",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
"id": UUID,
"fund_id" : UUID,
"payout_method":"BANK_DEPOSIT",
"calculation_mode":"SENDER_AMOUNT"
}
}'