Transfers
A transfer represents a movement of funds entirely within the Marqeta platform. Marqeta supports three types of transfers:
-
Fee transfers
-
Peer transfers
-
Program transfers
A peer transfer moves funds from the general purpose account (GPA) of one account holder (a user or business) to that of another. By default, every account holder has a GPA. Both the sender and recipient account holder must be active.
A fee transfer moves funds from the GPA of an account holder to your program’s fee account. The transfer amount is determined by the fee that is assessed. The request returns an error if the GPA has insufficient funds to cover the fee (this behavior contrasts with assessing a fee using the
A program transfer moves funds from an account holder’s GPA to a program funding source. As opposed to a fee transfer, the transfer amount is specified by the transfer itself and is therefore a dynamically settable value. An auto reload is triggered if the GPA has insufficient funds to cover the transfer amount and auto reload is enabled.
Create fee transfer
Copy section link
Action:
Endpoint:
Use this endpoint to create a fee transfer. Add the fee transfer details to the body of the request in JSON format.
You must pass in either user_token or business_token to associate a user or business with the fee transfer.
This is an all-or-nothing operation. When more than one fee is assessed, all fees must be assessed, or no fees are assessed.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the fee transfer. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API 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
|
Specifies the account holder to which the fee applies. Pass either user_token or business_token, not both. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
tags
string
|
Metadata about the transfer. Allowable Values: 255 char max |
fees
array of fee_model
|
Contains attributes that define characteristics of one or more fees. Allowable Values: An array of existing fee_model objects.
|
The fee_model object
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the fee. Allowable Values: Existing fee token |
memo
string
|
Additional text that describes the fee transfer. Allowable Values: 99 char max |
tags
string
|
Tags used by the fee_model object
Allowable Values: 255 char max |
Retrieve fee transfer
Copy section link
Action:
Endpoint:
Use this endpoint to retrieve a specific fee transfer. Include the fee transfer
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the fee transfer to retrieve. Allowable Values: Existing fee transfer token |
Create peer transfer
Copy section link
Action:
Endpoint:
Use this endpoint to request a peer transfer (movement of funds from the GPA of one account holder to that of another). Add the source details to the body of the request in JSON format.
When creating a peer transfer request, you must pass in both a token to identify the fee sender (either sender_user_token or sender_business_token) and a token to identify the fee recipient (either recipient_user_token or recipient_business_token). The sender and recipient objects must already exist.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the transfer request. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API 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 |
sender_user_token OR sender_business_token
string
|
Specifies the account holder that sends funds. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
recipient_user_token OR recipient_business_token
string
|
Specifies the account holder that receives funds. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
currency_code
string
|
The three-character ISO 4217 currency code. Allowable Values: The three-character ISO 4217 currency code. "USD" currently supported. |
amount
decimal
|
The amount of the transfer. Allowable Values: Format: 0.00 |
tags
string
|
Metadata about the transfer. Allowable Values: 255 char max |
memo
string
|
Additional descriptive text. Allowable Values: 99 char max |
Retrieve peer transfer
Copy section link
Action:
Endpoint:
Use this endpoint to retrieve a peer transfer request. Include the peer transfer
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the peer transfer to retrieve. Allowable Values: Existing peer transfer token. Send a GET request to /peertransfers/user/{user_or_business_token} to retrieve all peer transfer tokens for a particular account holder.
|
List sent peer transfers
Copy section link
Action:
Endpoint:
Use this endpoint to list peer transfers sent by an account holder. Include a user or business token as a path parameter to identify the sender.
This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
user_or_business_token
string
|
Identifies the sender of the peer transfers you want to list. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
List received peer transfers
Copy section link
Action:
Endpoint:
Use this endpoint to list peer transfers sent by an account holder. Include a user or business token as a path parameter to identify the recipient.
This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
user_or_business_token
string
|
Identifies the recipient of the peer transfers you want to list. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
List peer transfers for account holder
Copy section link
Action:
Endpoint:
Use this endpoint to list peer transfers sent or received by a particular account holder. Include a user or business token as a path parameter to identify the account holder whose transfers you want to list.
This endpoint supports field filtering and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
user_or_business_token
string
|
Identifies the account holder whose peer transfers you want to list. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
Create program transfer
Copy section link
Action:
Endpoint:
Use this endpoint to create a program transfer. Add the program transfer details to the body of the request in JSON format.
Include either user_token or business_token in the message body to specify the account holder whose GPA will be debited by the program transfer. The user or business must already exist.
A program transfer is an all-or-nothing operation. If the GPA has insufficient funds to cover both the
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the program transfer. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API 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 |
type_token
string
|
Specifies the program transfer type. Allowable Values: Token of existing program transfer type. Send a GET request to /programtransfers/types to retrieve program transfer type tokens.
|
user_token OR business_token
string
|
Specifies the account holder whose GPA will be debited by the program transfer. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
amount
decimal
|
Amount of program transfer. Allowable Values: Format: 0.00 |
currency_code
string
|
The three-character ISO 4217 currency code. Allowable Values: The three-character ISO 4217 currency code. Default value: USD
|
tags
string
|
Comma-delimited list of tags describing the program transfer. Allowable Values: 255 char max |
memo
string
|
Memo or note describing the program transfer. Allowable Values: 255 char max |
fees
array of fee_model
|
Used to add one or more fees to the program transfer. In the case of a program transfer, fees are debited from the GPA of the account holder. Allowable Values: An array of fee_model objects.
|
The fee_model object
Copy section link
| Fields | Description |
|---|---|
token
string
|
Specifies the fee to add. Allowable Values: Existing fee token |
memo
string
|
Memo or note describing the fee. Allowable Values: 99 char max |
tags
string
|
Comma-delimited list of tags describing the fee. Allowable Values: 255 char max |
Retrieve program transfer
Copy section link
Action:
Endpoint:
Use this endpoint to retrieve a specific program transfer. Include the program transfer
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the program transfer to retrieve. Allowable Values: Existing program transfer token. Send a GET request to /programtransfers to retrieve program transfer tokens.
|
List program transfers
Copy section link
Action:
Endpoint:
Use this endpoint to list all program transfers.
To narrow your result set to program transfers of a particular type or that are associated with a particular account holder, include the appropriate parameters from the following Query Parameters table. This endpoint also supports field filtering, pagination, and sorting.
Query parameters
Copy section link
| Fields | Description |
|---|---|
user_token
string
|
Identifies the account holder whose program transfers you want to retrieve. Allowable Values: Existing user or business token. Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.
|
type_token
string
|
Identifies the type of program transfers to retrieve. Allowable Values: Token of existing program transfer type. Send a GET request to /programtransfers/types to retrieve program transfer type tokens.
|
Create program transfer type
Copy section link
Action:
Endpoint:
Use this endpoint to create a program transfer type. Add the program transfer details to the body of the request in JSON format.
You are required to pass in a program_funding_source_token to associate a program funding source with the program transfer type. You must therefore create a program funding source before creating a program transfer type.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the program transfer type. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API 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 |
program_funding_source_token
string
|
Identifies the program funding source to which program transfers will be credited. Allowable Values: Token of existing program funding source. Send a GET request to /fundingsources/program to retrieve program funding source tokens.
|
memo
string
|
Memo or note describing the program transfer type. Allowable Values: 99 char max |
tags
string
|
Comma-delimited list of tags describing the program transfer type. Allowable Values: 255 char max |
Retrieve program transfer type
Copy section link
Action:
Endpoint:
Use this endpoint to retrieve a specific program transfer. Include the
URL path parameters
Copy section link
| Fields | Description |
|---|---|
type_token
string
|
Identifies the program transfer type to retrieve. Allowable Values: Token of existing program transfer type. Send a GET request to /programtransfers/types to retrieve program transfer type tokens.
|
Update program transfer type
Copy section link
Action:
Endpoint:
Use this endpoint to update a program transfer type. Include the
URL path parameters
Copy section link
| Fields | Description |
|---|---|
type_token
string
|
Identifies the program transfer type to update. Allowable Values: Token of an existing program transfer type. Send a GET request to /programtransfers/types to retrieve program transfer type tokens.
|
Body field details
Copy section link
| Fields | Description |
|---|---|
program_funding_source_token
string
|
Identifies the program funding source to which program transfers will be credited. Allowable Values: Token of existing program funding source. Send a GET request to /fundingsources/program to retrieve program funding source tokens.
|
memo
string
|
Memo or note describing the program transfer type. Allowable Values: 99 char max |
tags
string
|
Comma-delimited list of tags describing the program transfer type. Allowable Values: 255 char max |
List program transfer types
Copy section link
Action:
Endpoint:
Use this endpoint to list all program transfer types.
This endpoint supports field filtering, pagination, and sorting.