When mapping out your payments workflow, you may come across scenarios in which you need to receive funds from one or more users and collate those into a single outbound payment. Or inversely, you may have received a single inbound payment and want to split that into multiple pieces in order to send payments to many parties. Either way, you want to split things up.

You may even have a scenario when you want to split both the inbound and the outbound payment. This guide will run you through how to split the inbound payment and the outbound payment, but you could do both.

Prerequisite reading

Before you go too far with working out how to split your payments, there are some Assembly concepts that we will be using. If you haven't already covered off the following, it will make this guide easier to follow:

Splitting your inbound payments (pay-ins)

When creating a split pay-in there are two general methods for receiving split payments with Assembly: item-driven and user-driven.

Item-driven pay-ins

For your user(s), you would create a series of Items, each of those representing the amount the payment is for. For example, you may want your user to pay 10 amounts of $100 every month for a total of $1,000.

In a scenario like this, you are likely controlling how much a user will pay, the payment method they will use, what they are paying for, and possibly when they will pay (e.g. rental payments, subscription payments etc.).

User-driven pay-ins

The second method is where you directly fund a user's digital wallet and create an Item once a trigger or threshold has been reached. For example, you may want your users to send payments in to your platform but the $ value of funds being sent can't be known or accurately determined ahead of time (e.g. your users contribute funds to a diversified share portfolio at ad-hoc intervals).

In a scenario like this, you can't control how much your users pay, what payment method they will use, or when they will pay it, but you do control what they are paying for (e.g. investments, invoice payments etc.).

Basic inbound split payment workflow

For the following example, we will use a user-driven pay-in to demonstrate how to take funds which have 'landed' in many users' digital wallets and send them to a single destination. To make this work for an item-driven workflow, instead of creating Items after funds have landed, you would create an Item ahead of time. The key difference being that in one scenario you dictate the value being paid and how it is paid (item-driven), and in the other, your users are sending you money (user-driven).

For the below, we'll use the example of a property management platform where many tenants are paying rent to a single landlord.

In this model, we have the following actors:

  • Tenant (a pay-in user)
  • Landlord (a pay-out user)
  • Platform (the property management platform)

For a total pay-in amount of $1,000, you might want to distribute the funds as follows:

  • $1,000 total due for rent
  • $500 paid by Tenant 1
  • $500 paid by Tenant 2
  • $900 sent to the Landlord
  • $100 taken by the platform as your fee

To create this type of workflow with the Assembly API, you would do the following:

  1. Create a callback record on the Transactions object to be notified when a Tenant pays their rent (and funds have 'landed' in their digital wallet).
    # This is important, or you won't know when tenants have paid. If your workflow was Item-driven, you would create a callback on the Item to be notified when something was paid.
  2. Create a User for Tenant 1.
  3. Create a User for Tenant 2.
  4. Create a User to hold the funds for the rental payment (call it "Rent for June") and do not attach any card or bank accounts to this user.
  5. Create a User for your Landlord.
  6. Create a bank account for your Landlord and set this as the disbursement account.
  7. Create a Fee where the "to" value is set to the Landlord (seller) for 10% of the Item value.
  8. Now that your pieces are in place, we will assume that the payment method being used is BPay and that both Tenant 1 and Tenant 2 have paid their rent. To make this happen in our PreLive environment call PATCH /testing/wallet_accounts/process_bpay to add funds to a digital wallet.
  9. Create an Item (use type 2, Express) between the Buyer and the Holding User for the full amount of $100 (apply the fee ID from above).
  10. Make the payment to the Item using the pay-in user's bank or card account as the funding source.
  11. The funds should now be in the Holding user's digital wallet, less $20 which has been sent to the Platform as the fee.
  12. Locate the digital wallet ID of your Holding user, check the balance to confirm and take note of the wallet account ID, you'll need it in a second.
  13. Create an Item (use type 2, Express) between the Holding user's digital wallet and the Referrer for $10.
  14. Make the payment to the Item using the Holding user's wallet account as the funding source.
  15. Create an Item (use type 2, Express) between the Holding User's digital wallet and the Seller for $70.
  16. Make the payment to the Item using the Holding user's wallet account as the funding source.
  17. With all Items now in a completed state, your Holding User should be left with $0, your payout user will have $70, your Referrer will have $10 and the platform will have earned $20.

You've now created a split payout workflow incorporating multiple users. You could extend the model to create additional payouts to users as required.

Splitting your outbound payments (pay-outs)

The below example runs through how to split a pay-out into multiple pieces from a single inbound payment. In the example, the funding source used is either a bank account or a card account, but you could also use a digital wallet (per the above).

Basic outbound split payment workflow

For the below, we'll use the example of a Widgets Marketplace where people can buy and sell widgets. A Referrer can drive business to your platform by finding widget Buyers and giving them a referral code to use in the marketplace.

In this model, we have the following actors:

  • Buyer (a pay-in user)
  • Seller (a pay-out user)
  • Referrer (a pay-out user)
  • Platform (the Widget Marketplace)

For a pay-in amount of $100, you might want to distribute the funds as follows:

  • $100 paid for Widgets
  • $70 sent to the seller for the sale of Widgets
  • $10 sent to the referrer as their fee
  • $20 taken by the platform as your fee

To create this type of workflow with the Assembly API, you would do the following:

  1. Create a User for the pay-in (the person who is paying).
  2. Create a bank or card account for your pay-in user.
  3. Create a User to hold the funds (call it the Holding User) and do not attach any card or bank accounts to this user.
  4. Create a User for the payout.
  5. Create a bank account for your payout user and set this as the disbursement account.
  6. Create a User for the Referrer.
  7. Create a bank account for your Referrer user and set this as the disbursement account.
  8. Create a Fee where the "to" value is set to the Seller for 20% of the Item value.
  9. Create an Item (use type 2, Express) between the Buyer and the Holding User for the full amount of $100 (apply the fee ID from above).
  10. Make the payment to the Item using the pay-in user's bank or card account as the funding source.
  11. The funds should now be in the Holding user's digital wallet, less $20 which has been sent to the Platform as the fee.
  12. Locate the digital wallet ID of your Holding user, check the balance to confirm and take note of the wallet account ID, you'll need it in a second.
  13. Create an Item (use type 2, Express) between the Holding user's digital wallet and the Referrer for $10.
  14. Make the payment to the Item using the Holding user's wallet account as the funding source.
  15. Create an Item (use type 2, Express) between the Holding User's digital wallet and the Seller for $70.
  16. Make the payment to the Item using the Holding user's wallet account as the funding source.
  17. With all Items now in a completed state, your Holding User should be left with $0, your payout user will have $70, your Referrer will have $10 and the platform will have earned $20.

You've now created a a split pay-out workflow incorporating multiple users. You could extend the model to create additional payouts to users as required.

Did this answer your question?