DOCS

New!

/

5 minute read

August 3, 2019

Fees

A fees resource represents a monetary assessment against a user’s general purpose account (GPA). Assessing a fee transfers funds from the user’s GPA account to your program’s fee account. By default, every user has a GPA used for the funding of transfers.

You can assess fees either post-transaction or in real time. Real-time fee assessment ensures the account has sufficient funds available to cover both the transaction amount and the fee before authorization of the transaction. To assess fees in real time, you must create a real-time fee group using the /realtimefeegroups endpoint.

When assessing a post-transaction fee, you can either debit existing GPA funds, or pull in new funds from a funding source. To use existing GPA funds, use the /feetransfers endpoint. To pull in new funds, leverage the fees array in /gpaorders.

Create fee

Action: POST
Endpoint: /fees

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to create a fee. 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.

Body field details

Fields Description

token

string, optional

The unique identifier of the fee.

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

The name of the fee request.

Allowable Values:

50 char max

currency_code

string, required

The 3-character ISO 4217 currency code.

Allowable Values:

The 3-character ISO 4217 currency code.

"USD" currently supported.

amount

decimal, required

The amount of the fee.

Allowable Values:

0.00

active

boolean, optional

Indicates whether the fee is active.

Allowable Values:

true, false

Default value: true

real_time_assessment

object, optional

Controls the assessment of real-time fees.

Allowable Values:

tags

string, optional

Descriptive metadata about the fee.

Allowable Values:

99 char max

The real_time_assessment object

Fields Description

international_enabled

boolean, optional

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

domestic_enabled

boolean, optional

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

transaction_type

string, optional

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

Sample request body

{
  "token": "my_fee_01",
  "amount": "1.00",
  "name": "My Fee 01",
  "currency_code": "USD",
  "real_time_assessment": {
    "international_enabled": true,
    "domestic_enabled": true,
    "transaction_type": "authorization"
  },
  "tags": "My Tags"
}

Is this helpful?

Sample response body

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

Is this helpful?

Retrieve fee

Action: GET
Endpoint: /fees/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a fee. Include the token path parameter to specify the fee to return.

URL path parameters

Fields Description

token

string, required

Identifies the fee to retrieve.

Allowable Values:

Existing fee token.

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

Sample response body

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

Is this helpful?

Update fee

Action: PUT
Endpoint: /fees/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to update a fee. Include the token as a path parameter to indicate the fee to update.

URL path parameters

Fields Description

token

string, required

Identifies the fee to update.

Allowable Values:

Existing fee token.

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

Body field details

Fields Description

name

string, required

The name of the fee request.

Allowable Values:

50 char max

currency_code

decimal, required

The 3-character ISO 4217 currency code.

Allowable Values:

The 3-character ISO 4217 currency code.

"USD" currently supported.

amount

decimal, required

The amount of the fee.

Allowable Values:

0.00

active

boolean, optional

Indicates whether the fee is active.

Allowable Values:

true, false

Default value: true

real_time_assessment

object, optional

Controls the assessment of real-time fees.

Allowable Values:

tags

string, optional

Descriptive metadata about the fee.

Allowable Values:

99 char max

The real_time_assessment object

Fields Description

international_enabled

boolean, optional

Enables fee assessments where the origin of the transaction acquirer is outside the US.

Allowable Values:

true, false

domestic_enabled

boolean, optional

Enables fee assessments where the origin of the transaction acquirer is inside the US.

Allowable Values:

true, false

transaction_type

string, optional

Indicates the type of transactions on which the fee is assessed.

Allowable Values:

authorization, pindebit.atm.withdrawal, pindebit

Sample request body

{
    "active": false
}

Is this helpful?

Sample response body

{
  "token": "my_fee_01",
  "active": false,
  "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
  }
}

Is this helpful?

List fees

Action: GET
Endpoint: /fees

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list existing fees.

This endpoint supports field filtering and pagination.

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_fee_02",
      "active": true,
      "name": "My Fee 02",
      "amount": 3,
      "tags": "My Tags",
      "created_time": "2017-05-11T18:03:39Z",
      "last_modified_time": "2017-05-11T18:03:39Z",
      "currency_code": "USD",
      "real_time_assessment": {
        "transaction_type": "authorization",
        "international_enabled": true,
        "domestic_enabled": true
      }
    },
    {
      "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
      }
    }
  ]
}

Is this helpful?

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.