Available in version 0.6.0 and later.

​
Overview

Blnk allows you to process similar transactions from a single source to multiple destination, providing your application with more customization and efficiency.

Simplified flow of how multiple sources work

This provides enhanced flexibility and control over complex money flows within your application. By consolidating multiple destinations into one single transaction, you can monitor and manage transactions more effectively, contextualize your transaction, and facilitate easier tracking and reconciliation.

Multiple sources

Let’s get started ✨ What we’ll cover …
  1. Sending to multiple destinations
  2. Distribution types
  3. Handling transaction references

​
Sending to multiple destinations

Consider a customer sending USD 30,000 from their account balance to three people. They want 20% to go to Person A, USD 10,000 to go to Person B, and the remaining amount to Person C.
UserBalance IDExpectation
Senderbln_92e4b9b6-0b85-4ef4-87a2-682c31500d38Will send a total of USD 30,000
Person Abln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7fWill receive 20% of USD 30,000
Person Bbln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025dWill receive USD 10,000
Person Cbln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89bWill receive the remaining amount left

​
1. Define your transaction parameters

Define the total amount to be sent, the source balances you are sending from, and the destination balance you are sending to.
ParametersDescription
AmountTotal amount to be sent by the sender (USD 30,000),
SourceBalance ID of the sender.
DestinationsBalance IDs of all the balances the amount is distributed to.
When sending to multiple destinations, you can only send from one source.

​
2. Initiate the transaction

Call the record-transaction endpoint, and provide the following required fields.
Request
{
    "amount": 30000,
    "precision": 100,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "source": "bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38"
    "destinations": [
        {
            "identifier": "bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f",
            "distribution": "20%",
            "narration": "For groceries"
        },
        {
            "identifier": "bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d",
            "distribution": "10000",
            "narration": "For electricity bills"
        },
        {
            "identifier": "bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b",
            "distribution": "left",
            "narration": "For savings"
        }
    ]
}
FieldDescriptionRequiredType
amountTotal amount of money to be sent.Yesfloat
precisionConverts the transaction amount to the lowest unit possible. See also → Understanding precision.Noint64
referenceUnique transaction reference.Yesstring
currencyShort code for your asset class. See also → Defining asset classes.Yesstring
sourceSender’s balance ID.Yesstring
destinationsContains information about the destinations the money is being sent to. Each object within this array represents a destination and has 2 required fields — identifier and distribution.Yes
identifierDestination’s balance IDYesstring
distributionSpecific amount being sent to the respective destination.Yesstring
narrationShort description for the respective destination.Nostring
meta_dataCustom data associated with the transactionNoobject
When sending to multiple destinations, do not include the destination field in your payload. Use the destinations array to group the participating balances in your payload.
Once your request is submitted, Blnk creates separate transaction records for each source with their respective amounts. The transactions are computed, queued, and processed like this:
ReferenceCurrencyAmountSourceDestination
ref_001adcfgf1USD6000bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f
ref_001adcfgf2USD10000bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d
ref_001adcfgf3USD14000bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b
At the end of the transaction, the sender’s balance will have sent a total of USD 30000.

​
Distribution types

There are three ways you can specify how the amount should be distributed among the destinations as you’ve seen in the example above.
Distribution typeDescriptionExample
Specific amountProvide the specific amount of money to be received"distribution": "10000" - Means USD 10,000 from the total amount should be received
PercentageCalculates a percentage of the total amount to be received"distribution": "20%" - Means 20% of the total amount should be received
”left”Calculates the remaining amount not assigned to a destination"distribution": "left" - Means the remaining amount left after others have been deducted should be received
You can only use the left distribution type once in your request body.
It is crucial to ensure that the total sum of your distributions fields is exactly equal to the value specified in the amount field.

​
Handling transaction references

Blnk auto-generates a unique transaction reference for each transaction record based on the original reference you provided in your transaction request. A counter, starting at 1, is appended for each transaction record created ensuring that the individual transaction records have unique references derived from the original transaction reference. This makes sure that each transaction record is unique through its modified reference ensuring traceability and management while preserving the integrity of the original transaction’s reference.
Refer to the sample transaction table in Step 3 above to see how it is applied.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.