1. Guides

Transfers

Transfers occur between a source and destination payment method, which represents how and where money should move. The only other required field is an amount.

Node SDK transfer example:

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

const moov = new Moov(credentialsObject);

const transfer = await moov.transfers.create({
  source: {
    paymentMethodID: "source-payment-method-id",
  },
  destination: {
    paymentMethodID: "destination-payment-method-id",
  },
  amount: {
    value: 100,
    currency: "USD"
  },
});

Flow of funds

All transfers facilitated with Moov involve money moving in, out, through, or within the Moov platform. Since all funds flow through Moov, a single transfer can take advantage of multiple payment rails which allows you to tailor the cost, speed, and risk of each payment to your particular use case.

Source

Bank account Same-day ACH

Bank accounts

Same-day ACH Faster ACH*

Debit / credit cards

Card payment

Wallets

Moov Wallet

Destination

Bank account Same-day ACH

Bank accounts

Same-day ACH Standard ACH RTP

Wallets

Moov Wallet

Transfer responses

Moov uses standard HTTP status codes to communicate the outcome of all Moov API requests. The following table summarizes the possible responses after submitting a Create transfer POST /transfers request.

Transfer statuses

A transfer can have the following statuses:

Rail specific statuses are also available under the source and destination. You can view rail-specific statuses in our other guides:

• Cards
• ACH

Source

A source represents the first stage of a transfer, and is where funds originate. A source can be an external linked bank account, payment card, or a Moov wallet balance. The following payment method types can be used as the source of a transfer:

Destination

The destination represents the final stage of a transfer and the ultimate recipient of the funds. The following payment method types can be used as the destination of a transfer.

Idempotency

To prevent duplicate transfers, every POST /transfers request requires an X-Idempotency-Key header. You are responsible for generating a version 4 UUID idempotency key. If you try to create a transfer with the same idempotency key twice, your second attempt will result in a 409 error response indicating that a transfer was previously created with that idempotency key.

Transfer options utility

Moov offers the transfer options POST endpoint as an easy way to know which payment methods can be used in a transfer.

Some payment methods can only be used as the source or destination, and not all payment method combinations are valid options. The payment methods available for use also depend on the capabilities of the source and destination accounts. Transfer-options takes this business logic into account as well as network-specific restrictions such as maximum payment amounts to ensure a valid transfer request.

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

{
  "source": {
    "accountID": "4528aba-b9a1-11eb-8529-0242ac13003", 
    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43" 
  },
  "destination": {
    "accountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43", 
    "paymentMethodID": "4528aba-b9a1-11eb-8529-0242ac13003" 
  },
  "amount": {
    "value": 100,
    "currency": "USD"
  }
}

To use transfer-options, make a request to the transfers POST endpoint with a Moov accountID or paymentMethodID and an amount.

• Supplying a single accountID in the source{} or destination{}: will return a list of available payment methods
• Supplying an accountID for both the source{} and destination{}: will return two lists of payment methods filtered on the capabilities of the transfer participants
• Supplying one paymentMethodID and one accountID: will return a list of valid payment methods for the accountID provided

In practice, transfer-options can be used to present a menu of different options for how and where you want money to move.

Bank holidays

Bank holidays can cause delays in transfers. If you’re creating a transfer on a bank holiday, it will be processed on the next business day. Settlement from the prior day’s card sales will be delayed when the settlement day is a bank holiday.

Holidays observed by the Federal Reserve System include:

• New Year’s Day
• Martin Luther King Jr. Day
• Presidents’ Day
• Memorial Day
• Juneteenth
• Independence Day
• Labor Day
• Columbus Day
• Veterans Day
• Thanksgiving Day
• Christmas Day

FAQ