Guides API reference Use cases Changelog

Transfer groups

A transfer group chains transfers so each one runs after the one before it completes. Use it to split a single customer payment between your platform and the people you pay.

Every transfer in the group shares a groupID, so the final recipient can see incoming funds from the moment of the original charge, and you keep the context of the original payment for reporting.

When to use a transfer group

With a transfer group, you can split a transfer into two or more child transfers with distinct destinations. The sum of the child transfers must be less than or equal to the amount of the preceding transfer.

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 customers 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.

Rules

  • 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, but 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 additional transfers

Create a transfer group

To create a transfer group, provide the transferID in the source of your POST request of the immediate preceding transfer. Transfers that belong to a group must have an amount less than or equal to the amount of the source transfer.

1{
2  "source": {
3    "transferID": "string"
4  },
5  "destination": {
6    "paymentMethodID": "string"
7  },
8  "amount": {}
9}

Transfer statuses in a group

Status Description
queued A transfer that is part of a group will have the queued status until the preceding transfer has successfully completed
pending After the preceding transfer has completed, the next transfer will be pending indicating we have kicked off the money movement process
completed The transfer has completed
canceled When a preceding transfer fails, subsequent transfers will be canceled and the funds will be at the destination of the last completed transfer
failed If a transfer in a group fails, all subsequent transfers will be canceled. For 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.
Use the transfer.updated webhook event to subscribe to changes on the parent and child transfers.

Find the group ID

When any amount of transfers are linked through a parent-child relationship, they will share a groupID.

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 transfers GET response.

 1{
 2  "transferID": "",
 3  "createdOn": "",
 4  "status": "queued",
 5  "source": {
 6    "transferID": "string",
 7    "paymentMethodID": "string",
 8    "paymentMethodType": "moov-wallet",
 9    "wallet": {
10      "walletID": "string"
11    },
12    "account": {}
13  },
14  "destination": {},
15  "amount": {},
16  "groupID": "string"
17}

Get all transfers in a group

You can find all transfers in a transfer group by passing the groupID to the list transfers GET 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.