DOCS

Support
/
Guides
Core API

Launch and manage your company’s payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta’s reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

15 minute read
February 22, 2021

Transfers

Hidden

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

/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

Sign in to use API widgets
POST

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
Optional

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
Required

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
Optional

Metadata about the transfer.

Allowable Values:

255 char max

fees

array of fee_model
Optional

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
Optional

The unique identifier of the fee.

Allowable Values:

Existing fee token

memo

string
Optional

Additional text that describes the fee transfer.

Allowable Values:

99 char max

tags

string
Optional

Tags used by the

fee_model
object

Allowable Values:

255 char max
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve fee transfer
Copy section link

Action:

GET

Endpoint:
/feetransfers/{token}

Sign in to use API widgets
GET

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
Required

Identifies the fee transfer to retrieve.

Allowable Values:

Existing fee transfer token
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create peer transfer
Copy section link

Action:

POST

Endpoint:
/peertransfers

Sign in to use API widgets
POST

Use this endpoint to request a peer transfer (i.e., a 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.

Note
This feature is disabled by default and requires activation by Marqeta.

If you are interested in using this feature for transferring or reallocating funds where the
sender_*_token
and the
recipient_*_token
belong to the same account holder, contact your Marqeta representative for more information.
Body field details
Copy section link
Fields Description

token

string
Optional

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
Required

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
Required

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
Required

The three-character ISO 4217 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

"USD" currently supported.

amount

decimal
Required

The amount of the transfer.

Allowable Values:

Format: 0.00

tags

string
Optional

Metadata about the transfer.

Allowable Values:

255 char max

memo

string
Optional

Additional descriptive text.

Allowable Values:

99 char max
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve peer transfer
Copy section link

Action:

GET

Endpoint:
/peertransfers/{token}

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List sent peer transfers
Copy section link

Action:

GET

Endpoint:
/peertransfers/user/{user_or_business_token}/sender

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List received peer transfers
Copy section link

Action:

GET

Endpoint:
/peertransfers/user/{user_or_business_token}/recipient

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List peer transfers for account holder
Copy section link

Action:

GET

Endpoint:
/peertransfers/user/{user_or_business_token}

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create program transfer
Copy section link

Action:

POST

Endpoint:
/programtransfers

Sign in to use API widgets
POST

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
Optional

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
Required

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
Required

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
Required

Amount of program transfer.

Allowable Values:

Format: 0.00

currency_code

string
Optional

The three-character ISO 4217 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

Default value:

USD

tags

string
Optional

Comma-delimited list of tags describing the program transfer.

Allowable Values:

255 char max

memo

string
Optional

Memo or note describing the program transfer.

Allowable Values:

255 char max

fees

array of fee_model
Optional

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
Optional

Specifies the fee to add.

Allowable Values:

Existing fee token

memo

string
Required

Memo or note describing the fee.

Allowable Values:

99 char max

tags

string
Optional

Comma-delimited list of tags describing the fee.

Allowable Values:

255 char max
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve program transfer
Copy section link

Action:

GET

Endpoint:
/programtransfers/{token}

Sign in to use API widgets
GET

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
Required

Identifies the program transfer to retrieve.

Allowable Values:

Existing program transfer token.

Send a

GET
request to
/programtransfers
to retrieve program transfer tokens.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List program transfers
Copy section link

Action:

GET

Endpoint:
/programtransfers

Sign in to use API widgets
GET

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
Optional

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
Optional

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Create program transfer type
Copy section link

Action:

POST

Endpoint:
/programtransfers/types

Sign in to use API widgets
POST

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
Optional

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
Required

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
Required

Memo or note describing the program transfer type.

Allowable Values:

99 char max

tags

string
Required

Comma-delimited list of tags describing the program transfer type.

Allowable Values:

255 char max
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Retrieve program transfer type
Copy section link

Action:

GET

Endpoint:
/programtransfers/types/{type_token}

Sign in to use API widgets
GET

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
Required

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.
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

Update program transfer type
Copy section link

Action:

PUT

Endpoint:
/programtransfers/types/{type_token}

Sign in to use API widgets
PUT

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
Required

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
Required

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
Required

Memo or note describing the program transfer type.

Allowable Values:

99 char max

tags

string
Required

Comma-delimited list of tags describing the program transfer type.

Allowable Values:

255 char max
Sample request body
Copy section link
Copied

Is this helpful?

Yes
No
Sample response body
Copy section link
Copied

Is this helpful?

Yes
No

List program transfer types
Copy section link

Action:

GET

Endpoint:
/programtransfers/types

Sign in to use API widgets
GET

Use this endpoint to list all program transfer types.

This endpoint supports field filtering, pagination, and sorting.

Sample response body
Copy section link
Copied

Is this helpful?

Yes
No
Related materials

Feedback on this page?

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

© 2021 Marqeta, Inc.

• Terms
 • API Terms
 • Privacy
 • Cookies
Back to Marqeta.com