With Moov, you can implement transfer groups, allowing you to associate multiple transfers together and run them sequentially. Transfer groups help to make the final beneficiary in a chain of transfers aware of incoming funds before they land in their account. This also gives platforms more control over the flow of funds which can be beneficial for reporting and preserving the context of the original transfer.
When you create a grouped transfer, you can split a transfer into two or more child transfers with distinct destinations, as long as the sum of the child transfers is less than or equal to the amount of the preceding transfer.
When there are multiple parties involved in a payment flow that represents a single transaction, transfer groups will eliminate delays and create a seamless payment experience. For example, if a service-based platform is collecting payments from customers and transferring those funds to the service provider, transfer groups enable funds to flow:
- from a customer to the platform
- from the platform to the service provider
The service provider will be able to know that their service fee is incoming at the time of the initial charge, while also giving them the context of the processing fees included as a line item.
To create a grouped transfer, simply provide the transferID in the source object of your POST request of the immediately preceding transfer. Transfers that belong to a group must have an amount less than or equal to the amount of the source transfer.
- Child transfers must be less than or equal to the original transfer amount
- You can collect a fee on one or all transfers in the group, just be sure to consider the net amount when creating the subsequent transfer
- If a child transfer destination is set to a bank account, the child transfer can’t become the source of any more transfers
queued: a transfer that is part of a group will have the
queued status until the preceding transfer has successfully
pending: after the preceding transfer has
completed, the next transfer will be
pending indicating we have kicked off the money movement process.
failed: if a transfer in a group fails, all subsequent transfers will be
failed transfers, you will be able to retry the transfer at any point
- The most common reason a transfer in a group may fail is if a wallet doesn’t have sufficient funds in order to fund the next transfer
transfer.updatedwebhook event to subscribe to changes on the parent and child transfers.
When any amount of transfers are linked through a parent-child relationship, they will share a
Moov mints and assigns an identifier for the transfer group automatically, which is the
transferID of the most senior parent transfer. If a transfer belongs to a group, the
groupID will be returned in the
GET /transfers response.
You can find all transfers in a group by passing the
groupID to the
GET /transfers endpoint. Applying this filter will result in a list of transfers that belong to the group.
You can assemble a chain of events by requesting all of the transfers in a group, and recursively comparing the
source.transferID of each child transfer.