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.
If your program uses Gateway JIT Funding, you cannot assess fees.
Create fee
Action:POSTEndpoint:
/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, falseDefault 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, falseDefault 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:GETEndpoint:
/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 modelDefault 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, falseDefault 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:PUTEndpoint:
/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, falseDefault 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, falseDefault 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:GETEndpoint:
/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, falseDefault 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"
}