Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

A fee charge moves funds from the general purpose account (GPA) of an account holder to your program’s fee account. The charge amount is determined by the fee that is assessed. The request returns an error if the GPA has insufficient funds to cover the fee. This behavior contrasts with assessing a fee using the /gpaorders endpoint, in which case the amount of the fee is loaded into the GPA from the funding source before the GPA is debited.

​
Create fee charge

Action: POST
Endpoint: /feecharges Use this endpoint to create a fee charge. You must pass in either user_token or business_token to associate a user or business with the fee charge. This is an all-or-nothing operation. When more than one fee is present, you must assess either all fees, or no fees.

​
Request body

FieldsDescription
business_token

string

Required		Specifies the business account holder to which the fee applies.

Pass either business_token or user_token, not both.

Allowable Values:

1–36 chars
fees

array of objects

Optional		Contains attributes that define characteristics of one or more fees.

Allowable Values:

An array of one or more fee_model objects
fees[].memo

string

Optional		Additional text describing the fee.

Allowable Values:

1–255 chars
fees[].overrideAmount

decimal

Optional		Dynamic fee amount that overrides the fee.amount field value.

Allowable Values:

decimal

Format:
0.00
fees[].tags

string

Optional		Descriptive metadata about the fee.

Allowable Values:

255 char max
fees[].token

string

Required		Unique identifier of the fee.

Allowable Values:

1–36 chars
tags

string

Optional		Metadata about the transfer.

Allowable Values:

255 char max
token

string

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

Allowable Values:

1–36 chars
user_token

string

Required		Specifies the user account holder to which the fee applies.

Pass either user_token or business_token, not both.

Allowable Values:

1–36 chars

​
Sample request body

JSON
{
  "fees": [
    {
      "token": "my_fee_01",
      "memo": "Initiation fee"
    }
  ],
  "token": "my_feecharge_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01"
}

​
Response body

FieldsDescription
business_token

string

Returned		Specifies the business account holder to which the fee applies.

Allowable Values:

1–36 chars
created_time

datetime

Returned		Date and time when the fee_charge object was created, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees

array of objects

Returned		Contains attributes that define characteristics of one or more fees.

Allowable Values:

Array of existing fees objects
fees[].fee

object

Returned		Contains details about the fee.

Allowable Values:

amount, created_time, currency_code, last_modified_time, name, tags, token
fees[].fee.amount

decimal

Returned		Amount of the fee.

Allowable Values:

decimal

Format:
0.00
fees[].fee.created_time

datetime

Returned		Date and time when the fees object was created, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees[].fee.currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Valid three-digit ISO 4217 currency code
fees[].fee.last_modified_time

datetime

Returned		Date and time when the fees object was last modified, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees[].fee.name

string

Returned		Name of the fee.

Allowable Values:

50 char max
fees[].fee.tags

string

Conditionally returned		Descriptive metadata about the fee.

Allowable Values:

255 char max
fees[].fee.token

string

Returned		Unique identifier of the fees object.

Allowable Values:

Existing fees object token
fees[].memo

string

Conditionally returned		Additional text describing the fee.

Allowable Values:

1–255 chars
fees[].overrideAmount

decimal

Conditionally returned		Dynamic fee amount that overrides the fee.amount field value.

Allowable Values:

decimal

Format:
0.00
fees[].tags

string

Conditionally returned		Descriptive metadata about the fee.

Allowable Values:

255 char max
fees[].token

string

Returned		Unique identifier of the fee.

Allowable Values:

1–36 chars
fees[].transaction_token

string

Returned		Unique identifier of the fee transaction.

Allowable Values:

36 char max
tags

string

Conditionally returned		Metadata about the fee charge.

This field is returned if it exists in the resource.

Allowable Values:

255 char max
token

string

Returned		Unique identifier of the fee transfer.

Allowable Values:

1–36 chars
user_token

string

Returned		Specifies the user account holder to which the fee applies.

Allowable Values:

1–36 chars

​
Sample response body

JSON
{
  "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": "2024-05-11T17:57:21Z",
        "last_modified_time": "2024-05-11T17:57:21Z",
        "currency_code": "USD"
      }
    }
  ],
  "token": "my_feecharge_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01",
  "created_time": "2024-05-11T19:05:55Z"
}

​
Retrieve fee charge

Action: GET
Endpoint: /feecharges/{token} Use this endpoint to retrieve a specific fee charge. Include the fee transfer token path parameter to specify the fee charge to return.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the fee charge to retrieve.

Allowable Values:

Existing fee charge token

​
Response body

FieldsDescription
business_token

string

Returned		Specifies the business account holder to which the fee applies.

Allowable Values:

1–36 chars
created_time

datetime

Returned		Date and time when the fee_charge object was created, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees

array of objects

Returned		Contains attributes that define characteristics of one or more fees.

Allowable Values:

Array of existing fees objects
fees[].fee

object

Returned		Contains details about the fee.

Allowable Values:

amount, created_time, currency_code, last_modified_time, name, tags, token
fees[].fee.amount

decimal

Returned		Amount of the fee.

Allowable Values:

decimal

Format:
0.00
fees[].fee.created_time

datetime

Returned		Date and time when the fees object was created, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees[].fee.currency_code

string

Returned		Three-digit ISO 4217 currency code.

Allowable Values:

Valid three-digit ISO 4217 currency code
fees[].fee.last_modified_time

datetime

Returned		Date and time when the fees object was last modified, in UTC.

Allowable Values:

datetime

Format:
yyyy-MM-ddThh:mm:ssZ
fees[].fee.name

string

Returned		Name of the fee.

Allowable Values:

50 char max
fees[].fee.tags

string

Conditionally returned		Descriptive metadata about the fee.

Allowable Values:

255 char max
fees[].fee.token

string

Returned		Unique identifier of the fees object.

Allowable Values:

Existing fees object token
fees[].memo

string

Conditionally returned		Additional text describing the fee.

Allowable Values:

1–255 chars
fees[].overrideAmount

decimal

Conditionally returned		Dynamic fee amount that overrides the fee.amount field value.

Allowable Values:

decimal

Format:
0.00
fees[].tags

string

Conditionally returned		Descriptive metadata about the fee.

Allowable Values:

255 char max
fees[].token

string

Returned		Unique identifier of the fee.

Allowable Values:

1–36 chars
fees[].transaction_token

string

Returned		Unique identifier of the fee transaction.

Allowable Values:

36 char max
tags

string

Conditionally returned		Metadata about the fee charge.

This field is returned if it exists in the resource.

Allowable Values:

255 char max
token

string

Returned		Unique identifier of the fee transfer.

Allowable Values:

1–36 chars
user_token

string

Returned		Specifies the user account holder to which the fee applies.

Allowable Values:

1–36 chars

​
Sample response body

JSON
{
  "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": "2024-05-11T17:57:21Z",
        "last_modified_time": "2024-05-11T17:57:21Z",
        "currency_code": "USD"
      }
    }
  ],
  "token": "my_feetransfer_01",
  "user_token": "my_user_01",
  "business_token": "my_business_01",
  "created_time": "2024-05-11T19:05:55Z"
}

Related topics

About FeesFeesFee RefundsChargebacksSimulating Transactions