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

Transfer groups

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 to use transfer groups

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.

Creating a transfer group

To create a grouped transfer, provide the transferID in the source object 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": "transferID"
  },
  "destination": {
    "paymentMethodID": "paymentMethodID"
  },
  "amount": {}
}

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, 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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

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

Getting all transfers in a transfer group

You can find all transfers in a 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