Create a transfer

Move money by providing the source, destination, and amount in the request body.

Read our transfers overview guide to learn more.

To access this endpoint using an access token you’ll need to specify the /accounts/{accountID}/transfers.write scope.

POST

/accounts/{accountID}/transfers

cURL Go

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


curl -X POST "https://api.moov.io/accounts/{accountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "value": 100,
      "currency": "USD"
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID"
    },
    "description": "Optional transaction description."
  }'\

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


mc, _ := moov.NewClient()

var accountID string

mc.CreateTransfer(ctx, accountID, moov.CreateTransfer{
  Amount: moov.Amount{
    Currency: "USD",
    Value:    100, // $1.00
  },
  Destination: moov.CreateTransfer_Destination{
    PaymentMethodID: "UUID",
  },
  Source: moov.CreateTransfer_Source{
    PaymentMethodID: "UUID",
  },
  Description: "Optional transaction description.",
})

200 201 202 400 404 409 422 429 500 504

The request completed successfully.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

A transfer was successfully created but an error occurred while generating the synchronous response. The asynchronous response object will be returned.

{
  "createdOn": "2019-08-24T14:15:22Z",
  "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

A transfer was successfully created but a timeout occurred while waiting for a synchronous response. Rail-specific details may be missing from the response object.

Details of a Transfer.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The server could not understand the request due to invalid syntax.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The requested resource was not found.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Attempted to create a transfer using a duplicate X-Idempotency-Key header.

Details of a Transfer.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.

{
  "FacilitatorFee.MarkupDecimal": "string",
  "FacilitatorFee.TotalDecimal": "string",
  "Transfer": "string",
  "amount": "string",
  "description": "string",
  "destinationPaymentMethodID": "string",
  "error": "string",
  "metadata": "string",
  "source": "string",
  "sourcePaymentMethodID": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Request was refused due to rate limiting.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed due to an unexpected error.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed because a downstream service failed to respond.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Headers

x-moov-version


      string

API version

Specify an API version.

API versioning follows the format vYYYY.QQ.BB, where

YYYY is the year
QQ is the two-digit month for the first month of the quarter (e.g., 01, 04, 07, 10)
BB is the build number, starting at .01, for subsequent builds in the same quarter.
- For example, v2024.01.00 is the initial release of the first quarter of 2024.

The latest version represents the most recent development state. It may include breaking changes and should be treated as a beta release.

Default: v2024.01.00

x-idempotency-key


      string
      <uuid>

required

Prevents duplicate transfers from being created.

x-wait-for


      string

Optional header that indicates whether to return a synchronous response that includes full transfer and rail-specific details or an asynchronous response indicating the transfer was created (this is the default response if the header is omitted).

Possible values: rail-response

Path parameters

accountID


      string
      <uuid>

required

The merchant’s Moov account ID.

Body

application/json

amount


        object

required

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

destination


        object

required

The final stage of a transfer and the ultimate recipient of the funds.

Show child attributes

paymentMethodID


        string

required

achDetails


        object

Show child attributes

companyEntryDescription


        string

[4 to 10] characters

An optional override of the default NACHA company entry description for a transfer.

originatingCompanyName


        string

[4 to 16] characters

An optional override of the default NACHA company name for a transfer.

cardDetails


        object

Show child attributes

dynamicDescriptor


        string

[4 to 22] characters

An optional override of the default card statement descriptor for a transfer. Accounts must be enabled by Moov to set this field.

source


        object

required

Where funds for a transfer originate. For the source, you must include either a paymentMethodID or a transferID.

Show child attributes

achDetails


        object

Show child attributes

companyEntryDescription


        string

[4 to 10] characters

An optional override of the default NACHA company entry description for a transfer.

debitHoldPeriod


        string<enum>

An optional override of your default ACH hold period in banking days. The hold period must be longer than or equal to your default setting.

Possible values: no-hold, 1-day, 2-days

originatingCompanyName


        string

[4 to 16] characters

An optional override of the default NACHA company name for a transfer.

secCode


        string<enum>

Code used to identify the ACH authorization method.

Possible values: WEB, PPD, CCD, TEL

cardDetails


        object

Show child attributes

dynamicDescriptor


        string

[4 to 22] characters

An optional override of the default card statement descriptor for a transfer. Accounts must be enabled by Moov to set this field.

transactionSource


        string<enum>

Specifies the nature and initiator of a transaction.

Crucial for recurring and merchant-initiated transactions as per card scheme rules. Omit for customer-initiated e-commerce transactions.

Possible values: first-recurring, recurring, unscheduled

paymentMethodID


        string<uuid>

paymentToken


        string

transferID


        string<uuid>

A transferID is used to create a transfer group, associating the new transfer with a parent transfer.

description


        string

<=256 characters

An optional description of the transfer for your own internal use.

facilitatorFee


        object

Total or markup fee.

Show child attributes

markup


        integer<int64>

Markup facilitator fee in cents. Only either markup or markupDecimal can be set.

markupDecimal


        string

Same as markup, but a decimal-formatted numerical string that represents up to 9 decimal place precision. Only either markup or markupDecimal can be set. Set this field if you expect the fee to be in fractions of a cent.

total


        integer<int64>

Total facilitator fee in cents. Only either total or totalDecimal can be set.

totalDecimal


        string

Same as total, but a decimal-formatted numerical string that represents up to 9 decimal place precision.

Only either total or totalDecimal can be set. Set this field if you expect the fee to be in fractions of a cent.

metadata


        object

Free-form key-value pair list. Useful for storing information that is not captured elsewhere.

Response

application/json

Sync Async

Details of a Transfer.

amount


        object

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

cancellations


        array

Show child attributes

cancellationID


        string

createdOn


        string<date-time>

status


        string<enum>

Possible values: pending, completed, failed

completedOn


        string<date-time>

createdOn


        string<date-time>

description


        string

<=128 characters

An optional description of the transfer for your own internal use.

destination


        object

Show child attributes

account


        object

required

Show child attributes

accountID


        string

required

displayName


        string

required

email


        string

required

paymentMethodID


        string

required

paymentMethodType


        string<enum>

required

The payment method type that represents a payment rail and directionality

Possible values: moov-wallet, ach-debit-fund, ach-debit-collect, ach-credit-standard, ach-credit-same-day, rtp-credit, card-payment, push-to-card, pull-from-card, apple-pay, card-present-payment

achDetails


        object

ACH specific details about the transaction.

Show child attributes

status


        string<enum>

required

Status of a transaction within the ACH lifecycle.

Possible values: initiated, originated, corrected, returned, completed, canceled

traceNumber


        string

<=15 characters required

canceledOn


        string<date-time>

companyEntryDescription


        string

[4 to 10] characters

An optional override of the default NACHA company entry description for a transfer.

completedOn


        string<date-time>

correctedOn


        string<date-time>

correction


        object

Show child attributes

code


        string

description


        string

reason


        string

debitHoldPeriod


        string<enum>

An optional override of your default ACH hold period in banking days. The hold period must be longer than or equal to your default setting.

Possible values: no-hold, 1-day, 2-days

failedOn


        string<date-time>

initiatedOn


        string<date-time>

originatedOn


        string<date-time>

originatingCompanyName


        string

[4 to 16] characters

An optional override of the default NACHA company name for a transfer.

return


        object

Show child attributes

code


        string

description


        string

reason


        string

returnedOn


        string<date-time>

secCode


        string<enum>

Code used to identify the ACH authorization method.

Possible values: WEB, PPD, CCD, TEL

applePay


        object

Describes an Apple Pay token on a Moov account.

Show child attributes

brand


        string<enum>

required

The card brand.

Possible values: American Express, Discover, Mastercard, Visa, Unknown

cardDisplayName


        string

required

User-friendly name of the tokenized card returned by Apple.

It usually contains the brand and the last four digits of the underlying card. There is no standard format.

cardType


        string<enum>

required

The type of the card.

Possible values: debit, credit, prepaid, unknown

dynamicLastFour


        string

required

The last four digits of the Apple Pay token, which may differ from the tokenized card’s last four digits.

expiration


        object

required

The expiration date of the card or token.

Show child attributes

month


        string

2 characters required

year


        string

2 characters required

fingerprint


        string

<=100 characters required

Uniquely identifies a linked payment card or token. For Apple Pay, the fingerprint is based on the tokenized card number and may vary based on the user’s device. This field can be used to identify specific payment methods across multiple accounts on your platform.

issuerCountry


        string

Country where the underlying card was issued.

bankAccount


        object

A bank account as contained within a payment method.

Show child attributes

bankAccountID


        string<uuid>

required

bankAccountType


        string<enum>

required

The bank account type.

Possible values: checking, savings, general-ledger, loan

bankName


        string

required

fingerprint


        string

<=100 characters required

Once the bank account is linked, we don’t reveal the full bank account number.

The fingerprint acts as a way to identify whether two linked bank accounts are the same.

holderName


        string

required

holderType


        string<enum>

required

The type of holder on a funding source.

Possible values: individual, business

lastFourAccountNumber


        string

required

routingNumber


        string

required

status


        string<enum>

required

Possible values: new, verified, verificationFailed, pending, errored

updatedOn


        string<date-time>

required

card


        object

A card as contained within a payment method.

Show child attributes

billingAddress


        object

required

Show child attributes

postalCode


        string

<=10 characters required

addressLine1


        string

<=60 characters

addressLine2


        string

<=32 characters

city


        string

<=32 characters

country


        string

<=2 characters

stateOrProvince


        string

<=2 characters

bin


        string

[6 to 8] characters required

The first six to eight digits of the card number, which identifies the financial institution that issued the card.

brand


        string<enum>

required

The card brand.

Possible values: American Express, Discover, Mastercard, Visa, Unknown

cardID


        string<uuid>

required

ID of the card.

cardType


        string<enum>

required

The type of the card.

Possible values: debit, credit, prepaid, unknown

cardVerification


        object

required

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

Show child attributes

accountName


        object

required

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

Show child attributes

firstName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

fullName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

lastName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

middleName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

addressLine1


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

cvv


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

postalCode


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

domesticPullFromCard


        string<enum>

required

Indicates if the card supports domestic pull-from-card transfer.

Possible values: not-supported, supported, unknown

domesticPushToCard


        string<enum>

required

Indicates which level of domestic push-to-card transfer is supported by the card, if any.

Possible values: not-supported, standard, fast-funds, unknown

expiration


        object

required

The expiration date of the card or token.

Show child attributes

month


        string

2 characters required

year


        string

2 characters required

fingerprint


        string

<=100 characters required

issuer


        string

required

Financial institution that issued the card.

issuerCountry


        string

required

Country where the card was issued.

lastFourCardNumber


        string

4 characters required

Last four digits of the card number

cardAccountUpdater


        object

The results of the most recent card update request.

Show child attributes

updateType


        string<enum>

The results of the card update request.

Possible values: unspecified, account-closed, contact-cardholder, expiration-update, no-change, no-match, number-update

updatedOn


        string<date-time>

cardOnFile


        boolean

Indicates cardholder has authorized card to be stored for future payments.

holderName


        string

The name of the cardholder as it appears on the card.

merchantAccountID


        string<uuid>

cardDetails


        object

Card-specific details about the transaction.

Show child attributes

status


        string<enum>

required

Status of a transaction within the card payment lifecycle.

Possible values: initiated, confirmed, canceled, settled, failed, completed

canceledOn


        string<date-time>

completedOn


        string<date-time>

confirmedOn


        string<date-time>

dynamicDescriptor


        string

[4 to 22] characters

An optional override of the default card statement descriptor for a transfer. Accounts must be enabled by Moov to set this field.

failedOn


        string<date-time>

failureCode


        string<enum>

Possible values: call-issuer, do-not-honor, processing-error, invalid-transaction, invalid-amount, no-such-issuer, reenter-transaction, cvv-mismatch, lost-or-stolen, insufficient-funds, invalid-card-number, invalid-merchant, expired-card, incorrect-pin, transaction-not-allowed, suspected-fraud, amount-limit-exceeded, velocity-limit-exceeded, revocation-of-authorization, card-not-activated, issuer-not-available, could-not-route, cardholder-account-closed, unknown-issue, duplicate-transaction

feeProgram


        string

The program assigned by the card network that determines the interchange rate for the transfer.

initiatedOn


        string<date-time>

interchangeQualification


        string

deprecated

The program assigned by the card network that determines the interchange rate for the transfer.

settledOn


        string<date-time>

transactionSource


        string<enum>

Specifies the nature and initiator of a transaction.

Crucial for recurring and merchant-initiated transactions as per card scheme rules. Omit for customer-initiated e-commerce transactions.

Possible values: first-recurring, recurring, unscheduled

rtpDetails


        object

RTP specific details about the transaction.

Show child attributes

status


        string<enum>

required

Status of a transaction within the RTP lifecycle.

Possible values: initiated, completed, failed, accepted-without-posting

acceptedWithoutPostingOn


        string<date-time>

completedOn


        string<date-time>

failedOn


        string<date-time>

failureCode


        string<enum>

Status codes for RTP failures.

Possible values: processing-error, invalid-account, account-closed, account-blocked, invalid-field, transaction-not-supported, limit-exceeded, invalid-amount, customer-deceased, other

initiatedOn


        string<date-time>

networkResponseCode


        string

Response code returned by network on failure.

wallet


        object

Show child attributes

walletID


        string<uuid>

required

disputedAmount


        object

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

disputes


        array

Show child attributes

amount


        object

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

createdOn


        string<date-time>

disputeID


        string<uuid>

facilitatorFee


        object

Total or markup fee.

Show child attributes

markup


        integer<int64>

Markup facilitator fee in cents. Only either markup or markupDecimal can be set.

markupDecimal


        string

total


        integer<int64>

Total facilitator fee in cents. Only either total or totalDecimal can be set.

totalDecimal


        string

Same as total, but a decimal-formatted numerical string that represents up to 9 decimal place precision.

Only either total or totalDecimal can be set. Set this field if you expect the fee to be in fractions of a cent.

failureReason


        string<enum>

Reason for a transfer’s failure.

Possible values: source-payment-error, destination-payment-error, wallet-insufficient-funds, rejected-high-risk, processing-error

groupID


        string

metadata


        object

Free-form key-value pair list. Useful for storing information that is not captured elsewhere.

moovFee


        integer<int64>

Fees charged to your platform account for transfers.

moovFeeDecimal


        string

Same as moovFee, but a decimal-formatted numerical string that represents up to 9 decimal place precision.

moovFeeDetails


        object

Processing and pass-through costs that add up to the moovFee.

Show child attributes

moovProcessing


        string

required

Moov processing fee. String type represents dollars with up to 9 decimal place precision.

cardScheme


        string

Card scheme fees accrued during authorization and settlement. String type represents dollars with up to 9 decimal place precision.

discount


        string

Network discount fee for American Express. String type represents dollars with up to 9 decimal place precision.

interchange


        string

Network interchange fee for Visa, Mastercard, or Discover. String type represents dollars with up to 9 decimal place precision.

occurrenceID


        string

refundedAmount


        object

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

refunds


        array

Show child attributes

amount


        object

Show child attributes

currency


        string

required

A 3-letter ISO 4217 currency code.

value


        integer<int64>

required

Quantity in the smallest unit of the specified currency.

In USD this is cents, for example, $12.04 is 1204 and $0.99 is 99.

cardDetails


        object

Show child attributes

status


        string<enum>

required

Possible values: initiated, confirmed, settled, failed, completed

completedOn


        string<date-time>

confirmedOn


        string<date-time>

failedOn


        string<date-time>

failureCode


        string<enum>

initiatedOn


        string<date-time>

settledOn


        string<date-time>

createdOn


        string<date-time>

refundID


        string<uuid>

Identifier for the refund.

status


        string<enum>

Possible values: created, pending, completed, failed

updatedOn


        string<date-time>

scheduleID


        string

source


        object

Show child attributes

account


        object

required

Show child attributes

accountID


        string

required

displayName


        string

required

email


        string

required

paymentMethodID


        string

required

paymentMethodType


        string<enum>

required

The payment method type that represents a payment rail and directionality

achDetails


        object

ACH specific details about the transaction.

Show child attributes

status


        string<enum>

required

Status of a transaction within the ACH lifecycle.

Possible values: initiated, originated, corrected, returned, completed, canceled

traceNumber


        string

<=15 characters required

canceledOn


        string<date-time>

companyEntryDescription


        string

[4 to 10] characters

An optional override of the default NACHA company entry description for a transfer.

completedOn


        string<date-time>

correctedOn


        string<date-time>

correction


        object

Show child attributes

code


        string

description


        string

reason


        string

debitHoldPeriod


        string<enum>

An optional override of your default ACH hold period in banking days. The hold period must be longer than or equal to your default setting.

Possible values: no-hold, 1-day, 2-days

failedOn


        string<date-time>

initiatedOn


        string<date-time>

originatedOn


        string<date-time>

originatingCompanyName


        string

[4 to 16] characters

An optional override of the default NACHA company name for a transfer.

return


        object

Show child attributes

code


        string

description


        string

reason


        string

returnedOn


        string<date-time>

secCode


        string<enum>

Code used to identify the ACH authorization method.

Possible values: WEB, PPD, CCD, TEL

applePay


        object

Describes an Apple Pay token on a Moov account.

Show child attributes

brand


        string<enum>

required

The card brand.

Possible values: American Express, Discover, Mastercard, Visa, Unknown

cardDisplayName


        string

required

User-friendly name of the tokenized card returned by Apple.

It usually contains the brand and the last four digits of the underlying card. There is no standard format.

cardType


        string<enum>

required

The type of the card.

Possible values: debit, credit, prepaid, unknown

dynamicLastFour


        string

required

The last four digits of the Apple Pay token, which may differ from the tokenized card’s last four digits.

expiration


        object

required

The expiration date of the card or token.

Show child attributes

month


        string

2 characters required

year


        string

2 characters required

fingerprint


        string

<=100 characters required

issuerCountry


        string

Country where the underlying card was issued.

bankAccount


        object

A bank account as contained within a payment method.

Show child attributes

bankAccountID


        string<uuid>

required

bankAccountType


        string<enum>

required

The bank account type.

Possible values: checking, savings, general-ledger, loan

bankName


        string

required

fingerprint


        string

<=100 characters required

Once the bank account is linked, we don’t reveal the full bank account number.

The fingerprint acts as a way to identify whether two linked bank accounts are the same.

holderName


        string

required

holderType


        string<enum>

required

The type of holder on a funding source.

Possible values: individual, business

lastFourAccountNumber


        string

required

routingNumber


        string

required

status


        string<enum>

required

Possible values: new, verified, verificationFailed, pending, errored

updatedOn


        string<date-time>

required

card


        object

A card as contained within a payment method.

Show child attributes

billingAddress


        object

required

Show child attributes

postalCode


        string

<=10 characters required

addressLine1


        string

<=60 characters

addressLine2


        string

<=32 characters

city


        string

<=32 characters

country


        string

<=2 characters

stateOrProvince


        string

<=2 characters

bin


        string

[6 to 8] characters required

The first six to eight digits of the card number, which identifies the financial institution that issued the card.

brand


        string<enum>

required

The card brand.

Possible values: American Express, Discover, Mastercard, Visa, Unknown

cardID


        string<uuid>

required

ID of the card.

cardType


        string<enum>

required

The type of the card.

Possible values: debit, credit, prepaid, unknown

cardVerification


        object

required

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

Show child attributes

accountName


        object

required

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

Show child attributes

firstName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

fullName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

lastName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

middleName


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

addressLine1


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

cvv


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

postalCode


        string<enum>

required

Possible values: noMatch, match, notChecked, unavailable, partialMatch

domesticPullFromCard


        string<enum>

required

Indicates if the card supports domestic pull-from-card transfer.

Possible values: not-supported, supported, unknown

domesticPushToCard


        string<enum>

required

Indicates which level of domestic push-to-card transfer is supported by the card, if any.

Possible values: not-supported, standard, fast-funds, unknown

expiration


        object

required

The expiration date of the card or token.

Show child attributes

month


        string

2 characters required

year


        string

2 characters required

fingerprint


        string

<=100 characters required

issuer


        string

required

Financial institution that issued the card.

issuerCountry


        string

required

Country where the card was issued.

lastFourCardNumber


        string

4 characters required

Last four digits of the card number

cardAccountUpdater


        object

The results of the most recent card update request.

Show child attributes

updateType


        string<enum>

The results of the card update request.

Possible values: unspecified, account-closed, contact-cardholder, expiration-update, no-change, no-match, number-update

updatedOn


        string<date-time>

cardOnFile


        boolean

Indicates cardholder has authorized card to be stored for future payments.

holderName


        string

The name of the cardholder as it appears on the card.

merchantAccountID


        string<uuid>

cardDetails


        object

Card-specific details about the transaction.

Show child attributes

status


        string<enum>

required

Status of a transaction within the card payment lifecycle.

Possible values: initiated, confirmed, canceled, settled, failed, completed

canceledOn


        string<date-time>

completedOn


        string<date-time>

confirmedOn


        string<date-time>

dynamicDescriptor


        string

[4 to 22] characters

An optional override of the default card statement descriptor for a transfer. Accounts must be enabled by Moov to set this field.

failedOn


        string<date-time>

failureCode


        string<enum>

feeProgram


        string

The program assigned by the card network that determines the interchange rate for the transfer.

initiatedOn


        string<date-time>

interchangeQualification


        string

deprecated

The program assigned by the card network that determines the interchange rate for the transfer.

settledOn


        string<date-time>

transactionSource


        string<enum>

Specifies the nature and initiator of a transaction.

Crucial for recurring and merchant-initiated transactions as per card scheme rules. Omit for customer-initiated e-commerce transactions.

Possible values: first-recurring, recurring, unscheduled

terminalCard


        object

Describes payment card details captured with tap or in-person payment.

Show child attributes

bin


        string

[6 to 8] characters

brand


        string<enum>

The card brand.

Possible values: American Express, Discover, Mastercard, Visa, Unknown

cardType


        string<enum>

The type of the card.

Possible values: debit, credit, prepaid, unknown

entryMode


        string<enum>

How the card information was entered into the point of sale terminal.

Possible values: contactless

expiration


        object

The expiration date of the card or token.

Show child attributes

month


        string

2 characters required

year


        string

2 characters required

fingerprint


        string

<=100 characters

holderName


        string

The name of the cardholder as it appears on the card.

issuer


        string

Financial institution that issued the card.

issuerCountry


        string

Country where the card was issued.

lastFourCardNumber


        string

4 characters

Last four digits of the card number

transferID


        string<uuid>

UUID present only if the transfer is part of a transfer group.

wallet


        object

Show child attributes

walletID


        string<uuid>

required

status


        string<enum>

Status of a transfer.

Possible values: created, pending, completed, failed, reversed, queued, canceled

sweepID


        string

transferID


        string<uuid>

createdOn


        string<date-time>

transferID


        string<uuid>

cURL Go

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


curl -X POST "https://api.moov.io/accounts/{accountID}/transfers" \
  -H "Authorization: Bearer {token}" \
  -H "X-Idempotency-Key: UUID" \
  -H "X-Wait-For: rail-response" \
  --data-raw '{
    "amount": {
      "value": 100,
      "currency": "USD"
    },
    "destination": {
      "paymentMethodID": "UUID"
    },
    "source": {
      "paymentMethodID": "UUID"
    },
    "description": "Optional transaction description."
  }'\

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


mc, _ := moov.NewClient()

var accountID string

mc.CreateTransfer(ctx, accountID, moov.CreateTransfer{
  Amount: moov.Amount{
    Currency: "USD",
    Value:    100, // $1.00
  },
  Destination: moov.CreateTransfer_Destination{
    PaymentMethodID: "UUID",
  },
  Source: moov.CreateTransfer_Source{
    PaymentMethodID: "UUID",
  },
  Description: "Optional transaction description.",
})

200 201 202 400 404 409 422 429 500 504

The request completed successfully.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

A transfer was successfully created but an error occurred while generating the synchronous response. The asynchronous response object will be returned.

{
  "createdOn": "2019-08-24T14:15:22Z",
  "transferID": "e23de6dd-5168-4e1d-894d-807fa691dc80"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

A transfer was successfully created but a timeout occurred while waiting for a synchronous response. Rail-specific details may be missing from the response object.

Details of a Transfer.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The server could not understand the request due to invalid syntax.

{
  "error": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The requested resource was not found.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Attempted to create a transfer using a duplicate X-Idempotency-Key header.

Details of a Transfer.

{
  "amount": {
    "currency": "USD",
    "value": 32945
  },
  "createdOn": "2025-01-21T21:32:16Z",
  "description": "Transfer from card to wallet",
  "destination": {
    "account": {
      "accountID": "34233b72-780c-4a0d-8b08-cbbe23k878f8",
      "displayName": "Whole Body Fitness",
      "email": "john@wholebodyfitness.io"
    },
    "paymentMethodID": "3f9969cf-a1f3-4d83-8ddc-229a506651cf",
    "paymentMethodType": "moov-wallet",
    "wallet": {
      "walletID": "744b2e78-8cc8-4a6a-af42-611e3b844503"
    }
  },
  "source": {
    "account": {
      "accountID": "7e4b26c2-b399-49ef-8390-50e1ea44d550",
      "displayName": "Jules Jackson",
      "email": "jules@julesjackson.com"
    },
    "card": {
      "billingAddress": {
        "postalCode": "80301"
      },
      "bin": "400020",
      "brand": "Visa",
      "cardAccountUpdater": {},
      "cardID": "aefd5563-93c6-413c-875e-1bd0ebfc116d",
      "cardType": "credit",
      "cardVerification": {
        "accountName": {
          "firstName": "unavailable",
          "fullName": "unavailable",
          "lastName": "unavailable",
          "middleName": "unavailable"
        },
        "addressLine1": "unavailable",
        "cvv": "unavailable",
        "postalCode": "unavailable"
      },
      "domesticPullFromCard": "supported",
      "domesticPushToCard": "standard",
      "expiration": {
        "month": "01",
        "year": "28"
      },
      "fingerprint": "2f5d782ceef1c3bd31ed5...",
      "holderName": "Jules Jackson",
      "issuer": "Moov Visa Sandbox",
      "issuerCountry": "US",
      "lastFourCardNumber": "2000"
    },
    "cardDetails": {
      "confirmedOn": "2025-01-21T21:32:16.799681237Z",
      "dynamicDescriptor": "WhlBdy *Yoga 11-12",
      "status": "confirmed"
    },
    "paymentMethodID": "9506dbf6-4208-44c3-ad8a-e4431660e1f2",
    "paymentMethodType": "card-payment"
  },
  "status": "pending",
  "transferID": "d835gf30-4b19-4850-a9b2-c0624c41ecb3"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request was well-formed, but the contents failed validation. Check the request for missing or invalid fields.

{
  "FacilitatorFee.MarkupDecimal": "string",
  "FacilitatorFee.TotalDecimal": "string",
  "Transfer": "string",
  "amount": "string",
  "description": "string",
  "destinationPaymentMethodID": "string",
  "error": "string",
  "metadata": "string",
  "source": "string",
  "sourcePaymentMethodID": "string"
}

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Request was refused due to rate limiting.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed due to an unexpected error.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

The request failed because a downstream service failed to respond.

x-request-id


      string
      <uuid>

required

A unique identifier used to trace requests.

Create a transfer

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers

Response headers