/
10 minute read
March 24, 2022

Peer Transfers

Hidden

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.

Create peer transfer

Action: POST
Endpoint: /peertransfers

Use this endpoint to request a peer transfer (i.e., a movement of funds from the GPA of an account holder to another account belonging to 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.
Request body
Fields Description

amount

decimal
Required

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Required

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Optional

Additional descriptive text about the transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Optional

Specifies the business account holder that receives funds.

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

Allowable Values:

1–36 chars

recipient_user_token

string
Optional

Specifies the user account holder that receives funds.

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

Allowable Values:

1–36 chars

sender_business_token

string
Optional

Specifies the business account holder that sends funds.

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

Allowable Values:

1–36 chars

sender_user_token

string
Optional

Specifies the user account holder that sends funds.

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

Allowable Values:

1–36 chars

tags

string
Optional

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Optional

The unique identifier of the peer 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:

1–36 chars

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

amount

decimal
Returned

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Conditionally returned

Additional descriptive text about the peer transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Conditionally returned

Specifies the business account holder that receives funds.

Allowable Values:

1–36 chars

recipient_user_token

string
Conditionally returned

Specifies the user account holder that receives funds.

Allowable Values:

1–36 chars

sender_business_token

string
Conditionally returned

Specifies the business account holder that sends funds.

Allowable Values:

1–36 chars

sender_user_token

string
Conditionally returned

Specifies the user account holder that sends funds.

Allowable Values:

1–36 chars

tags

string
Conditionally returned

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Returned

The unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List peer transfers for account holder

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
Fields Description

business_token

string
Required

Existing user or business token.

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

Allowable Values:

1–36 chars

URL query parameters
Fields Description

count

integer
Optional

The number of peer transfer resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

A comma-delimited list of fields, or blank

Response body
Fields Description

amount

decimal
Returned

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Conditionally returned

Additional descriptive text about the peer transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Conditionally returned

Specifies the business account holder that receives funds.

Allowable Values:

1–36 chars

recipient_user_token

string
Conditionally returned

Specifies the user account holder that receives funds.

Allowable Values:

1–36 chars

sender_business_token

string
Conditionally returned

Specifies the business account holder that sends funds.

Allowable Values:

1–36 chars

sender_user_token

string
Conditionally returned

Specifies the user account holder that sends funds.

Allowable Values:

1–36 chars

tags

string
Conditionally returned

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Returned

The unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List received peer transfers

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
Fields Description

user_or_business_token

string
Required

Existing user or business token.

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

Allowable Values:

1–36 chars

URL query parameters
Fields Description

count

integer
Optional

The number of peer transfer resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

A comma-delimited list of fields, or blank

Response body
Fields Description

amount

decimal
Returned

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Conditionally returned

Additional descriptive text about the peer transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Conditionally returned

Specifies the business account holder that receives funds.

Allowable Values:

1–36 chars

recipient_user_token

string
Conditionally returned

Specifies the user account holder that receives funds.

Allowable Values:

1–36 chars

sender_business_token

string
Conditionally returned

Specifies the business account holder that sends funds.

Allowable Values:

1–36 chars

sender_user_token

string
Conditionally returned

Specifies the user account holder that sends funds.

Allowable Values:

1–36 chars

tags

string
Conditionally returned

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Returned

The unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List sent peer transfers

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
Fields Description

user_or_business_token

string
Required

Existing user or business token.

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

Allowable Values:

1–36 chars

URL query parameters
Fields Description

count

integer
Optional

The number of peer transfer resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

fields

string
Optional

Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.

Allowable Values:

A comma-delimited list of fields, or blank

Response body
Fields Description

amount

decimal
Returned

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Conditionally returned

Additional descriptive text about the peer transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Conditionally returned

Specifies the business account holder that receives funds.

Allowable Values:

1–36 chars

recipient_user_token

string
Conditionally returned

Specifies the user account holder that receives funds.

Allowable Values:

1–36 chars

sender_business_token

string
Conditionally returned

Specifies the business account holder that sends funds.

Allowable Values:

1–36 chars

sender_user_token

string
Conditionally returned

Specifies the user account holder that sends funds.

Allowable Values:

1–36 chars

tags

string
Conditionally returned

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Returned

The unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve peer transfer

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
Fields Description

token

string
Required

Peer transfer token

Allowable Values:

Existing peer transfer token

Response body
Fields Description

amount

decimal
Returned

The amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

The three-digit ISO 4217 currency code.

Allowable Values:

A valid three-digit ISO 4217 currency code

memo

string
Conditionally returned

Additional descriptive text about the peer transfer.

Allowable Values:

1–99 chars

recipient_business_token

string
Conditionally returned

Specifies the business account holder that receives funds.

Allowable Values:

1–36 chars

recipient_user_token

string
Conditionally returned

Specifies the user account holder that receives funds.

Allowable Values:

1–36 chars

sender_business_token

string
Conditionally returned

Specifies the business account holder that sends funds.

Allowable Values:

1–36 chars

sender_user_token

string
Conditionally returned

Specifies the user account holder that sends funds.

Allowable Values:

1–36 chars

tags

string
Conditionally returned

Metadata about the peer transfer.

Allowable Values:

1–255 chars

token

string
Returned

The unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter