DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

10 minute read

October 2, 2019

Account Holder Funding Sources

Use the /fundingsources/ach and /fundingsources/paymentcard endpoints to create account holder funding sources. A funding source enables access to funds outside of the Marqeta platform.

You must create the user or business resource that represents the account holder before creating the funding source.

If an account holder owns only one funding source, that funding source is used by default. If an account holder has more than one funding source and none is configured as the default, then you must explicitly identify which funding source to use (by way of the funding source token).

Different types of funding sources require different verification procedures. For example, payment cards are validated through a payment gateway, whereas checking accounts (ACH) are validated using small deposits.

For more information on users and businesses, see About Account Holders.

Create ACH source
Copy section link

Action: POST
Endpoint: /fundingsources/ach

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create an ACH funding source. You must create the user or business before creating the funding source. Specify the owner of the funding source by passing a user or business token.

When adding an ACH funding source, a small amount is deposited in the bank account as a test. The test deposit should be reflected in the account after two to three business days. You must then make an API call to verify the deposit amount in order to activate (enable) the ACH account. See the "Verify or Update ACH Funding Source" section on this page for more information.

The response body returns details about the account, including the verification status. Possible ACH verification status values include VERIFICATION_PENDING, ACH_VERIFIED, and ACH_FAILED.

Body field details
Copy section link

Fields Description

token

string, optional

The unique identifier of the funding source. If you do not include a token, the system will generate one automatically. This token is necessary for use in other calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

user_token OR business_token

string, required

Specifies the owner of the funding source.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

account_number

string, required

The ACH account number.

Allowable Values:

36 char max

name_on_account

string, required

The name on the ACH account.

Allowable Values:

40 char max

routing_number

string, required

The routing number for the ACH account.

Allowable Values:

9 digits

account_type

string, required

The type of account.

Allowable Values:

checking, savings, corporate

is_default_account

boolean, optional

If there are multiple funding sources, this field specifies which source is used by default in funding calls. If there is only one funding source, the system ignores this field and always uses that source. If you do not specify this field upon creation, the system sets it to false.

Allowable Values:

true, false

Default value: false

verification_override

boolean, optional

Allows the ACH funding source to be used regardless of its verification status.

Allowable Values:

true, false

Default value: false

verification_notes

string, optional

Free-form text field for holding notes about verification. This field is returned only if verification_override=true.

Allowable Values:

255 char max

Sample request body
Copy section link

{
  "token": "bigbird_fundingsource_token05",
  "user_token": "bigbird_token",
  "routing_number": "121000358",
  "name_on_account": "Big Bird",
  "is_default_account": false,
  "account_number": "987654321",
  "account_type": "savings",
  "verification_notes": "These are my verification notes.",
  "verification_override": true
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "bigbird_fundingsource_token05",
  "created_time": "2016-04-26T18:46:06Z",
  "last_modified_time": "2016-04-26T18:46:06Z",
  "account_suffix": "4321",
  "verification_status": "ACH_VERIFIED",
  "account_type": "savings",
  "name_on_account": "Big Bird",
  "active": true,
  "date_sent_for_verification": "2016-04-26T18:46:05Z",
  "user_token": "bigbird_token",
  "is_default_account": false,
  "date_verified": "2016-04-26T18:46:05Z",
  "verification_override": true,
  "verification_notes": "These are my verification notes."
}

Is this helpful?

Retrieve ACH source
Copy section link

Action: GET
Endpoint: /fundingsources/ach/{funding_source_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve a specific ACH funding source.

The response body returns details about the account, including the verification status. Possible ACH verification status values are: VERIFICATION_PENDING, ACH_VERIFIED, and ACH_FAILED.

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Identifies the ACH funding source to retrieve.

Allowable Values:

Existing ACH funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Sample response body
Copy section link

{
  "token": "bigbird_fundingsource_token05",
  "created_time": "2016-04-26T18:46:06Z",
  "last_modified_time": "2016-04-26T18:46:06Z",
  "account_suffix": "4321",
  "verification_status": "ACH_VERIFIED",
  "account_type": "savings",
  "name_on_account": "Big Bird",
  "active": true,
  "date_sent_for_verification": "2016-04-26T18:46:05Z",
  "user_token": "bigbird_token",
  "is_default_account": false,
  "date_verified": "2016-04-26T18:46:05Z",
  "verification_override": true,
  "verification_notes": "These are my verification notes."
}

Is this helpful?

Retrieve ACH verification amounts
Copy section link

Action: GET
Endpoint: /fundingsources/ach/{funding_source_token}/verificationamounts

Develop Now!

Sign in and use your sandbox to access the API Explorer

In your sandbox environment, retrieve the amounts used to verify the association with your ACH account.

Use this endpoint for testing purposes only. In production, verification amounts can be retrieved from the bank statement of the account holder.

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Identifies the ACH funding source for which you want to retrieve verification deposit amounts.

Allowable Values:

Existing ACH funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Sample response body
Copy section link

{
  "token": "bigbird_ach_token",
  "verify_amount1": 0.43,
  "verify_amount2": 0.11
}

Is this helpful?

Verify or update ACH source
Copy section link

Action: PUT
Endpoint: /fundingsources/ach/{funding_source_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Verify or update an ACH funding source.

If you are verifying the ACH source, include the verification amounts in the body of the request. If you are updating the ACH source, include the active field instead. The active field is the only field you can update.

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Identifies the ACH funding source to verify.

Allowable Values:

Existing ACH funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Body field details
Copy section link

Fields Description

active

boolean, optional

Indicates whether the ACH funding source is active.

Allowable Values:

true, false

verify_amount1

decimal, optional

Verification amount.

Allowable Values:

0.00

verify_amount2

decimal, optional

Verification amount.

Allowable Values:

0.00

Sample request body
Copy section link

{
"active": "false",
"verify_amount1": 0.43,
"verify_amount2": 0.11
}

Is this helpful?

Sample response body
Copy section link

{
"token": "bigbird_ach_token",
"account_suffix": "4321",
"verification_status": "ACH_VERIFIED",
"account_type": "savings",
"name_on_account": "Big Bird",
"active": false,
"date_sent_for_verification": "2015-11-16T23:27:58Z",
"user_token": "bigbird_token",
"is_default_account": false,
"date_verified": "2015-11-17T03:57:10Z"
}

Is this helpful?

Create payment card source
Copy section link

Action: POST
Endpoint: /fundingsources/paymentcard

Develop Now!

Sign in and use your sandbox to access the API Explorer

Create a payment card funding source.

When creating a payment card funding source, you must pass a user or business token to specify the owner of the funding source. You must create the user/business before creating the funding source.

As a result of this POST operation, additional fields are returned in the response object. The Marqeta platform recognizes the card type from the account number and returns the account_type (for example VISA), the account_suffix (last 4 digits), and sets the active field to true.

Note that the Marqeta platform does not retain the credit card number (PAN). Rather, a tokenized representation is stored for security purposes.

Body field details
Copy section link

Fields Description

token

string, optional

The unique identifier of the funding account. If you do not include a token, the system will generate one automatically. As this token is necessary for use in other calls, we recommend that you define a simple and easy to remember string rather than letting the system generate a token for you. This value cannot be updated.

Allowable Values:

36 char max

postal_code

string, optional

Postal code of the account holder (user/business).

Allowable Values:

10 char max

account_number

string, required

Payment card account number.

Allowable Values:

16 digit number

exp_date

string, required

Payment card expiration date.

Allowable Values:

mmyy

user_token

OR

business_token

string, required

Specifies the owner of the funding source.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

cvv_number

string, required

Payment card CVV2 number.

Allowable Values:

3-4 characters

is_default_account

boolean, optional

If there are multiple funding sources, this field specifies which source is used by default in funding calls. If there is only one funding source, the system ignores this field and always uses that source. If you do not specify this field upon creation, the system sets it to false.

Allowable Values:

true, false

Default value: false

Sample request body
Copy section link

{
  "token": "paycard_fs4_01",
  "postal_code": "94608",
  "user_token": "6745de06-1f88-44b5-8019-42250386c63c",
  "is_default_account": true,
  "exp_date": "0120",
  "account_number": "6559906559906557",
  "cvv_number": "123"
}

Is this helpful?

Sample response body
Copy section link

{
  "type": "paymentcard",
  "token": "paycard_fs4_01",
  "created_time": "2016-04-26T21:52:17Z",
  "last_modified_time": "2016-04-26T21:52:17Z",
  "account_suffix": "6557",
  "account_type": "DISCOVER",
  "active": true,
  "is_default_account": true,
  "exp_date": "0120",
  "user_token": "6745de06-1f88-44b5-8019-42250386c63c"
}

Is this helpful?

Retrieve payment card source
Copy section link

Action: GET
Endpoint: /fundingsources/paymentcard/{funding_source_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieve a specific payment card funding source.

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Identifies the payment card funding source you want to retrieve.

Allowable Values:

Existing payment card funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Sample response body
Copy section link

{
  "type": "paymentcard",
  "token": "paycard_fs4_01",
  "created_time": "2016-04-26T21:52:17Z",
  "last_modified_time": "2016-04-26T21:52:17Z",
  "account_suffix": "6557",
  "account_type": "DISCOVER",
  "active": true,
  "is_default_account": true,
  "exp_date": "0120",
  "user_token": "6745de06-1f88-44b5-8019-42250386c63c"
}

Is this helpful?

Update payment card source
Copy section link

Action: PUT
Endpoint: /fundingsources/paymentcard/{funding_source_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Update a payment card funding source. Only the values of parameters in the request are modified; all others are left unchanged.

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Identifies the payment card funding source you want to retrieve.

Allowable Values:

Existing payment card funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Body field details
Copy section link

Fields Description

active

boolean, optional

Indicates whether the card funding source is active.

Allowable Values:

true, false

Default value: true

exp_date

string, optional

The expiration date for the payment card.

Allowable Values:

mmyy

is_default_account

boolean, optional

If there are multiple funding sources, this field specifies which source is used by default in funding calls. If there is only one funding source, the system ignores this field and always uses that source.

Allowable Values:

true, false

Default value: false

Sample request body
Copy section link

{
  "is_default_account": false
}

Is this helpful?

Sample response body
Copy section link

{
  "type": "paymentcard",
  "token": "paycard_fs4_01",
  "created_time": "2016-04-26T21:52:17Z",
  "last_modified_time": "2016-04-26T22:13:42Z",
  "account_suffix": "6557",
  "account_type": "DISCOVER",
  "active": true,
  "is_default_account": true,
  "exp_date": "0120",
  "user_token": "6745de06-1f88-44b5-8019-42250386c63c"
}

Is this helpful?

List sources for user
Copy section link

Action: GET
Endpoint: /fundingsources/user/{user_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

List funding sources associated with a specific user.

This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

user_token

string, required

Identifies the owner of the funding sources you want to list.

Allowable Values:

Existing user token.

Send a GET request to /users to retrieve existing user tokens.

Query parameters
Copy section link

Fields Description

type

string, optional

Type of funding source to return: ACH or payment card. Leave unspecified to return both types.

Allowable Values:

paymentcard, ach

Default value: empty (all types)

Sample response body
Copy section link

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "type": "paymentcard",
      "token": "bigbird_paymentcard_token",
      "account_suffix": "4113",
      "account_type": "VISA",
      "active": true,
      "is_default_account": true,
      "exp_date": "1217",
      "user_token": "bigbird_token"
    },
    {
      "type": "ach",
      "token": "bigbird_ach_token",
      "account_suffix": "4321",
      "account_type": "savings",
      "active": false,
      "is_default_account": false,
      "verification_status": "ACH_VERIFIED",
      "user_token": "bigbird_token",
      "name_on_account": "Big Bird",
      "date_sent_for_verification": "2015-11-16T23:27:58Z"
    }

Is this helpful?

List sources for business
Copy section link

Action: GET
Endpoint: /fundingsources/business/{business_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

List funding sources associated with a specific business.

This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

business_token

string, required

Identifies the business whose funding sources you want to retrieve.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve existing business tokens.

Query parameters
Copy section link

Fields Description

type

string, optional

Type of funding source to return: ACH or payment card. Leave unspecified to return both types.

Allowable Values:

paymentcard, ach

Default value: empty (all types)

Sample response body
Copy section link

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "type": "paymentcard",
      "token": "my_paymentcard_funding_source_01",
      "created_time": "2016-10-26T21:26:13Z",
      "last_modified_time": "2016-10-26T21:26:13Z",
      "account_suffix": "4113",
      "account_type": "VISA",
      "active": true,
      "is_default_account": true,
      "exp_date": "1220",
      "user_token": "my_business_01"
    }
  ]
}

Is this helpful?

Set default source
Copy section link

Action: PUT
Endpoint: /fundingsources/{funding_source_token}/default

Develop Now!

Sign in and use your sandbox to access the API Explorer

Configure either an ACH funding source or a payment card funding source as the default funding source.

A default funding source is used when you omit the funding_source_token field from funding requests, such as a POST request to /gpaorders. Note that the first funding source you create is automatically set as the default (is_default_source=true).

URL path parameters
Copy section link

Fields Description

funding_source_token

string, required

Specifies the funding source to use by default.

You can set the default only to an ACH or payment card funding source.

Allowable Values:

Existing ACH or payment card funding source token.

Send a GET request to /fundingsources/user/{user_token} to retrieve existing funding source tokens for a user or to /fundingsources/business/{business_token} to retrieve existing funding source tokens for a business.

Sample response body
Copy section link

{
  "type": "bankaccount",
  "token": "bigbird_ach_token",
  "account_suffix": "4321",
  "account_type": "savings",
  "active": true,
  "is_default_account": true,
  "user_token": "bigbird_token"
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.