DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
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

10 minute read
April 10, 2023

Peer Transfers

A peer transfer moves funds from the general purpose account (GPA) of an account holder (a user or business) to another account belonging to the same account holder. Both the sender and recipient accounts must be active.

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 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
Copy section link

Fields Description

amount

decimal
Required

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Required

Three-digit ISO 4217 currency code.

Allowable Values:

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

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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Response body
Copy section link

Fields Description

amount

decimal
Returned

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

Three-digit ISO 4217 currency code.

Allowable Values:

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

Unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List peer transfers by 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

Existing user or business token.

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

Allowable Values:

Existing user or business resource token

URL query parameters
Copy section link

Fields Description

count

integer
Optional

Number of peer transfer resources to retrieve.

Allowable Values:

1-50

Default value:
25

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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:

Comma-delimited list of fields, or blank

Response body
Copy section link

Fields Description

amount

decimal
Returned

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

Three-digit ISO 4217 currency code.

Allowable Values:

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

Unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
Copy section link

JSON
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

Existing user or business token.

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

Allowable Values:

Existing user or business resource token

URL query parameters
Copy section link

Fields Description

count

integer
Optional

Number of peer transfer resources to retrieve.

Allowable Values:

1-50

Default value:
25

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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:

Comma-delimited list of fields, or blank

Response body
Copy section link

Fields Description

amount

decimal
Returned

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

Three-digit ISO 4217 currency code.

Allowable Values:

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

Unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
Copy section link

JSON
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

Existing user or business token.

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

Allowable Values:

Existing user or business resource token

URL query parameters
Copy section link

Fields Description

count

integer
Optional

Number of peer transfer resources to retrieve.

Allowable Values:

1-50

Default value:
25

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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:

Comma-delimited list of fields, or blank

Response body
Copy section link

Fields Description

amount

decimal
Returned

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

Three-digit ISO 4217 currency code.

Allowable Values:

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

Unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
Copy section link

JSON
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

Unique identifier of the peer transfer.

Allowable Values:

Existing peer transfer token

Response body
Copy section link

Fields Description

amount

decimal
Returned

Amount of the transfer.

Allowable Values:

Format: 0.00

currency_code

string
Returned

Three-digit ISO 4217 currency code.

Allowable Values:

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

Unique identifier of the peer transfer request.

Allowable Values:

1–36 chars

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Related materials

Subscribe to our developer newsletter

© 2023 Marqeta, Inc.

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