Transfers

A transfer is the movement of money between Moov accounts, from source to destination. Provided you have linked a bank account which has been verified, you can initiate a transfer to another Moov account. For more context, read our guide on transfers.

Create

Creates a transfer to move money from a source to a destination.

1

transfers.create(transfer, idempotencyKey)

Parameters

Name	Type	Description
transfer	TransferCreate	Subset of the Transfer object
idempotencyKey	`string`	Optional UUID to prevent duplicate transfers

Returns

Promise.<TransferResponse>

Examples

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


const moov = new Moov(...);
try {
  const transfer = {
    source: { paymentMethodID: "..." },
    destination: { paymentMethodID: "..." },
    amount: {
      value: 3215, // $32.15
      currency: "USD"
    },
    facilitatorFee: {
      value: 8, // $0.8
      currency: "USD"
    },
    description: "Yoga class"
  };
  const { transferID } = moov.transfers.create(transfer);
} catch (err) {
  // ...
}

List

Lists transfers that match the given criteria.

1

transfers.list(criteria)

Parameters

Name	Type	Description
criteria	TransferListCriteria

Returns

Promise.<Array.<Transfer>>

Examples

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


const moov = new Moov(...);
try {
  const criteria = {
    accountIDs: ["...", "...", ...],
    status: "pending",
    startDateTime: new Date("1/1/2022").toISOString(), // inclusive
    endDateTime: new Date("2/1/2022").toISOString(), // exclusive
    count: 15,
    skip: 15, // start on page 2
  };
  const results = await moov.transfers.list(criteria);
} catch (err) {
  // ...
}

Get

Gets the details of a transfer.

1

transfers.get(transferID)

Parameters

Name	Type	Description
transferID	`string`

Returns

Promise.<Transfer>

Examples

1
2
3
4
5
6


const moov = new Moov(...);
try {
  const transfer = await moov.transfers.get("...");
} catch (err) {
  // ...
}

UpdateMetadata

Update the metadata on a transfer.

1

transfers.updateMetadata(transferID, metadata)

Parameters

Name	Type	Description
transferID	`string`
metadata	`object`	Arbitrary key-value pairs

Returns

Promise.<Transfer>

Examples

1
2
3
4
5
6
7
8
9


const moov = new Moov(...);
try {
  const transfer = await moov.transfers.updateMetadata(
    "...",
    { key: "value" }
  );
} catch (err) {
  // ...
}

GetTransferOptions

Gets the available payment options for a transfer.

1

transfers.getTransferOptions(transferOptionsCriteria)

Parameters

Name	Type	Description
transferOptionsCriteria	TransferOptionsCriteria	Criteria for available payment options

Returns

Promise.<AvailableTransferOptions>

Examples

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


const moov = new Moov(...);
try {
  const options = moov.transfers.getTransferOptions({
    source: {
      accountID: "...",
      paymentMethodID: "..."
    },
    destination: {
      accountID: "...",
      paymentMethodID: "..."
    },
    amount: {
      value: 43350, // $433.50
      currency: "USD"
    }
  });
} catch (err) {
  // ...
}

Refund

Initiate a refund for a card transfer.

1

transfers.refund(transferID, idempotencyKey)

Parameters

Name	Type	Description
transferID	`string`
idempotencyKey	`string`	Optional UUID to prevent duplicate refunds

Returns

Promise.<TransferResponse>

Examples

1
2
3
4
5
6


const moov = new Moov(...);
try {
  const { transferID } = moov.transfers.refund("...");
} catch (err) {
  // ...
}

ListRefunds

List refunds for a card transfer.

1

transfers.listRefunds(transferID)

Parameters

Name	Type	Description
transferID	`string`

Returns

Promise.<Array.<Refund>>

Examples

1
2
3
4
5
6


const moov = new Moov(...);
try {
  const refunds = moov.transfers.listRefunds("...");
} catch (err) {
  // ...
}

GetRefund

Get details of a specific refund.

1

transfers.getRefund(transferID, refundID)

Parameters

Name	Type	Description
transferID	`string`
refundID	`string`

Returns

Promise.<Refund>

Examples

1
2
3
4
5
6


const moov = new Moov(...);
try {
  const refund = moov.transfers.getRefund("...");
} catch (err) {
  // ...
}

Types

CardDetails

Properties

Property	Type	Description
dynamicDescriptor	`string`	An optional override of the default card statement descriptor for a single transfer.
transactionSource	`first-recurring`, `recurring`, `unscheduled`, `null`	Enum: [first-recurring recurring unscheduled] Describes how the card transaction was initiated

PaymentMethodAccount

High-level account information associated with a payment method.

Properties

Property	Type	Description
accountID	`string`
email	`string`
displayName	`string`

BankAccount

Properties

Property	Type	Description
bankAccountID	`string`
fingerprint	`string`
status	`new`, `verified`, `verificationFailed`, `pending`, `errored`
holderName	`string`
holderType	`individual`, `business`
bankName	`string`
bankAccountType	`checking`, `savings`, `unknown`
routingNumber	`string`
lastFourAccountNumber	`string`

Wallet

Properties

Property	Type	Description
walletID	`string`

CardExpiration

Properties

Property	Type	Description
month	`string`	Two-character month
year	`string`	Two-character year

CardVerification

The results of submitting cardholder data to a card network for verification.

Properties

Property	Type	Description
cvv	`noMatch`, `match`, `notChecked`, `unavailable`
addressLine1	`noMatch`, `match`, `notChecked`, `unavailable`
postalCode	`noMatch`, `match`, `notChecked`, `unavailable`

Card

Properties

Property	Type	Description
cardID	`string`
fingerprint	`string`
brand	`American Express`, `Discover`, `MasterCard`, `Visa`
cardType	`debit`, `credit`, `prepaid`, `unknown`
lastFourCardNumber	`string`
bin	`string`
expiration	CardExpiration
holderName	`string`
billingAddress	Address
cardVerification	CardVerification

ACHCode

Models the reason for an ACH return or correction.

Properties

Property	Type	Description
code	`string`
reason	`string`
description	`string`

ACHDetails

Properties

Property	Type	Description
	`initiated`, `originated`, `corrected`, `returned`, `completed`
traceNumber	`string`
return	ACHCode
correction	ACHCode

PaymentMethod

Properties

Property	Type	Description
paymentMethodID	`string`
paymentMethodType	`moov-wallet`, `ach-debit-fund`, `ach-debit-collect`, `ach-credit-standard`, `ach-credit-same-day`, `rtp-credit`, `card-payment`
account	PaymentMethodAccount
bankAccount	BankAccount
wallet	Wallet
card	Card
achDetails	ACHDetails
cardDetails	CardDetails

Amount

Properties

Property	Type	Description
value	`number`	Integer quantity in the smallest unit of the specified currency. In USD this is cents, so $12.04 is 1204 and $0.99 would be 99.
currency	`string`	Three-letter ISO 4217 currency code

Refund

Properties

Property	Type	Description
refundID	`string`
createdOn	`string`
updatedOn	`string`
status	`created`, `pending`, `completed`, `failed`
amount	Amount

Transfer

Properties

Property	Type	Description
transferID	`string`
createdAt	`string`
status	`created`, `pending`, `completed`, `failed`, `reversed`
source	PaymentMethod
destination	PaymentMethod
amount	Amount
description	`string`
metadata	`object`	Arbitrary key-value pairs
refundedAmount	Amount
refunds	Array.<Refund>
facilitatorFee	`object`
moovFee	`number`	Integer quantity of Moov fee in USD, so $0.11 would be 11

TransferCreate

Properties

Property	Type	Description
source	PaymentMethod
destination	PaymentMethod
amount	Amount
facilitatorFee	`object`
description	`string`
metadata	`object`	Arbitrary key-value pairs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


{
  "source": {
    "transferID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
    "cardDetails": {}
  },
  "destination": {
    "paymentMethodID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43"
  },
  "amount": {
    "currency": "USD",
    "value": 1204
  },
  "facilitatorFee": {
    "total": 0,
    "markup": 0
  },
  "description": "Pay Instructor for May 15 Class",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

TransferResponse

Properties

Property	Type	Description
transferID	`string`

1
2
3


{
  "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80"
}

TransferListCriteria

Properties

Property	Type	Description
accountIDs	`Array.<string>`	Optional list of account IDs to filter sources and destinations
status	`string`	Optional transfer status by which to filter the transfers
startDateTime	`string`	Optional date-time which inclusively filters all transfers created after this starting date-time
endDateTime	`string`	Optional date-time which exclusively filters all transfers created before this date-time
count	`number`	Optional parameter to limit the number of results in the query
skip	`number`	Optional number of items to offset before starting to collect the result set

TransferOptionsCriteria

Criteria for finding available payment types for a transfer.

Properties

Property	Type	Description
source	`object`
source.accountID	`string`
source.paymentMethodID	`string`
destination	`object`
destination.accountID	`string`
destination.paymentMethodID	`string`
amount	Amount

TransferOptions

Properties

Property	Type	Description
paymentMethodID	`string`
paymentMethodType	`moov-wallet`, `ach-debit-fund`, `ach-debit-collect`, `ach-credit-standard`, `ach-credit-same-day`, `rtp-credit`, `card-payment`
wallet	Wallet	Populated when `paymentMethodType` is “moov-wallet”
bankAccount	BankAccount	Populated when `paymentMethodType` is one of the ACH or FTP variations
card	Card	Populated when `paymentMethodType` is “card-payment”

AvailableTransferOptions

Properties

Property	Type	Description
sourceOptions	Array.<TransferOptions>
destinationOptions	Array.<TransferOptions>

Refund

Properties

Property	Type	Description
refundID	`string`
createdOn	`string`
updatedOn	`string`
status	`created`, `pending`, `completed`, `failed`
amount	Amount

Transfers

Was this helpful?