Query Non-Transaction Fees
Overview
Provide customers with transparency and insight into the fees associated with their payment processing, separate from transaction-related fees. Merchants can use this information to reconcile their deposit by seeing the total amount of fees which are automatically deducted. This will help customers to understand the true cost of each transaction, plan their cash flow better, and make informed decisions about payment processing.
Currently only for Stripe
Non-Transactional fees will currently only be available to merchants processing through Stripe.
Non-transaction related fees include:
- Payout Fee – Fee charged upon account receiving a payout
- Terminal Usage fees – These fees will only be applied to merchants utilizing card reader devices.
- PCI Non-Compliance Fee – This is a flat fee. PaySimple evaluates PCI compliance and incurs a fee when the merchant is found to be practicing non-compliant payment processes.
- PCI Program Fee – This is a flat fee incurred to support the PCI Program.
Merchant Fee Properties
| Property | Type | Description |
|---|---|---|
| amount | decimal | Amount of the fee. |
| charged_on | date | Date the fee was charged to the merchant. |
| currency | string | Originating currency. |
| fee_type | string | Name of the fee. |
| fee_type_id | int | Identifier for the type of fee. |
| id | int | Identifier for the fee. |
| notes | string | Any additional details related to the fee. |
| processor_reference_id | string | Processor fee or charge identifier. |
Merchant Fees Endpoint
Below is an example of a Merchant Fees call.
Search Request Object
POST /ps/merchant_fees/search
{
"time_zone": "Pacific Standard Time",
"filters": [
{
"type": "field_query",
"field": "fee_type",
"query": "stripe"
},
{
"type": "range",
"field": "charged_on",
"min": "01-01-2023"
}
],
"sort": {
"by": "charged_on",
"direction": "desc"
},
"page": {
"number": 1,
"size": 25
}
}
Search Response Object
200 OK
{
"data": [
{
"data": [
{
"id": 4323,
"fee_type": "Stripe Payout Fee",
"fee_type_id": 22,
"amount": 0.75,
"charged_on": "2024-05-02T13:32:40.785Z",
"currency": "USD",
"processor_reference_id": "pi_6536acf58e79f17af98ef5c5",
"notes": "Notes about the charge"
},
{
"id": 4326,
"fee_type": "Stripe PCI Program Fee",
"fee_type_id": 25,
"amount": 5.95,
"charged_on": "2023-11-05T21:32:40.785Z",
"currency": "USD",
"processor_reference_id": "pi_6536acf58e79f17af98ef5c5",
"notes": "Notes about the charge"
},
{
"id": 4355,
"fee_type": "Stripe M2 Usage Fee",
"fee_type_id": 28,
"amount": 1.50,
"charged_on": "2023-09-05T19:22:30.263Z",
"currency": "USD",
"processor_reference_id": "pi_6536acf58e79f17af98ef5c5",
"notes": "Notes about the charge".
}
]
}
],
"count": 3,
"page": {
"number": 1,
"size": 2000
},
}
Request Properties
| Property | Type | Description |
|---|---|---|
| time_zone | string | Optional - The time zone that is used when querying data. Default is UTC. |
| query | string | Optional - A search query to search all fields. |
| filters | array | Optional - A list of field filters to narrow your search. (See [Filters Properties]). |
| sort | object | Optional - Sorting criteria for the search results (See Sort Properties). |
| page | object | Optional - Pagination settings for the search results (See Page Properties). |
| search_after | string | Optional - Replaces the page.number field and defines the starting point of the search. This must be a value of the field by which you are sorting, and must be used when trying to page a dataset larger than 10,000 rows. |
*Sort is required if Search After is used.
Filters Properties
Each filter must specify a type which can be "exact_term", "exclude_term", "field_query", "range", "or". Other properties of the filter object depend on the filter type.
exact_term
Returns records where the field is an exact match with any of the terms.
| Property | Type | Description |
|---|---|---|
| type | string | Type of filter (should be 'exact_term'). |
| field | string | The field to filter on. |
| terms | array | An array of exact terms to match in the specified field. At least 1 required. |
exclude_term
Returns records where the field does not match any of the terms.
| Property | Type | Description |
|---|---|---|
| type | string | Type of filter (should be 'exclude_term'). |
| field | string | The field to filter on. |
| terms | array | An array of terms to exclude from the specified field. At least 1 required. |
field_query
Returns records where the field contains the search query.
| Property | Type | Description |
|---|---|---|
| type | string | Type of filter (should be 'field_query'). |
| field | string | The field to filter on. |
| query | array | Search query for the specific field. |
range
Returns records where the field falls within the given range. This can be applied to numeric or date fields and must specify a minimum and/or a maximum value.
| Property | Type | Description |
|---|---|---|
| type | string | Type of filter (should be 'range'). |
| field | string | The field to filter on. |
| min | string | The minimum value of the range. This is inclusive and will be a number or date depending on the field. |
| max | string | The maximum value of the range. This is inclusive and will be a number or date depending on the field. |
or
Used to combine multiple filters with a logical OR operation, meaning that a record will match the OR filter if it matches any of the filters in the filters array.
| Property | Type | Description |
|---|---|---|
| type | string | Type of filter (should be 'or'). |
| filters | array | An array of filter objects. |
Sort Properties
| Property | Type | Description |
|---|---|---|
| by | string | Required - The field to sort by. Max length 100. |
| direction | string | Optional - The direction to sort by. Must be either "asc" or "desc". Default is "asc". |
Page Properties
| Property | Type | Description |
|---|---|---|
| number | integer | The page number to receive. Default is 1. |
| size | integer | The number of results to retrieve per page. Default is 2,000. Max 10,000. |
Response Properties
| Property | Type | Description |
|---|---|---|
| data | array | An array of merchant fee objects (See Merchant Fee Properties) |
| count | integer | The total number of fees belonging to the merchant. |
| page | object | The pagination settings for the search results. Should match request pagination settings. |
Example Requests
Example 1
Find all merchant fees that were charged this year and where the fee_type is "Stripe PCI Program Fee" or the processor_reference_id contains the term "py".
{
"time_zone": "Pacific Standard Time",
"filters": [
{
"type": "range",
"field": "charged_on",
"min": "01/01/2024"
},
{
"type": "or",
"filters": [
{
"type": "exact_term",
"field": "fee_type",
"terms": [
"Stripe PCI Program Fee"
]
},
{
"type": "field_query",
"field": "processor_reference_id",
"query": "py"
}
]
}
]
}
Example 2
Find all merchant fees where notes contains the term "pci" and it was charged in 2021 or 2024.
{
"time_zone": "Pacific Standard Time",
"filters": [
{
"type": "field_query",
"field": "notes",
"query": "pci"
},
{
"type": "or",
"filters": [
{
"type": "range",
"field": "charged_on",
"min": "01/01/2024",
"max": "12/31/2024"
},
{
"type": "range",
"field": "charged_on",
"min": "01/01/2021",
"max": "12/31/2021"
}
]
}
]
}
Updated about 2 months ago