DOCS
Support

Marqeta Home

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

5 minute read

September 4, 2020

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. If you are interested in using this feature, contact your Marqeta representative for more information.

Create real-time fee group
Copy section link

Action: POST
Endpoint: /realtimefeegroups

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string
Optional

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.

Allowable Values:

36 char max

name

string
Required

A descriptive name for the real-time fee group.

Allowable Values:

50 char max

active

boolean
Optional

Indicates whether the real-time fee group is active

Allowable Values:

true, false

Default value:
true

fee_tokens

array of strings
Optional

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

Allowable Values:

Array of already existing fee tokens.

Send a GET request to /fees to retrieve fee tokens.

Sample request body
Copy section link

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

Is this helpful?

Sample response body
Copy section link

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

Is this helpful?

Retrieve real-time fee group
Copy section link

Action: GET
Endpoint: /realtimefeegroups{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string
Required

Identifies the real-time fee group to retrieve.

Allowable Values:

Existing real-time fee group token.

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

Sample response body
Copy section link

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

Is this helpful?

Update real-time fee group
Copy section link

Action: PUT
Endpoint: /realtimefeegroups/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

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
Copy section link

Fields Description

token

string
Required

Identifies the real-time fee group to update.

Allowable Values:

Existing real-time fee group token.

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

Body field details
Copy section link

Fields Description

name

string
Required

A descriptive name for the real-time fee group.

Allowable Values:

50 char max

active

boolean
Optional

Indicates whether the real-time fee group is active

Allowable Values:

true, false

Default value:
true

fee_tokens

array of strings
Optional

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

Allowable Values:

Array of already existing fee tokens.

Send a GET request to /fees to retrieve fee tokens.

Sample request body
Copy section link

{
   "active": false
}

Is this helpful?

Sample response body
Copy section link

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

Is this helpful?

List real-time fee groups
Copy section link

Action: GET
Endpoint: /realtimefeegroups

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

This endpoint supports field filtering and pagination.

Sample response body
Copy section link

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

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.