Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Dashboard Use cases API Changelog
  1. Guides
  2. Money movement

Transfer groups

Transfer groups eliminate delays and create a seamless payment experience for multiple parties involved in a single transaction payment flow.

Implement transfer groups to associate multiple transfers together and run them sequentially. The final beneficiary in a chain of transfers is made aware of incoming funds before they land in their account. This gives platforms more control over the flow of funds which can be beneficial for reporting and preserving the context of the original transfer.

Transfer group use cases

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.

Guidelines

  • 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
3
4
5
6
7
8
9

{
  "source": {
    "transferID": "UUID"
  },
  "destination": {
    "paymentMethodID": "UUID"
  },
  "amount": {}
}

Transfer statuses

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.

Transfer group IDs

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
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "transferID": "",
  "createdOn": "",
  "status": "queued",
  "source": {
    "transferID": "UUID",
    "paymentMethodID": "UUID",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "UUID"
    },
    "account": {}
  },
  "destination": {},
  "amount": {},
  "groupID": "UUID"
}

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.

Summary Beta