Real-Time Fee Groups

Marqeta enables you to assess fees in real time through the use of real-time fee groups. A real-time fee group is a group of fees associated with an account holder group (and thereby associated with the users and businesses that are part of that account holder group). Real-time fee assessment ensures that associated accounts have sufficient funds available to cover both the transaction amount and the fee before authorization of a transaction.

Before you create a real-time fee group, you must create the individual fees (using the /fees endpoint) and the account holder group to which you will associate the real-time fee group (using the /accountholdergroups endpoint). Each fee in the group must be applicable to a different transaction type. For example, one fee could assess $1 on authorization transactions while another assesses $2 on PIN-debit transactions.

Use of real-time fee groups requires prior approval by Marqeta.

Create real-time fee group

Action: POST
Endpoint: /realtimefeegroups

Use this endpoint to create a real-time fee group. Add the real-time fee group 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.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the real-time fee group.

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
name string Yes A descriptive name for the real-time fee group. 50 char max
active boolean No Indicates whether the real-time fee group is active true | false;

Default: true
fee_tokens array of strings No Specifies the fees in this real-time fee group.

No two fees in the group can be applicable to the same transaction type (in other words, each fee must have a different value for its real_time_assessment.transaction_type field.)
Array of already existing fee tokens.

Issue a GET to /fees to retrieve fee tokens.

Sample request

{
"name": "My Real-Time Fee Group 01",
"token": "my_rtfg_01",
"fee_tokens": [
"my_fee_01", "my_fee_05"
]
}

Sample response

{
"token": "my_rtfg_01",
"active": true,
"name": "My Real-Time Fee Group 01",
"created_time": "2016-01-28T00:36:11Z",
"last_modified_time": "2016-01-28T00:36:11Z",
"fee_tokens": [
"my_fee_01",
"my_fee_05"
]
}


Retrieve real-time fee group

Action: GET
Endpoint: /realtimefeegroups{token}

Use this endpoint to retrieve a specific real-time fee group. Include the real-time fee group token path parameter to specify the real-time fee group to return.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the real-time fee group to retrieve. Existing real-time fee group token.

Issue a GET to /realtimefeegroups to retrieve real-time fee group tokens.

Sample response

{
"token": "my_rtfg_01",
"active": true,
"name": "My Real-Time Fee Group 01",
"created_time": "2016-01-28T00:36:11Z",
"last_modified_time": "2016-01-28T00:36:11Z",
"fee_tokens": [
"my_fee_01",
"my_fee_05"
]
}


Update real-time fee group

Action: PUT
Endpoint: /realtimefeegroups/{token}

Use this endpoint to update a real-time fee group. Include the real-time fee group token path parameter to specify the real-time fee group to update. Add the real-time fee group details to update 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
token string Yes Identifies the real-time fee group to update. Existing real-time fee group token.

Issue a GET to /realtimefeegroups to retrieve real-time fee group tokens.

Body field details

Name Type Required? Description Allowable Values
name string Yes A descriptive name for the real-time fee group. 50 char max
active boolean No Indicates whether the real-time fee group is active true | false

Default: true
fee_tokens array of strings No Specifies the fees in this real-time fee group.

No two fees in the group can be applicable to the same transaction type (in other words, each fee must have a different value for its real_time_assessment.transaction_type field.)
Array of already existing fee tokens.

Issue a GET to /fees to retrieve fee tokens.

Sample request

{
"active": false
}

Sample response

{
"token": "my_rtfg_01",
"active": false,
"name": "My Real-Time Fee Group 01",
"created_time": "2016-01-28T00:36:11Z",
"last_modified_time": "2016-01-28T00:53:48Z",
"fee_tokens": [
"my_fee_01",
"my_fee_05"
]
}


List real-time fee groups

Action: GET
Endpoint: /realtimefeegroups

Use this endpoint to list existing real-time fee groups.

This endpoint supports field filtering and pagination.

Sample response

{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "my_rtfg_01",
"active": false,
"name": "My Real-Time Fee Group 01",
"created_time": "2016-01-28T00:36:11Z",
"last_modified_time": "2016-01-28T00:53:48Z",
"fee_tokens": [
"my_fee_01",
"my_fee_05"
]
},
{
"token": "my_rtfg_02",
"active": true,
"name": "My Real-Time Fee Group 01",
"created_time": "2015-09-17T23:05:20Z",
"last_modified_time": "2015-09-17T23:05:20Z",
"fee_tokens": [
"07b4aeeb-f572-4bc1-b84c-66bb65865372",
"64857807-c80d-43db-928a-e134a22a662b",
"9503b823-a1aa-4e2b-8df7-f9446eeb61ca"
]
}
]
}