Create Fee Transfer

Action: POST
Endpoint: /feetransfers

To create a fee transfer, send a POST request to the /feetransfers endpoint and include the fee transfer details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. 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.

fee_model

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}

To retrieve a specific fee transfer, issue a GET request to the /feetransfers/{token} endpoint. 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

To request a peer transfer (movement of funds from the GPA of one account holder to that of another), send a POST request to the /peertransfers endpoint and include the source details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. 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}

To retrieve a peer transfer request, issue a GET request to the /peertransfers/{token} endpoint. 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

To list peer transfers sent by an account holder, issue a GET request to the /peertransfers/user/{user_or_business_token}/sender endpoint. 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

To list peer transfers sent by an account holder, issue a GET request to the /peertransfers/user/{user_or_business_token}/recipient endpoint. Include a user or business token as a path parameter to identify the recipient.

This endpoint supports field filtering and pagination.

URL Path Parameters

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

To list peer transfers sent or received by a particular account holder, issue a GET request to the /peertransfers/user/{user_or_business_token} endpoint. 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

To create a program transfer, send a POST request to the /programtransfers endpoint and include the program transfer details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. 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.

fee_model

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}

To retrieve a specific program transfer, issue a GET request to the /programtransfers/{token} endpoint. 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

To list all program transfers, issue a GET request to the /programtransfers endpoint.

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

To create a program transfer type, send a POST request to the /programtransfers/types endpoint and include the program transfer details in JSON format in the body of the request. When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using any alpha-numeric characters, 36 chars max. 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}

To retrieve a specific program transfer, issue a GET request to the /programtransfers/types/{type_token} endpoint. 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}

To update a program transfer type, send a PUT request to the /programtransfers/types/{type_token} endpoint. Include the type_token path parameter to indicate the program transfer type to update. Include the modified detail parameters in JSON format in the body of the request. 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

To list all program transfer types, issue a GET request to the /programtransfers/types endpoint.

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