Create ACH Source

Action: POST
Endpoint: /fundingsources/ach

To create an ACH funding source, send a POST request to the /fundingsources/ach endpoint and include the source details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

When creating a 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.

When adding an ACH funding source, a small deposit is made to the bank account that should be evident after two to three business days. You must then make an API call to verify the deposit amounts 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 are: VERIFICATION_PENDING, ACH_VERIFIED, ACH_FAILED.

Body Field Details

Name Type Required? Description Allowable Values
token string No 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. 36 char max
user_token

OR

business_token
string Yes Specifies the owner of the funding source. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
account_number string Yes The ACH account number. 36 char max
name_on_account string Yes The name on the ACH account. 40 char max
routing_number string Yes The routing number for the ACH account. 9 digits
account_type string Yes The type of account. checking | savings | corporate
is_default_account boolean No 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. true | false; Default: false
verification_override boolean No Allows the ACH funding source to be used regardless of its verification status. true | false; Default: false
verification_notes string No Free-form text field for holding notes about verification. This field is returned only if verification_override=true. 255 char max

Sample Request Body

{
"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
}

Sample Response Body

{
"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."
}


Retrieve ACH Source

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

To retrieve a specific ACH funding source, issue a GET request to the /fundingsources/ach/{funding_source_token} endpoint. Include the ACH funding_source_token path parameter to specify the funding source to return.

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

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Identifies the ACH funding source to retrieve. Existing ACH funding source token.

Issue a GET 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

{
"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."
}


Retrieve ACH Verification Amounts

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

To retrieve the amounts used to verify the registration of an ACH account, issue a GET request to the /fundingsources/ach/{funding_source_token}/verificationamounts endpoint. Include the funding_source_token path parameter to specify the funding source account. Use this call for testing purposes only. In production, verification amounts can be retrieved from the bank statement of the account holder.

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Identifies the ACH funding source for which you want to retrieve verification deposit amounts. Existing ACH funding source token.

Issue a GET 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

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


Verify or Update ACH Source

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

To either verify or update an ACH funding source, send a PUT request to the /fundingsources/ach/{funding_source_token} endpoint. Include the funding_source_token path parameter to indicate the ACH funding source to verify or update. If you are verifying the ACH source, include the verification amounts in JSON format in the body of the request. If you are updating the ACH source, include the active field instead. The active field is the only updateable field.

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Identifies the ACH funding source to verify. Existing ACH funding source token.

Issue a GET 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

Name Type Required? Description Allowable Values
active boolean No Indicates whether the ACH funding source is active. true | false
verify_amount1 decimal No Verification amount. 0.00
verify_amount2 decimal No Verification amount. 0.00

Sample Request Body

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

Sample Response Body

{
"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"
}


Create Card Source

Action: POST
Endpoint: /fundingsources/paymentcard

To create a payment card funding source, issue a POST request to the fundingsources/paymentcard endpoint and include the source details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

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 on the response object. The system 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 Marqeta does not retain the credit card number (PAN) in its system. Rather, a tokenized representation is stored for security purposes.

Body Field Details

Name Type Required? Description Allowable Values
token string No 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. 36 char max
zipCode string No Zip code of the account holder (user/business). 10 char max
account_number string Yes Payment card account number. 16 digit number
exp_date string Yes Payment card expiration date. mmyy
user_token

OR

business_token
string Yes Specifies the owner of the funding source. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
cvv_number string Yes Payment card CVV number. 3-4 characters
is_default_account boolean No 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. true | false; Default: false

Sample Request Body

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

Sample Response Body

{
"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"
}


Retrieve Card Source

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

To retrieve a specific payment card funding source, issue a GET request to the /fundingsources/paymentcard/{funding_source_token} endpoint. Include the funding source funding_source_token path parameter to specify the funding source to return.

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Identifies the payment card funding source you want to retrieve. Existing payment card funding source token.

Issue a GET 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

{
"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"
}


Update Card Source

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

To update a payment card funding source, send a PUT request to the /fundingsources/paymentcard/{funding_source_token} endpoint. Include the funding source funding_source_token path parameter to indicate the funding source to update. Include the modified detail parameters in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Identifies the payment card funding source you want to retrieve. Existing payment card funding source token.

Issue a GET 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

Name Type Required? Description Allowable Values
active boolean No Indicates whether the card funding source is active. true | false; Default: true
exp_date string No The expiration date for the payment card. mmyy
is_default_account boolean No 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. true | false; Default: false

Sample Request Body

{
"is_default_account": false
}

Sample Response Body

{
"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"
}


Create Program Source

Action: POST
Endpoint: /fundingsources/program

To create a program funding source, send a POST request to the /fundingsources/program endpoint and include the source details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

Body Field Details

Name Type Required? Description Allowable Values
active boolean No Indicates whether the program funding source is active. true | false; Default: true
token string No The unique identifier of the funding source. 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. 36 char max
name string Yes The name of the funding program. 40 char max

Sample Request Body

{
"token": "my_programfundingsource_token",
"name": "my_programfundingsource_name",
"active": true
}

Sample Response Body

{
"name": "my_programfundingsource_name",
"active": true,
"token": "my_programfundingsource_token",
"account": "12.003.001.000147",
"created_time": "2015-11-25T20:46:04Z",
"last_modified_time": "2015-11-25T20:46:04Z"
}


Retrieve Program Source

Action: GET
Endpoint: /fundingsources/program/{token}

To retrieve a specific program funding source, issue a GET request to the /fundingsources/program/{token} endpoint. Include the program source token path parameter to specify the program source to return.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the program funding source you want to retrieve. Existing program funding source token.

Issue a GET 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

{
"name": "my_programfundingsource_name",
"active": true,
"token": "my_programfundingsource_token",
"account": "12.003.001.000147",
"created_time": "2015-11-25T20:46:04Z",
"last_modified_time": "2015-11-25T20:46:04Z"
}


Update Program Source

Action: PUT
Endpoint: /fundingsources/program/{token}

To update a program funding source, send a PUT request to the /fundingsources/program/{token} endpoint. Include the program source token as a path parameter to indicate the funding source to update. Include the modified detail parameters in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the program funding source to update. Existing program funding source token.

Issue a GET 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

Name Type Required? Description Allowable Values
name string No The name of the program funding source. 40 char max
active boolean No Indicates whether the program funding source is active. true | false

Sample Request Body

{
"name": "your_programfundingsource_name",
"active": false
}

Sample Response Body

{
"name": "your_programfundingsource_name",
"active": false,
"token": "my_programfundingsource_token",
"account": "12.003.001.000147",
"created_time": "2015-11-25T20:46:04Z",
"last_modified_time": "2015-11-25T21:33:59Z"
}


Create Program Gateway Source

Action: POST
Endpoint: /fundingsources/programgateway

A program gateway funding source is a transaction relay that, when configured, allows a partner to approve or decline transactions in real time.

To create a program gateway funding source, send a POST request to the /fundingsources/programgateway endpoint and include the source details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. If you do not include a token value, one is generated automatically.

Body Field Details

Name Type Required? Description Allowable Values                    
token string No The unique identifier of the funding source. 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. 36 char max
url string Yes The URL of the partner's gateway, to which POST messages are submitted by Marqeta. 250 char max. Must be HTTPS. Empty string not allowed.
basic_auth_username string Yes Username for partner environment authentication. 50 char max.
basic_auth_password string Yes Password for partner environment authentication.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
name string Yes The name of the program gateway funding source. 50 char max
timeout_millis integer No Total timeout in milliseconds for gateway processing. Default 3000
active boolean No Indicates whether the program gateway funding source is active. true | false;

Default: true

Sample Request Body

{
"token": "my_pgfs_token",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password",
"url": "https://my_secure_domain.com/my_gateway",
"name": "my_pgfs_name"
}

Sample Response Body

{
"name": "my_pgfs_name",
"active": true,
"token": "my_pgfs_token",
"account": "12.003.001.000155",
"url": "https://my_secure_domain.com/my_gateway",
"created_time": "2015-11-30T20:00:51Z",
"last_modified_time": "2015-11-30T20:00:51Z",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password",
"timeout_millis": 3000
}


Update Program Gateway Source

Action: PUT
Endpoint: /fundingsources/programgateway/{token}

To update a program gateway funding source, send a PUT request to the /fundingsources/programgateway/{token} endpoint. Include the funding source token path parameter to indicate the funding source to update. Include the modified detail parameters in JSON format in the body of the request. Only values of parameters in the request are modified; all others are left unchanged.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the program gateway funding source to retrieve. Existing program gateway funding source token.

Issue a GET 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

Name Type Required? Description Allowable Values
url string Yes The URL of the partner's gateway, to which POST messages are submitted by Marqeta. 250 char max. Must be HTTPS. Empty string not allowed.
timeout_millis integer No Total timeout in milliseconds for gateway processing. Default 3000
basic_auth_username string Yes Username for partner environment authentication. 50 char max.
basic_auth_password string Yes Password for partner environment authentication.
  • 20-50 characters
  • must contain at least 1 numeral
  • must contain at least 1 lower-case letter
  • must contain at least 1 upper-case letter
  • must contain at least 1 of these symbols: @#$%!^&*()\_+~`-=[]{}|;:'",./<>?
active boolean No Indicates whether the program gateway funding source is active. true | false;

Default: true
name string No The name of the program gateway funding source. 50 char max

Sample Request Body

{
"active": false
}

Sample Response Body

{
"name": "my_pgfs_name",
"active": false,
"token": "my_pgfs_token",
"account": "12.003.001.000155",
"url": "https://my_secure_domain.com/my_gateway",
"created_time": "2015-11-30T20:00:51Z",
"last_modified_time": "2015-11-30T23:39:10Z",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password",
"timeout_millis": 3000
}


Retrieve Program Gateway Source

Action: GET
Endpoint: /fundingsources/programgateway/{token}

To retrieve a specific program gateway funding source, issue a GET request to the /fundingsources/programgateway/{token} endpoint. Include the token path parameter to specify the funding source to return.

URL Path Parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the gateway program funding source to retrieve. Existing program gateway funding source token.

Issue a GET 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

{
"name": "my_pgfs_name",
"active": false,
"token": "my_pgfs_token",
"account": "12.003.001.000155",
"url": "https://my_secure_domain.com/my_gateway",
"created_time": "2015-11-30T20:00:51Z",
"last_modified_time": "2015-11-30T23:39:10Z",
"basic_auth_username": "my_username",
"basic_auth_password": "My_20-character-min_password",
"timeout_millis": 3000
}


List Sources for User

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

To list funding sources owned by a specific user, issue a GET request to the /fundingsources/user/{user_token} endpoint. Include the user_token path parameter to specify the owner of the funding sources. You can optionally specify the type of funding sources to list as a query parameter.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
user_token string Yes Identifies the owner of the funding sources you want to list. Existing user token.

Issue a GET to /users to retrieve existing user tokens.

Query Parameters

Name Type Required? Description Allowable Values
type string No Type of funding source to return: ACH or payment card. Leave blank to return both types. paymentcard | ach;

Default: blank (all types)

Sample Response Body

{
"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"
}


List Sources for Business

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

To list funding sources associated with a specific business, issue a GET request to the /fundingsources/business/{business_token} endpoint. Include the business_token path parameter to specify the business whose funding sources you want to return. You can optionally specify the type of funding sources to return as a query parameter.

This endpoint supports field filtering.

URL Path Parameters

Name Type Required? Description Allowable Values
business_token string Yes Identifies the business whose funding sources you want to retrieve. Existing business token.

Issue a GET to /businesses to retrieve existing business tokens.

Query Parameters

Name Type Required? Description Allowable Values
type string No Type of funding source to return: ACH or payment card. Leave blank to return both types. paymentcard | ach;

Default: blank (all types)

Sample Response Body

{
"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"
}
]
}


Set Default Source

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

To configure either an ACH funding source or a payment card funding source as the default funding source, send a PUT request to the /fundingsources/{funding_source_token}/default endpoint. Include a funding_source_token path parameter to indicate the funding source to make the default.

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

URL Path Parameters

Name Type Required? Description Allowable Values
funding_source_token string Yes Specifies the funding source to use by default.

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

Issue a GET 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

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