Intra-Account Transfers

An intra-account transfer moves funds between general purpose accounts (GPAs) of the same user or business account holder. You can only transfer funds between a parent account and their child accounts within your card program. Both the sender and recipient accounts must be active.

Note
Intra-account transfers are only available for specific, preapproved use cases. For more information about this endpoint, contact your Marqeta representative.

Create intra-account transfer

Action: POST
Endpoint: /peertransfers Use this endpoint to request an intra-account transfer. Add the source details to the body of the request in JSON format. When creating an intra-account transfer request, you must pass in both a token to identify the transfer sender (either sender_user_token or sender_business_token) and a token to identify the transfer 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 and the recipient belong to the same user within the card program. It does not allow you to transfer or reallocate funds between different users within the same card program, or between different card programs. Contact your Marqeta representative for more information.

Request body

Fields	Description
amount decimal Required	Amount of the transfer. Allowable Values: decimal 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 intra-account transfer. Allowable Values: 1–255 chars
token string Optional	Unique identifier of the intra-account 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

{
  "token": "my_intra_account_transfer_01",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "currency_code": "USD",
  "amount": 50
}

Response body

Fields	Description
amount decimal Returned	Amount of the transfer. Allowable Values: decimal 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 intra-account 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 intra-account transfer. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the intra-account transfer request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_intra_account_transfer_01",
  "amount": 50,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "created_time": "2023-03-11T19:15:01Z"
}

List intra-account transfers by account holder

Action: GET
Endpoint: /peertransfers/user/{user_or_business_token} Use this endpoint to list intra-account transfers sent or received by a given 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
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

Fields	Description
count integer Optional	Number of intra-account 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

Fields	Description
amount decimal Returned	Amount of the transfer. Allowable Values: decimal 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 intra-account 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 intra-account transfer. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the intra-account transfer request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data[]": null,
  "token": "my_intra_account_transfer_01",
  "amount": 40,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "created_time": "2023-03-11T20:41:27Z"
}

List received intra-account transfers

Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}/recipient Use this endpoint to list intra-account 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: Existing user or business resource token

URL query parameters

Fields	Description
count integer Optional	Number of intra-account 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

Fields	Description
amount decimal Returned	Amount of the transfer. Allowable Values: decimal 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 intra-account 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 intra-account transfer. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the intra-account transfer request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data[]": null,
  "token": "my_intra_account_transfer_01",
  "amount": 40,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "created_time": "2023-03-11T20:41:27Z"
}

List sent intra-account transfers

Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}/sender Use this endpoint to list intra-account 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: Existing user or business resource token

URL query parameters

Fields	Description
count integer Optional	Number of intra-account 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

Fields	Description
amount decimal Returned	Amount of the transfer. Allowable Values: decimal 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 intra-account 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 intra-account transfer. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the intra-account transfer request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "count": "3,",
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data[]": null,
  "token": "my_intra_account_transfer_01",
  "amount": 40,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "created_time": "2023-05-11T20:41:27Z"
}

Retrieve intra-account transfer

Action: GET
Endpoint: /peertransfers/{token} Use this endpoint to retrieve an intra-account transfer request. Include the intra-account transfer token as a path parameter in the URL to identify the intra-account transfer to return.

URL path parameters

Fields	Description
token string Required	Unique identifier of the intra-account transfer. Allowable Values: Existing intra-account transfer token

Response body

Fields	Description
amount decimal Returned	Amount of the transfer. Allowable Values: decimal 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 intra-account 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 intra-account transfer. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the intra-account transfer request. Allowable Values: 1–36 chars

Sample response body

JSON

{
  "token": "my_intra_account_transfer_01",
  "amount": 50,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_01_account_2",
  "created_time": "2023-03-11T19:15:01Z"
}

​Create intra-account transfer

​Request body

​Sample request body

​Response body

​Sample response body

​List intra-account transfers by account holder

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​List received intra-account transfers

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​List sent intra-account transfers

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve intra-account transfer

​URL path parameters

​Response body

​Sample response body

Create intra-account transfer

Request body

Sample request body

Response body

Sample response body

List intra-account transfers by account holder

URL path parameters

URL query parameters

Response body

Sample response body

List received intra-account transfers

URL path parameters

URL query parameters

Response body

Sample response body

List sent intra-account transfers

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve intra-account transfer

URL path parameters

Response body

Sample response body