Create fee transfer

Action: POST
Endpoint: /feetransfers

Use this endpoint to create a fee transfer. Add the fee transfer details to the body of the request in JSON format.

When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

You must pass in either user_token or business_token to associate a user/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

Name Type Required? Description Allowable Values
token string No 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.
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.
Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
tags string No Metadata about the transfer. 255 char max
fees array of fee_model No Contains attributes that define characteristics of one or more fees.

The fee_model object

Name Type Required? Description Allowable Values
token string No The unique identifier of the fee. Existing fee token
memo string No Additional text that describes the fee transfer. 99 char max
tags string No 255 char max

Sample request body

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

Sample response body

{
"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": "2017-05-11T17:57:21Z",
"last_modified_time": "2017-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": "2017-05-11T19:05:55Z"
}


Retrieve fee transfer

Action: GET
Endpoint: /feetransfers/{token}

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

Name Type Required? Description Allowable Values
token string Yes Identifies the fee transfer to retrieve. Existing fee transfer token

Sample response body

{
"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": "2017-05-11T17:57:21Z",
"last_modified_time": "2017-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": "2017-05-11T19:05:55Z"
}


Create peer transfer

Action: POST
Endpoint: /peertransfers

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 you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

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

Name Type Required? Description Allowable Values
token string No 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.
36 char max
sender_user_token

OR

sender_business_token
string Required Specifies the account holder that sends funds. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
recipient_user_token

OR

recepient_business_token
string Required Specifies the account holder that receives funds. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
currency_code string Yes The 3-character ISO 4217 currency code. The 3-character ISO 4217 currency code.

"USD" currently supported.
amount decimal Yes The amount of the transfer. 0.00
tags string No Metadata about the transfer. 255 char max
memo string No Additional descriptive text. 99 char max

Sample request body

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

Sample response body

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


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

Name Type Required? Description Allowable Values
token string Yes Identifies the peer transfer to retrieve. Existing peer transfer token.

Issue a GET to /peertransfers/user/{user_or_business_token} to retrieve all peer transfer tokens for a particular account holder.

Sample response body

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


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

Name Type Required? Description Allowable Values
user_or_business_token string Yes Identifies the sender of the peer transfers you want to list. Existing user or business token.

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

Sample response body

{
"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": "2017-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": "2017-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": "2017-05-11T19:15:01Z"
}
]
}


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 arameters

Name Type Required? Description Allowable Values
user_or_business_token string Yes Identifies the recepient of the peer transfers you want to list. Existing user or business token.

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

Sample response body

{
"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": "2017-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": "2017-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": "2017-05-11T19:15:01Z"
}
]
}


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

Name Type Required? Description Allowable Values
user_or_business_token string Yes Identifies the account holder whose peer transfers you want to list. Existing user or business token.

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

Sample response body

{
"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": "2017-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": "2017-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": "2017-05-11T19:15:01Z"
}
]
}


Create program transfer

Action: POST
Endpoint: /programtransfers

Use this endpoint to create a program transfer. Add the program transfer details to the body of the request in JSON format.

When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

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

Name Type Required? Description Allowable Values
token string No 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.
36 char max
type_token string Yes Specifies the program transfer type. Token of existing program transfer type.

Issue a GET 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. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
amount decimal Yes Amount of program transfer. 0.00 format
currency_code string No The 3-character ISO 4217 currency code. The 3-character ISO 4217 currency code.

Default: "USD"
tags string Yes Comma-delimited list of tags describing the program transfer. 255 char max
memo string Yes Memo or note describing the program transfer. 255 char max
fees array of fee_model No 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.

The fee_model object

Name Type Required? Description Allowable Values
token string No Specifies the fee to add. Existing fee token
memo string Yes Memo or note describing the fee. 99 char max
tags string No Comma-delimited list of tags describing the fee. 255 char max

Sample request body

{
"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"
}

Sample response body

{
"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": "2017-05-11T20:58:30Z"
}


Retrieve program transfer

Action: GET
Endpoint: /programtransfers/{token}

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

Name Type Required? Description Allowable Values
token string Yes Identifies the program transfer to retrieve. Existing program transfer token.

Issue a GET to /programtransfers to retrieve program transfer tokens.

Sample response body

{
"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": "2017-05-11T21:02:45Z"
}


List program transfers

Action: GET
Endpoint: /programtransfers

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

Name Type Required? Description Allowable Values
user_token string No Identifies the account holder whose program transfers you want to retrieve. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
type_token string No Identifies the type of program transfers to retrieve. Token of existing program transfer type.

Issue a GET to /programtransfers/types to retrieve program transfer type tokens.

Sample response body

{
"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": "2017-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": "2017-05-11T20:58:30Z"
}
]
}


Create program transfer type

Action: POST
Endpoint: /programtransfers/types

Use this endpoint to create a program transfer type. Add the program transfer details to the body of the request in JSON format.

When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

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

Name Type Required? Description Allowable Values
token string No 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.
36 char max
program_funding_source_token string Yes Identifies the program funding source to which program transfers will be credited. Token of existing program funding source.

Issue a GET to /fundingsources/program to retrieve program funding source tokens.
memo string Yes Memo or note describing the program transfer type. 99 char max
tags string Yes Comma-delimited list of tags describing the program transfer type. 255 char max

Sample request body

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

Sample response body

{
"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": "2016-03-15T19:18:50Z",
"last_modified_time": "2016-03-15T19:18:50Z"
}


Retrieve program transfer type

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

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

Name Type Required? Description Allowable Values
type_token string Yes Identifies the program transfer type to retrieve. Token of existing program transfer type.

Issue a GET to /programtransfers/types to retrieve program transfer type tokens.

Sample response body

{
"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": "2016-03-15T19:18:50Z",
"last_modified_time": "2016-03-15T19:18:50Z"
}


Update program transfer type

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

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

Name Type Required? Description Allowable Values
type_token string Yes Identifies the program transfer type to update. Token of an existing program transfer type.

Issue a GET to /programtransfers/types to retrieve program transfer type tokens.

Body field details

Name Type Required? Description Allowable Values
program_funding_source_token string Yes Identifies the program funding source to which program transfers will be credited. Token of existing program funding source.

Issue a GET to /fundingsources/program to retrieve program funding source tokens.
memo string Yes Memo or note describing the program transfer type. 99 char max
tags string Yes Comma-delimited list of tags describing the program transfer type. 255 char max

Sample request body

{
"program_funding_source_token": "pfs_test_02"
}

Sample response body

{
"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": "2016-03-15T19:53:23Z",
"last_modified_time": "2016-03-15T19:58:33Z"
}


List program transfer types

Action: GET
Endpoint: /programtransfers/types

Use this endpoint to list all program transfer types.

This endpoint supports field filtering, pagination, and sorting.

Sample response body

{
"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": "2016-03-15T19:53:23Z",
"last_modified_time": "2016-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": "2016-03-15T19:18:50Z",
"last_modified_time": "2016-03-15T19:18:50Z"
}
]
}