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 transfers guide.

Create

Creates a transfer to move money from a source to a destination. The TRANSFERS_WRITE scope enum is required when making a request from the browser.

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
const moov = new Moov(...);
try {
  const transfer = {
    source: { paymentMethodID: "..." },
    destination: { paymentMethodID: "..." },
    amount: {
      value: 3215, // $32.15
      currency: "USD"
    },
    facilitatorFee: {
      total: 8, // $0.08
    },
    description: "Yoga class"
  };
  const { transferID } = moov.transfers.create(transfer);
} catch (err) {
  // ...
}

List

Lists transfers that match the given criteria. The TRANSFERS_READ scope enum is required when making a request from the browser.

1
transfers.list(criteria)

Parameters

Name Type Description
criteria TransferListCriteria Optional properties by which to query and filter a transfer list

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. The TRANSFERS_READ scope enum is required when making a request from the browser.

1
transfers.get(transferID)

Parameters

Name Type Description
transferID string Transfer identifier

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. The TRANSFERS_WRITE scope enum is required when making a request from the browser.

1
transfers.updateMetadata(transferID, metadata)

Parameters

Name Type Description
transferID string Transfer identifier
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. The TRANSFERS_READ scope enum is required when making a request from the browser.

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. The TRANSFERS_WRITE scope enum is required when making a request from the browser.

1
transfers.refund(transferID, idempotencyKey)

Parameters

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

Returns

Promise.<TransferResponse>

Examples

1
2
3
4
5
6
7
8
9
const moov = new Moov(...);
try {
  const { transferID } = moov.transfers.refund(
   "...",
   { amount: 200 } // omit if creating a refund for the full amount
 );
} catch (err) {
  // ...
}

ListRefunds

List refunds for a card transfer. The TRANSFERS_READ scope enum is required when making a request from the browser.

1
transfers.listRefunds(transferID)

Parameters

Name Type Description
transferID string Transfer identifier

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. The TRANSFERS_READ scope enum is required when making a request from the browser.

1
transfers.getRefund(transferID, refundID)

Parameters

Name Type Description
transferID string Transfer identifier
refundID string Refund identifier

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 transfer. Accounts must be enabled by Moov to set this field.
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 Payment method identifier
email string Email associated with the payment method
displayName string Display name associated with the payment method

BankAccount

Properties

Property Type Description
bankAccountID string Bank Account identifier
fingerprint string Fingerprint of the bank account
status new, verified, verificationFailed, pending, errored Bank account status
holderName string Name of the account holder
holderType individual, business Type of holder on a funding source
bankName string Name of the bank
bankAccountType checking, savings, loan, general-ledger The bank account type
routingNumber string Bank account routing number
lastFourAccountNumber string Last four digits of the bank account number

Wallet

Properties

Property Type Description
walletID string Wallet identifier

CardExpiration

Properties

Property Type Description
month string 2 characters
year string 2 characters

CardVerification

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

Properties

Property Type Description
cvv noMatch, match, notChecked, unavailable Card Verification Value status
addressLine1 noMatch, match, notChecked, unavailable Address status
postalCode noMatch, match, notChecked, unavailable Postal code status

Card

Properties

Property Type Description
cardID string Card identifier
fingerprint string Fingerprint of the card
brand American Express, Discover, MasterCard, Visa Card brand
cardType debit, credit, prepaid, unknown Card type
lastFourCardNumber string Last four digits of the card number
bin string Bank Identification Number
expiration CardExpiration The card’s expiration date
holderName string The cardholder’s name
billingAddress Address The billing address associated with the card
cardVerification CardVerification The results of submitting cardholder data to a card network for verification

ACHCode

Models the reason for an ACH return or correction.

Properties

Property Type Description
code string Ach return code (for example, R01)
reason string The network’s reason for the return or correction (for example, insufficient funds)
description string Explanation of the return code and reason

ACHDetails

Properties

Property Type Description
status initiated, originated, corrected, returned, completed ACH rail status
traceNumber string Tracking number that can be used by payment recipient to trace the payment with their external financial institution
return ACHCode ACH return information per Nacha specification
correction ACHCode ACH notification of change information per Nacha specification

PaymentMethod

Properties

Property Type Description
paymentMethodID string Payment method identifier
paymentMethodType moov-wallet, ach-debit-fund, ach-debit-collect, ach-credit-standard, ach-credit-same-day, rtp-credit, card-payment Allowed payment method types
account PaymentMethodAccount Account information associated with the payment method
bankAccount BankAccount Optional bank account object when payment method type is one of ach-debit-fund, ach-debit-collect, ach-credit-standard, or ach-credit-same-day
card Card Optional card object when payment method type is one of card-payment or apple-pay
wallet Wallet Optional wallet object when payment method type is moov-wallet
achDetails ACHDetails Information about ACH transfers and status details
cardDetails CardDetails Statement descriptor and recurring flag for card payments

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 3 letter ISO 4217 currency code

Refund

Properties

Property Type Description
refundID string Refund identifier
createdOn string Date-time the refund was created on
updatedOn string Date-time the refund was updated on
status created, pending, completed, failed Refund status
amount Amount Refund amount

Transfer

Properties

Property Type Description
transferID string Transfer identifier
createdAt string Deprecated (now createdOn)
createdOn string Date-time the transfer was created on
status created, pending, completed, failed, reversed Transfer status
source PaymentMethod paymentMethodID or transferID
destination PaymentMethod paymentMethodID
amount Amount Transfer amount
description string Transfer description (128 characters max)
metadata object Arbitrary key-value pairs
refundedAmount Amount The total refunded amount
refunds Array.<Refund> Array of refunds associated with the transfer
facilitatorFee object Total or markup fee
moovFee number Integer quantity of Moov fee in USD, so $0.11 would be 11
moovFeeDecimal string The precise fee charged - supports up to 9 decimals

TransferCreate

Properties

Property Type Description
source PaymentMethod paymentMethodID or transferID
destination PaymentMethod paymentMethodID
amount Amount Transfer amount represented by an integer value and its currency
facilitatorFee object Total or markup fee
description string Transfer description (128 characters max)
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
{
  "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,
  },
  "description": "Pay Instructor for May 15 Class",
  "metadata": {
    "property1": "string",
    "property2": "string"
  }
}

TransferResponse

Properties

Property Type Description
transferID string Transfer identifier
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 accountID or paymentMethodID
source.accountID string accountID associated with the transfer source
source.paymentMethodID string paymentMethodID associated with the transfer source
destination object accountID or paymentMethodID
destination.accountID string accountID associated with the transfer destination
destination.paymentMethodID string paymentMethodID associated with the transfer destination
amount Amount Transfer amount represented by an integer value and its currency

TransferOptions

Properties

Property Type Description
paymentMethodID string paymentMethodID associated with a transfer
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> Array of available payment methods for the source of a transfer
destinationOptions Array.<TransferOptions> Array of available payment methods for the destination of a transfer

Refund

Properties

Property Type Description
refundID string Refund identifier
createdOn string Date-time the refund was created on
updatedOn string Date-time the refund was updated on
status created, pending, completed, failed Refund status
amount Amount Refund amount
Summary Beta