SaFi Bank Space : Fees

Fees topic can be split into two distinct parts:

First one is the fee, what is optionally charged to customer. This feature depends on the product requested, and Subscription plan of the specific customer. In the following text, we would describe it as a “Customer fee”.
Second fee is the amount of money, which is passed to the specific operation (transaction) as the integration partner - vendor eg. Paynamics can charge the fee from the payment itself. In the following text, this will be described as a “Vendor fee”.

Customer fee

Customer fees are heavily related to the subscription plan of the customer. Therefore these fees are not managed within transactions scope, but rather are offered as service by the Product team. Dedicated service for fees calculation is the SubscriptionOperationUsage. This service offers 4 operation of which 3 are going to be used by transactions:

Query - this operation offers calculation about planned transfer. Functionality is interesting for UI to show to the customer fee for planned operation. The request looks like:
```
{
  "request": {
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "TRANSFER",
    "timesUsed": 0
  }
}
```
- type - describes one of {"TRANSFER","TOP_UP","ATM_WITHDRAWAL","CASH_IN","REMITTANCE_SERVICE","DEBIT_CARD"}
- timesUsed - contains information about volume. Eg. sending 150000 using Instapay service would mean to use 3 transactions as Instapay limits transaction to 50000 PHP.
- The response is really self explanatory.
Commit - this operation is by request identical to Query, however causes “consumption” of the potentially free transaction. Meaning, if there were 3 free transaction before, and we consume 1, there will be remaining 2. This is not the case for the Query. The response contains operation “id” which needs to be used in the case, when the transaction was not realised. This “id” is then used in the next operation “revert”.
```
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "remainingFreeUses": 0,
  "fee": 0,
  "percentageFee": 0,
  "currency": "string"
}
```
- id - is important for reverting the fee.
- remainingFreeUses - how many free operations is available
- fee - sum, which needs to be subtracted from the customer account
- percentageFee - if fee is not constant, but depends from the amount, percentageFee is used as a value (in percents) eg. 2, meaning 2% of operation value.
- currency - “PHP”
Revert - “rollbacks” the commit by reverting counter of used operations. It expects only the operation id.
```
{
  "subscriptionOperationUsageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

Mechanism

These fees should be added into postings by Transaction Processor Manager (TPM). Following is the logical schema of money flow within accounts. All the flows should executed within single batch. This schema is simplified and does not contain “Vendor fee”.

After the commit, TPM stores id and continues in operation. In case of the failure (after receiving the fail response from TM Vault), TPM should call the “Revert” operation.

Details about current Safi expectation about customer fees are here.

Vendor fee

Vendor fee is completely different kind of animal, and is hidden from the eyes of the customer. Main key is, that fee is strongly related to vendor (Paynamics), service (cash in) or even merchant (7-Eleven). The thing is that when we send thru vendor eg. 1000 PHP, he can charge the fee for the operation (instead of contract with SaFi) directly. Therefore, if the fee is eg. 20 PHP, we would need to send 1020 PHP.

Calculation

Value can be:

fixed - fee is always the same. On top of it, there might be ranges eg:
- 0-1000 - 10 PHP
- 1001-10000 - 20 PHP
- 10001-limit - 30 PHP
percentage - fee is based on the amount. In case of percentage there might be:
- top limit - maximum 50 PHP
- minimum fee - 5 PHP

Al values are just examples, and can vary for all alternatives.

Fee Manager

Fee manager is proposed module, which will based on the type of the transaction return the fee charged by vendor. In case, there is contract between SaFi and vendor, which is outside of the transactions, fee is obviously 0.

API should contain:

all information about the Vendor planned to be used and the service details.
all information about the operation

As splitting the transaction into smaller ones is the logic on side of TPM, for simplicity, we can implement this calculation for single transaction (and in case of split into 3 send 3 requests).

Transaction Processor Manager operation

This is full example of the flows between accounts. Lets expect, that customer wants to send 1000 PHP as interbank transaction. The operation will flow thru Paynamics.

Product manager calculates, that customer does not have free transactions, and that fee would be 20 PHP
Fee manager calculates, that Paynamics will charge us 10 PHP, and will subtract this amount from the amount.
We charge customer 1020 PHP as that is the amount 1000 + 20 as SaFi fee.
We transfer SaFi fee to SaFi internal account for incoming fees.
We charge the SaFi outgoing fees internal account and add this sum to original amount. 1000 + 10 as Paynamics fee.
Finally we transfer 1010 PHP to Paynamics.