Multiple destinations
Learn how to send money from a single source to a multiple destinations.
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.
Let’s get started ✨
What we’ll cover …
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.
| User | Balance ID | Expectation |
|---|---|---|
| Sender | bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38 | Will send a total of USD 30,000 |
| Person A | bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f | Will receive 20% of USD 30,000 |
| Person B | bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d | Will receive USD 10,000 |
| Person C | bln_7d98dfe9-5c3e-4c9b-b96a-65f6d9f7b89b | Will 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.
| Parameters | Description |
|---|---|
| Amount | Total amount to be sent by the sender (USD 30,000), |
| Source | Balance ID of the sender. |
| Destinations | Balance 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.
{
"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"
}
]
}
| Field | Description | Required | Type |
|---|---|---|---|
amount | Total amount of money to be sent. | Yes | float |
precision | Converts the transaction amount to the lowest unit possible. See also → Understanding precision. | No | int64 |
reference | Unique transaction reference. | Yes | string |
currency | Short code for your asset class. See also → Defining asset classes. | Yes | string |
source | Sender’s balance ID. | Yes | string |
destinations | Contains 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 | |
identifier | Destination’s balance ID | Yes | string |
distribution | Specific amount being sent to the respective destination. | Yes | string |
narration | Short description for the respective destination. | No | string |
meta_data | Custom data associated with the transaction | No | object |
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:
| Reference | Currency | Amount | Source | Destination |
|---|---|---|---|---|
| ref_001adcfgf1 | USD | 6000 | bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38 | bln_f2073f6b-905a-4e3e-b5a2-8d1b3dc2fb7f |
| ref_001adcfgf2 | USD | 10000 | bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38 | bln_64c50fb5-32d5-4f78-9f4a-e8b01aaf025d |
| ref_001adcfgf3 | USD | 14000 | bln_92e4b9b6-0b85-4ef4-87a2-682c31500d38 | bln_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 type | Description | Example |
|---|---|---|
| Specific amount | Provide the specific amount of money to be received | "distribution": "10000" - Means USD 10,000 from the total amount should be received |
| Percentage | Calculates 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 join our Discord community.
Was this page helpful?