Fees

A fees resource represents a monetary assessment against an account holder’s general purpose account (GPA). Assessing a fee transfers funds from the account holder’s GPA account to your program’s fee account. By default, every account has a GPA account 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, use the fees array in /gpaorders.

Note
If your program uses Gateway JIT Funding, you cannot assess fees.

Create fee

Action: POST
Endpoint: /fees Use this endpoint to create a fee. Add the source details to the body of the request in JSON format.

Request body

Fields	Description
active boolean Optional	Indicates whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
amount decimal Required	Amount of the fee. Allowable Values: decimal Format: 0.00
category string Optional	Specifies if the fee is a standalone fee or a real-time fee. Allowable Values: `STANDALONE`, `REALTIME`
currency_code string Required	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code.
fee_attributes object Optional	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
fee_attributes.reason string Optional	Describes the reason for the fee. Allowable Values: 255 char max
fee_attributes.region string Optional	Describes the region in which the fee is assessed. Allowable Values: 255 char max
fee_attributes.status string Optional	Describes the status of the fee. Allowable Values: 255 char max
fee_attributes.transaction_type string Optional	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
name string Required	Name of the fee request. Allowable Values: 1–50 chars
tags string Optional	Descriptive metadata about the fee. Allowable Values: 1–255 chars
memo string Optional	Additional text describing the fee. Allowable Values: 1–255 chars
token string Optional	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 Marqeta recommends 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
type string Optional	Specifies if the fee is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`

Sample request body

JSON

{
  "token": "my_fee_01",
  "amount": 1,
  "name": "My Fee 01",
  "currency_code": "USD",
  "tags": "My Tags"
}

Response body

Fields	Description
active boolean Returned	Specifies whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
category string Conditionally returned	Specifies if the fee is a standalone fee or a real-time fee. Allowable Values: `REALTIME`, `STANDALONE`
created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
fee_attributes object Conditionally returned	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
fee_attributes.reason string Conditionally returned	Describes the reason for the fee. Allowable Values: 255 char max
fee_attributes.region string Conditionally returned	Describes the region in which the fee is assessed. Allowable Values: 255 char max
fee_attributes.status string Conditionally returned	Describes the status of the fee. Allowable Values: 255 char max
fee_attributes.transaction_type string Conditionally returned	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
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
name string Returned	Name of the fee. Allowable Values: 50 char max
tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the `fees` object. Allowable Values: 36 char max
type string Conditionally returned	Specifies if the fee is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`

Sample response body

JSON

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

List fees

Action: GET
Endpoint: /fees Use this endpoint to list existing fees. This endpoint supports field filtering and pagination.

URL query parameters

Fields	Description
count integer Optional	Number of resources to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	An array of fee objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more fee objects
data[].active boolean Returned	Specifies whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
data[].amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
data[].category string Conditionally returned	Specifies if the fee is a standalone fee or a real-time fee. Allowable Values: `REALTIME`, `STANDALONE`
data[].created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
data[].fee_attributes object Conditionally returned	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
data[].fee_attributes.reason string Conditionally returned	Describes the reason for the fee. Allowable Values: 255 char max
data[].fee_attributes.region string Conditionally returned	Describes the region in which the fee is assessed. Allowable Values: 255 char max
data[].fee_attributes.status string Conditionally returned	Describes the status of the fee. Allowable Values: 255 char max
data[].fee_attributes.transaction_type string Conditionally returned	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
data[].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
data[].name string Returned	Name of the fee. Allowable Values: 50 char max
data[].tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
data[].memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
data[].token string Returned	Unique identifier of the `fees` object. Allowable Values: 36 char max
data[].type string Conditionally returned	Specifies if the fee is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 1,
  "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": "2024-05-11T18:03:39Z",
    "last_modified_time": "2024-05-11T18:03:39Z",
    "currency_code": "USD"
  }
}

Update fee

Action: PUT
Endpoint: /fees/{token} 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	Unique identifier of the fee resource. Allowable Values: Existing fee token

Request body

Fields	Description
active boolean Optional	Indicates whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
amount decimal Optional	Amount of the fee. Allowable Values: decimal Format: 0.00
category string Optional	Allowable Values: `STANDALONE`, `REALTIME`
currency_code string Optional	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code.
fee_attributes object Optional	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
fee_attributes.reason string Optional	Describes the reason for the fee. Allowable Values: 255 char max
fee_attributes.region string Optional	Describes the region in which the fee is assessed. Allowable Values: 255 char max
fee_attributes.status string Optional	Describes the status of the fee. Allowable Values: 255 char max
fee_attributes.transaction_type string Optional	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
name string Optional	Name of the fee request. Allowable Values: 1–50 chars
tags string Optional	Descriptive metadata about the fee. Allowable Values: 1–255 chars
memo string Optional	Additional text describing the fee. Allowable Values: 1–255 chars
type string Optional	Specifies if this is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`

Sample request body

JSON

{
  "active": false
}

Response body

Fields	Description
active boolean Returned	Specifies whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
category string Conditionally returned	Specifies if the fee is a standalone fee or a real-time fee. Allowable Values: `REALTIME`, `STANDALONE`
created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
fee_attributes object Conditionally returned	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
fee_attributes.reason string Conditionally returned	Describes the reason for the fee. Allowable Values: 255 char max
fee_attributes.region string Conditionally returned	Describes the region in which the fee is assessed. Allowable Values: 255 char max
fee_attributes.status string Conditionally returned	Describes the status of the fee. Allowable Values: 255 char max
fee_attributes.transaction_type string Conditionally returned	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
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
name string Returned	Name of the fee. Allowable Values: 50 char max
tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the `fees` object. Allowable Values: 36 char max
type string Conditionally returned	Specifies if the fee is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`

Sample response body

JSON

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

Retrieve fee

Action: GET
Endpoint: /fees/{token} 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	Unique identifier of the fee resource. Allowable Values: Existing fee token

Response body

Fields	Description
active boolean Returned	Specifies whether the fee is active. Allowable Values: `true`, `false` Default value: `true`
amount decimal Returned	Amount of the fee. Allowable Values: decimal Format: 0.00
category string Conditionally returned	Specifies if the fee is a standalone fee or a real-time fee. Allowable Values: `REALTIME`, `STANDALONE`
created_time datetime Returned	Date and time when the `fees` object was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
currency_code string Returned	Three-digit ISO 4217 currency code. Allowable Values: Valid three-digit ISO 4217 currency code
fee_attributes object Conditionally returned	Describes the attributes of a fee. Allowable Values: `reason`, `region`, `status`, `transaction_type`
fee_attributes.reason string Conditionally returned	Describes the reason for the fee. Allowable Values: 255 char max
fee_attributes.region string Conditionally returned	Describes the region in which the fee is assessed. Allowable Values: 255 char max
fee_attributes.status string Conditionally returned	Describes the status of the fee. Allowable Values: 255 char max
fee_attributes.transaction_type string Conditionally returned	Specifies the transaction type in which the fee was assessed. Allowable Values: - `authorization` - `authorization.atm.withdrawal` - `balanceinquiry` - `fee.charge` - `pindebit.atm.withdrawal` - `pindebit.authorization` - `pindebit.balanceinquiry`
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
name string Returned	Name of the fee. Allowable Values: 50 char max
tags string Conditionally returned	Descriptive metadata about the fee. Allowable Values: 255 char max
memo string Conditionally returned	Additional text describing the fee. Allowable Values: 1–255 chars
token string Returned	Unique identifier of the `fees` object. Allowable Values: 36 char max
type string Conditionally returned	Specifies if the fee is a flat fee or a percentage of the transaction amount. Allowable Values: `FLAT`, `PERCENTAGE`

Sample response body

JSON

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

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Create fee

​Request body

​Sample request body

​Response body

​Sample response body

​List fees

​URL query parameters

​Response body

​Sample response body

​Update fee

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve fee

​URL path parameters

​Response body

​Sample response body

Create fee

Request body

Sample request body

Response body

Sample response body

List fees

URL query parameters

Response body

Sample response body

Update fee

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve fee

URL path parameters

Response body

Sample response body