DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

15 minute read

February 3, 2020

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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 assessed, all fees must be assessed, or no fees are assessed.

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

Allowable Values:

255 char max

Sample request body
Copy section link

{
  "fees": [
    {
    "token": "my_fee_01",
    "memo": "Initiation fee"
    }
  ],
    "token": "my_feetransfer_01",
    "user_token": "my_user_01"
}

Is this helpful?

Sample response body
Copy section link

{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee",
      "transaction_token": "162",
      "fee": {
        "token": "my_fee_01",
        "active": true,
        "name": "My Fee 01",
        "amount": 1,
        "tags": "My Tags",
        "created_time": "2019-05-11T17:57:21Z",
        "last_modified_time": "2019-05-11T17:57:21Z",
        "currency_code": "USD",
        "real_time_assessment": {
          "transaction_type": "authorization",
          "international_enabled": true,
          "domestic_enabled": true
        }
      }
    }
  ],
  "token": "my_feetransfer_01",
  "user_token": "my_user_01",
  "created_time": "2019-05-11T19:05:55Z"
}

Is this helpful?

Retrieve fee transfer
Copy section link

Action: GET
Endpoint: /feetransfers/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee",
      "transaction_token": "162",
      "fee": {
        "token": "my_fee_01",
        "active": true,
        "name": "My Fee 01",
        "amount": 1,
        "tags": "My Tags",
        "created_time": "2019-05-11T17:57:21Z",
        "last_modified_time": "2019-05-11T17:57:21Z",
        "currency_code": "USD",
        "real_time_assessment": {
          "transaction_type": "authorization",
          "international_enabled": true,
          "domestic_enabled": true
        }
      }
    }
  ],
  "token": "my_feetransfer_01",
  "user_token": "my_user_01",
  "created_time": "2019-05-11T19:05:55Z"
}

Is this helpful?

Create peer transfer
Copy section link

Action: POST
Endpoint: /peertransfers

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

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

{
  "token": "my_peertransfer_01",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_02",
  "currency_code": "USD",
  "amount": "50"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_peertransfer_01",
  "amount": 50,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_02",
  "created_time": "2019-05-11T19:15:01Z"
}

Is this helpful?

Retrieve peer transfer
Copy section link

Action: GET
Endpoint: /peertransfers/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "token": "my_peertransfer_01",
  "amount": 50,
  "currency_code": "USD",
  "sender_user_token": "my_user_01",
  "recipient_user_token": "my_user_02",
  "created_time": "2019-05-11T19:15:01Z"
}

Is this helpful?

List sent peer transfers
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "token": "my_peertransfer_03",
      "amount": 40,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:27Z"
    },
    {
      "token": "my_peertransfer_02",
      "amount": 25,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:11Z"
    },
    {
      "token": "my_peertransfer_01",
      "amount": 50,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T19:15:01Z"
    }
  ]
}

Is this helpful?

List received peer transfers
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "token": "my_peertransfer_03",
      "amount": 40,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:27Z"
    },
    {
      "token": "my_peertransfer_02",
      "amount": 25,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:11Z"
    },
    {
      "token": "my_peertransfer_01",
      "amount": 50,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T19:15:01Z"
    }
  ]
}

Is this helpful?

List peer transfers for account holder
Copy section link

Action: GET
Endpoint: /peertransfers/user/{user_or_business_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "token": "my_peertransfer_03",
      "amount": 40,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:27Z"
    },
    {
      "token": "my_peertransfer_02",
      "amount": 25,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T20:41:11Z"
    },
    {
      "token": "my_peertransfer_01",
      "amount": 50,
      "currency_code": "USD",
      "sender_user_token": "my_user_01",
      "recipient_user_token": "my_user_02",
      "created_time": "2019-05-11T19:15:01Z"
    }
  ]
}

Is this helpful?

Create program transfer
Copy section link

Action: POST
Endpoint: /programtransfers

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Required

Comma-delimited list of tags describing the program transfer.

Allowable Values:

255 char max

memo

string
Required

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

{
  "token": "my_program_transfer_01",
  "amount": "1.00",
  "tags": "my, tags",
  "memo": "This is my program transfer",
  "type_token": "my_program_transfer_type_01",
  "user_token": "my_user_01",
  "currency_code": "USD"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_program_transfer_01",
  "type_token": "my_program_transfer_type_01",
  "user_token": "my_user_01",
  "transaction_token": "169",
  "currency_code": "USD",
  "amount": 1,
  "memo": "This is my program transfer",
  "tags": "my, tags",
  "created_time": "2019-05-11T20:58:30Z"
}

Is this helpful?

Retrieve program transfer
Copy section link

Action: GET
Endpoint: /programtransfers/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "token": "my_program_transfer_02",
  "type_token": "my_program_transfer_type_01",
  "user_token": "my_user_01",
  "transaction_token": "170",
  "currency_code": "USD",
  "amount": 1,
  "memo": "This is my program transfer",
  "tags": "my, tags",
  "created_time": "2019-05-11T21:02:45Z"
}

Is this helpful?

List program transfers
Copy section link

Action: GET
Endpoint: /programtransfers

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_program_transfer_02",
      "type_token": "my_program_transfer_type_01",
      "user_token": "my_user_01",
      "transaction_token": "170",
      "currency_code": "USD",
      "amount": 1,
      "memo": "This is my program transfer",
      "tags": "my, tags",
      "created_time": "2019-05-11T21:02:45Z"
    },
    {
      "token": "my_program_transfer_01",
      "type_token": "my_program_transfer_type_01",
      "user_token": "my_user_01",
      "transaction_token": "169",
      "currency_code": "USD",
      "amount": 1,
      "memo": "This is my program transfer",
      "tags": "my, tags",
      "created_time": "2019-05-11T20:58:30Z"
    }
  ]
}

Is this helpful?

Create program transfer type
Copy section link

Action: POST
Endpoint: /programtransfers/types

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "token": "my_program_transfer_type_01",
  "tags": "my, tags",
  "memo": "This is my program transfer type.",
  "program_funding_source_token": "my_pfs_01"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_program_transfer_type_01",
  "tags": "my, tags",
  "memo": "This is my program transfer type.",
  "program_funding_source_token": "my_pfs_01",
  "created_time": "2019-03-15T19:18:50Z",
  "last_modified_time": "2019-03-15T19:18:50Z"
}

Is this helpful?

Retrieve program transfer type
Copy section link

Action: GET
Endpoint: /programtransfers/types/{type_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "token": "my_program_transfer_type_01",
  "tags": "my, tags",
  "memo": "This is my program transfer type.",
  "program_funding_source_token": "pfs_test_01",
  "created_time": "2019-03-15T19:18:50Z",
  "last_modified_time": "2019-03-15T19:18:50Z"
}

Is this helpful?

Update program transfer type
Copy section link

Action: PUT
Endpoint: /programtransfers/types/{type_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

{
  "program_funding_source_token": "pfs_test_02"
}

Is this helpful?

Sample response body
Copy section link

{
  "token": "my_program_transfer_type_02",
  "tags": "my, tags",
  "memo": "This is my other program transfer type.",
  "program_funding_source_token": "pfs_test_02",
  "created_time": "2019-03-15T19:53:23Z",
  "last_modified_time": "2019-03-15T19:58:33Z"
}

Is this helpful?

List program transfer types
Copy section link

Action: GET
Endpoint: /programtransfers/types

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list all program transfer types.

This endpoint supports field filtering, pagination, and sorting.

Sample response body
Copy section link

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_program_transfer_type_02",
      "tags": "my, tags",
      "memo": "This is my other program transfer type.",
      "program_funding_source_token": "pfs_test_01",
      "created_time": "2019-03-15T19:53:23Z",
      "last_modified_time": "2019-03-15T19:53:23Z"
    },
    {
      "token": "my_program_transfer_type_01",
      "tags": "my, tags",
      "memo": "This is my program transfer type.",
      "program_funding_source_token": "pfs_test_01",
      "created_time": "2019-03-15T19:18:50Z",
      "last_modified_time": "2019-03-15T19:18:50Z"
    }
  ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

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

We strive for the best possible developer experience.