Charge Customer Fees

As an Embedded Partner (EP), you can add a markup fee to your customers' transactions, enabling you to collect additional revenue from your Customers.

These Embedded Partner Customer fees (hereinafter, customer fees) are optional charges. They are separate from the transaction amount and transaction fees and are collected from the Embedded Partner Customer (EPC) wallet.

Implement customer fees

To add a customer fee to a transaction, include the customerFee object in your API request:

{
    "type": "OUT",
     "fees": {
        "customerFee": {
            "currency": "USD",
            "amount": 1
        }
    }
}

The example use case for charging the customer fees may look as follows:

Send the GET /api/wallet request to acquire the list of your existing wallets with details.

In the response, find a wallet to which you plan to deposit fees and copy its lsid value.

[
    {
        "id": 3683091,
        "description": "USDC Wallet",
        "currency": {
            "id": 1773,
            "code": "USDC",
            "fiat": true,
            "icon": null,
            "name": "Euro",
            "withdrawalParameters": [],
            "options": {},
            "withdrawalFee": 0.4,
            "depositFee": 0,
            "supportsDeposits": true,
            "supportsWithdrawals": true,
            "quantityPrecision": 2,
            "pricePrecision": 5,
            "protocols": []
        },
        "lsid": "a:25041552279666:vpH2wtz:1",
        "status": "ACTIVE"
    }
]

The selected wallet's currency should match the currency of the fees you are charging.

You may use both fiat and crypto wallets, configuring an existing wallet or creating a new one for fees.

Designate the selected wallet as the fee destination by sending the PUT /platform/v1/fees/customer-fee-wallets request. Include the following payload:
```
{
    "destinationWalletId": "a:25041552279666:vpH2wtz:1",
    "currencyCode": "USDC"
}
```
Here, "a:25041552279666:vpH2wtz:1" is lsid from step 1.

Check that your selected wallet can receive customer fees by sending the GET /platform/v1/fees/customer-fee-wallets request.

In the response, you receive the list of wallets that will be used for accepting customer fees. The wallet with the lsid specified earlier must be listed here.

{
    "content": [
        {
            "destinationWalletId": "a:25041552279666:vpH2wtz:1",
            "currencyCode": "USDC"
        },
        {
            "destinationWalletId": "a:38472618394521:kLm9xRs:1",
            "currencyCode": "USDC"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": [],
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "first": true,
    "last": true,
    "size": 20,
    "number": 0,
    "sort": [],
    "numberOfElements": 2,
    "empty": false
}

Now, your wallet is configured for receiving customer fees.

To apply the fee, when creating payment requests, include the customer fee information in the fees object:

{
    "merchantId": "edce0951-5f7d-49ac-942f-bd4d86aeda56",
    "amount": 100,
    "currency": "USDC",
    "reference": "REF182597",
    "type": "OUT",
    "fees": {
        "customerFee": {
            "currency": "USDC",
            "amount": 1
        }
    }
}

{
	"walletId": "a:24071743000626:go5SB1l:1",
    "amount": {
        "value": "100.00",
        "currency": "USD"
    },
		"customerFee": {
        "value": "20.00",
        "currency": "USD"
    },
    "paymentReference": "Ref112455",
    "instruction": {
      "type": "FIAT",
      "paymentMethod": "ACH",
      "beneficiary": {
            "details": {
                "beneficiaryType": "SELF_OWNED",
                "transferDestination": "LOCAL",
                "currency": "USD",
                "businessDetails": {
                    "businessName": "Company ABC"
                },
                "address": {
                    "addressLine1": "Some address Line 1",
                    "addressLine2": "Some address Line 2",
                    "city": "Some city",
                    "region": "Some region",
                    "postCode": "ABCDEF",
                    "country": "US"
                },
                "bankDetails": {
                    "accountNumber": "2152209165",
                    "accountType": "CHECKING",
                    "code": "021214891"
                }
            }
        }
    },
    "requestDetails": {
        "originator": {
            "ipAddress": "5.57.72.118"
        }
    },
    "metadata": {
        "someKey": "someValue",
        "someKey2": {
            "someKey3": "someValue3"
        }
    }
}

When implemented correctly, the fee-charging process works as follows:

The system calculates the total transaction amount (payment amount + customer fee)
During payment processing, the customer fee is:
- Deducted from the EPC's wallet.
- Transferred to your designated fee wallet.
The full payment amount (excluding fees) is sent to the recipient

This approach ensures transparent fee management while maintaining accurate transaction accounting.

Here's an example of how the customer fee is calculated:

When you receive the amount of $100 from Customer Jane and charge a $0.50 EP customer fee, Jane must have a minimum balance of $100.75 in her wallet (transaction amount $100 + BVNK fee $0.25 + customer fee $0.50). After a successful transaction,

Jane's initial wallet balance was $100.75. The current balance is now $0.

Amount credited to your designated fee wallet is $0.50.

Important Considerations

Outgoing payments: Currently, the customer fees are only supported for payment type: OUT.
Make sure the EPC's wallet has enough funds to cover the customer fee. If fees like network or customer fees cannot be covered, the transaction is cancelled.
Fee Structure: Customer fees are implemented as a flat fee, a fixed predetermined price, per transaction.
Optional: You are not required to charge customer fees. Transactions can be processed without additional fees if desired.

Error Handling

If the EPC's wallet does not have enough funds for the customer fee, you have two options:

Return an "insufficient funds" error to the user. In this case, the transaction is cancelled.
Reduce the transaction amount to accommodate the fee. This ensures the total (transaction amount plus fee) does not exceed the available balance.