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 an account holder (a user or business) to another account for the same account holder. Both the sender and recipient accounts 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 /gpaorders endpoint, in which case the amount of the fee is loaded into the GPA from the funding source before the GPA is debited).
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: POST
Endpoint: /feetransfers
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 present, you must assess either all fees, or no fees.
Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.
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 |
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 |
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 Allowable Values: 255 char max |
Retrieve fee transfer
Copy section link
Action: GET
Endpoint: /feetransfers/{token}
Use this endpoint to retrieve a specific fee transfer.
Include the fee transfer token path parameter to specify the fee transfer to return.
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: POST
Endpoint: /peertransfers
Use this endpoint to request a peer transfer (a movement of funds from the GPA of an account holder to another account of the same account holder). 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.
Note
This feature is disabled by default and requires activation by Marqeta.This feature enables you to transfer or reallocate funds where the
sender_*_token and the recipient_*_token belong to the same account holder.
It does not allow you to transfer or reallocate funds between different account holders.
Contact your Marqeta representative for more information.
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 |
recipient_user_token OR recipient_business_token
string
|
Specifies the account holder that receives funds. Allowable Values: Existing user or business token. Send a |
currency_code
string
|
The three-digit ISO 4217 currency code. Allowable Values: The three-digit 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: GET
Endpoint: /peertransfers/{token}
Use this endpoint to retrieve a peer transfer request.
Include the peer transfer token as a path parameter in the URL to identify the peer transfer to return.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the peer transfer to retrieve. Allowable Values: Existing peer transfer token. Send a |
List sent peer transfers
Copy section link
Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}/sender
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 |
List received peer transfers
Copy section link
Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}/recipient
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 |
List peer transfers for account holder
Copy section link
Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}
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 |
Create program transfer
Copy section link
Action: POST
Endpoint: /programtransfers
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 amount of the program transfer and all attached fees, then no funds are transferred.
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 |
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 |
amount
decimal
|
Amount of program transfer. Allowable Values: Format: 0.00 |
currency_code
string
|
The three-digit ISO 4217 currency code. Allowable Values: The three-digit ISO 4217 currency code. Default value: |
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 |
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: GET
Endpoint: /programtransfers/{token}
Use this endpoint to retrieve a specific program transfer.
Include the program transfer token path parameter to specify the program transfer to retrieve.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
Identifies the program transfer to retrieve. Allowable Values: Existing program transfer token. Send a |
List program transfers
Copy section link
Action: GET
Endpoint: /programtransfers
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 |
type_token
string
|
Identifies the type of program transfers to retrieve. Allowable Values: Token of existing program transfer type. Send a |
Create program transfer type
Copy section link
Action: POST
Endpoint: /programtransfers/types
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 |
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: GET
Endpoint: /programtransfers/types/{type_token}
Use this endpoint to retrieve a specific program transfer.
Include the type_token path parameter to indicate the program transfer type to return.
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 |
Update program transfer type
Copy section link
Action: PUT
Endpoint: /programtransfers/types/{type_token}
Use this endpoint to update a program transfer type.
Include the type_token path parameter to indicate the program transfer type to update.
Add the modified detail parameters to the body of the request in JSON format.
Only values of parameters in the request are modified; all others are left unchanged.
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 |
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 |
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: GET
Endpoint: /programtransfers/types
Use this endpoint to list all program transfer types.
This endpoint supports field filtering, pagination, and sorting.