---
updatedAt: 2026-03-24T22:29:34.000Z
agentTools:
  projectIndex: https://developers.digitalfemsa.io/llms.txt
---

# Get A List of Charges

Retrieves a paginated list of charges for the authenticated account.

Use the pagination parameters (`limit`, `next_page`, `previous_page`) to navigate through results.
Use `search` to filter charges (for example by id or reference).


## Smart Filtering

The smart filter **search** allows you to search for charges based on different criteria, including "order\_id", "customer\_id", "details.email", "payment\_method.reference", "reference\_id", and "id".

Additionally, if no matches are found in these fields, the filter will also search for text matches in the fields "description", "details.email", "details.name", "details.phone", "payment\_method.name", "payment\_method.reference", "reference\_id", and "searchable\_tags".

## Advanced Filtering

In addition to having smart filters, we can filter by specific fields using an advanced filter type that helps us obtain more precise data.

You can learn about our advanced filters in [Advanced Filters](https://developers.digitalfemsa.io/reference/advanced-filters).

To use these filters, they are only allowed in the following fields:

| Field                       | Description                         |
| :-------------------------- | :---------------------------------- |
| id                          | Filters by ID                       |
| amount                      | Filters by amount                   |
| subscription\_id            | Filters by subscription id          |
| reference\_id               | Filters by reference id             |
| created\_at                 | Filters by creation date            |
| status                      | Filters by status                   |
| order\_id                   | Filters by order                    |
| customer\_info.id           | Filters by customer ID              |
| failure\_code               | Filters by failure code             |
| customer\_id                | Filters by customer id              |
| plan\_id                    | Filters by plan id                  |
| payment\_method.auth\_code  | Filters by payment method auth code |
| payment\_method.description | Filters by description              |
| payment\_method.issuer      | Filters by payment method issuer    |
| payment\_method.brand       | Filters by payment method brand     |
| paid\_at                    | Filters by paid at date             |

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "contact": {
      "email": "engineering@femsa.com",
      "name": "Engineering Femsa",
      "url": "https://github.com/digitalfemsa/openapi/issues"
    },
    "description": "Femsa sdk",
    "license": {
      "name": "MIT-LICENSE",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "title": "Femsa API",
    "version": "2.1.0"
  },
  "servers": [
    {
      "description": "Femsa main server",
      "url": "https://api.digitalfemsa.io"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/charges": {
      "get": {
        "description": "Retrieves a paginated list of charges for the authenticated account.\n\nUse the pagination parameters (`limit`, `next_page`, `previous_page`) to navigate through results.\nUse `search` to filter charges (for example by id or reference).\n",
        "operationId": "getCharges",
        "parameters": [
          {
            "description": "Use for knowing which language to use",
            "examples": {
              "es": {
                "summary": "for spanish request/response",
                "value": "es"
              },
              "en": {
                "summary": "for english request/response",
                "value": "en"
              }
            },
            "in": "header",
            "name": "Accept-Language",
            "required": false,
            "schema": {
              "default": "es",
              "enum": [
                "es",
                "en"
              ],
              "type": "string"
            }
          },
          {
            "description": "In the case of a holding company, the company id of the child company to which will process the request.",
            "example": "6441b6376b60c3a638da80af",
            "in": "header",
            "name": "X-Child-Company-Id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The numbers of items to return, the maximum value is 250",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "format": "int32",
              "maximum": 250,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "next page",
            "in": "query",
            "name": "next",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "previous page",
            "in": "query",
            "name": "previous",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "General order search, e.g. by mail, reference etc.",
            "in": "query",
            "name": "search",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/vnd.app-v2.1.0+json": {
                "schema": {
                  "$ref": "#/components/schemas/get_charges_response"
                }
              }
            },
            "description": "successful operation"
          },
          "401": {
            "content": {
              "application/vnd.app-v2.1.0+json": {
                "example": {
                  "details": [
                    {
                      "message": "Please include your access key in your request.",
                      "param": null,
                      "code": "femsa.errors.authentication.missing_key"
                    }
                  ],
                  "log_id": "507f1f77bcf86cd799439011",
                  "object": "error",
                  "type": "authentication_error"
                },
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "authentication error"
          },
          "422": {
            "content": {
              "application/vnd.app-v2.1.0+json": {
                "example": {
                  "details": [
                    {
                      "debug_message": "The \"custom_field\" parameter is not allowed",
                      "message": "El parametro \"custom_field\" no está permitido",
                      "code": "femsa.errors.parameter_validation.whitelist"
                    }
                  ],
                  "object": "error",
                  "type": "parameter_validation_error",
                  "log_id": "6462aa7c90fef20001633546"
                },
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "whitelist validation error"
          },
          "500": {
            "content": {
              "application/vnd.app-v2.1.0+json": {
                "example": {
                  "details": [
                    {
                      "debug_message": "There was a runtime error and Femsa engineers have been notified.",
                      "message": "There was a runtime error and Femsa engineers have been notified.",
                      "param": null,
                      "code": "femsa.errors.api.system.general_failure"
                    }
                  ],
                  "object": "error",
                  "type": "api_error",
                  "log_id": "641b6f2b3cd9a50001515098"
                },
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "internal server error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List charges",
        "tags": [
          "Charges"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "page": {
        "description": "page metadata",
        "properties": {
          "next_page_url": {
            "description": "URL of the next page.",
            "example": "https://api.femsa.io/resources?limit=10&next=chrg_1",
            "nullable": true,
            "type": "string"
          },
          "previous_page_url": {
            "description": "Url of the previous page.",
            "example": "https://api.femsa.io/resources?limit=10&previous=chrg_1",
            "nullable": true,
            "type": "string"
          }
        },
        "title": "page metadata",
        "type": "object"
      },
      "pagination": {
        "description": "pagination metadata",
        "properties": {
          "has_more": {
            "description": "Indicates if there are more pages to be requested",
            "example": false,
            "type": "boolean"
          },
          "object": {
            "description": "Object type, in this case is list",
            "example": "list",
            "type": "string"
          }
        },
        "required": [
          "has_more",
          "object"
        ],
        "title": "pagination metadata",
        "type": "object"
      },
      "error": {
        "allOf": [
          {
            "$ref": "#/components/schemas/details"
          },
          {
            "properties": {
              "log_id": {
                "description": "log id",
                "example": "507f1f77bcf86cd799439011",
                "nullable": true,
                "type": "string"
              },
              "type": {
                "example": "authentication_error",
                "type": "string"
              },
              "object": {
                "example": "error",
                "type": "string"
              }
            },
            "type": "object"
          }
        ],
        "description": "err model",
        "title": "error"
      },
      "charge_response": {
        "properties": {
          "amount": {
            "example": 600000,
            "format": "int64",
            "type": "integer"
          },
          "channel": {
            "$ref": "#/components/schemas/charge_response_channel"
          },
          "created_at": {
            "example": 1768581166,
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "example": "MXN",
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "description": {
            "example": "Payment from order",
            "type": "string"
          },
          "device_fingerprint": {
            "example": "6FR3chaU4Y1nGAW5NAGd1rcjAKa142Ba",
            "type": "string"
          },
          "failure_code": {
            "example": "suspected_fraud",
            "nullable": true,
            "type": "string"
          },
          "failure_message": {
            "example": "Este cargo ha sido declinado porque el comportamiento del comprador es sospechoso.",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "example": "696a682e1ef5ca00015698b7",
            "type": "string"
          },
          "livemode": {
            "example": true,
            "type": "boolean"
          },
          "object": {
            "type": "string"
          },
          "order_id": {
            "example": "ord_2zNwzJrfNC24uQUzq",
            "type": "string"
          },
          "paid_at": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "payment_method": {
            "$ref": "#/components/schemas/charge_response_payment_method"
          },
          "reference_id": {
            "description": "Reference ID of the charge",
            "example": "ref_2tN73UdUSNrYRPD9r",
            "nullable": true,
            "type": "string"
          },
          "refunds": {
            "$ref": "#/components/schemas/charge_response_refunds"
          },
          "status": {
            "example": "pending_payment",
            "type": "string"
          },
          "is_refundable": {
            "example": false,
            "type": "boolean"
          }
        },
        "title": "charge_response",
        "type": "object"
      },
      "details": {
        "properties": {
          "details": {
            "items": {
              "$ref": "#/components/schemas/details_error"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "payment_method_cash": {
        "allOf": [
          {
            "$ref": "#/components/schemas/payment_method"
          },
          {
            "description": "use for cash responses",
            "properties": {
              "auth_code": {
                "example": "542563",
                "nullable": true,
                "type": "string"
              },
              "cashier_id": {
                "example": "OINM01010",
                "nullable": true,
                "type": "string"
              },
              "reference": {
                "example": "93000262276908",
                "type": "string"
              },
              "barcode_url": {
                "example": "https://pt-common-s3-stg.s3.amazonaws.com/644ebf80f2243197aad6cd8810375b905b613dbe.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA3UN6375MP4SLLCWV%2F20230203%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230203T215750Z&X-Amz-Expires=604800&X-Amz-Security-Token=...&X-Amz-SignedHeaders=host&X-Amz-Signature=...",
                "type": "string"
              },
              "expires_at": {
                "example": 1768802399,
                "format": "int64",
                "type": "integer"
              },
              "service_name": {
                "example": "OxxoPay",
                "type": "string"
              },
              "store": {
                "nullable": true,
                "type": "string",
                "example": null
              },
              "store_name": {
                "example": "OXXO",
                "type": "string"
              }
            },
            "title": "charge_data_payment_method_cash_response",
            "type": "object"
          }
        ]
      },
      "payment_method": {
        "properties": {
          "type": {
            "type": "string"
          },
          "object": {
            "example": "payment_source",
            "type": "string"
          }
        },
        "required": [
          "object"
        ],
        "type": "object"
      },
      "get_charges_response": {
        "allOf": [
          {
            "$ref": "#/components/schemas/page"
          },
          {
            "$ref": "#/components/schemas/pagination"
          },
          {
            "properties": {
              "data": {
                "items": {
                  "$ref": "#/components/schemas/charge_response"
                },
                "type": "array"
              }
            },
            "type": "object"
          }
        ],
        "title": "get_charges_response"
      },
      "charge_response_channel": {
        "properties": {
          "segment": {
            "example": "Checkout",
            "type": "string"
          },
          "checkout_request_id": {
            "example": "f3a5bfc1-ba1c-474f-9687-46d8b75ffc90",
            "type": "string"
          },
          "checkout_request_type": {
            "example": "Integration",
            "type": "string"
          },
          "id": {
            "example": "channel_2zNxD65G8MBNkYksy",
            "type": "string"
          }
        },
        "type": "object"
      },
      "charge_response_payment_method": {
        "discriminator": {
          "mapping": {
            "cash_payment": "payment_method_cash"
          },
          "propertyName": "object"
        },
        "oneOf": [
          {
            "$ref": "#/components/schemas/payment_method_cash"
          }
        ],
        "title": "charge_response_payment_method"
      },
      "charge_response_refunds_data": {
        "properties": {
          "amount": {
            "example": -15000,
            "format": "int64",
            "type": "integer"
          },
          "auth_code": {
            "example": "867372",
            "type": "string"
          },
          "created_at": {
            "example": 1678226878,
            "format": "int64",
            "type": "integer"
          },
          "expires_at": {
            "description": "refund expiration date",
            "example": 1678226878,
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "example": "6407b5bee1329a000175ba11",
            "type": "string"
          },
          "object": {
            "example": "refund",
            "type": "string"
          },
          "status": {
            "description": "refund status",
            "example": "pending",
            "type": "string"
          },
          "payout_id": {
            "example": "6fca054a-8519-4c43-971e-cea35cc519bb",
            "type": "string"
          },
          "reference": {
            "description": "payout reference for oxxo stores",
            "example": "12002000778626",
            "type": "string"
          }
        },
        "required": [
          "amount",
          "created_at",
          "id",
          "object"
        ],
        "title": "charge_response_refunds_data",
        "type": "object"
      },
      "charge_response_refunds": {
        "allOf": [
          {
            "$ref": "#/components/schemas/pagination"
          },
          {
            "$ref": "#/components/schemas/page"
          },
          {
            "properties": {
              "data": {
                "description": "refunds",
                "items": {
                  "$ref": "#/components/schemas/charge_response_refunds_data"
                },
                "type": "array"
              }
            },
            "type": "object"
          }
        ],
        "nullable": true,
        "title": "charge_response_refunds",
        "type": "object"
      },
      "details_error": {
        "properties": {
          "code": {
            "example": "femsa.errors.authentication.missing_key",
            "type": "string"
          },
          "param": {
            "nullable": true,
            "type": "string"
          },
          "message": {
            "example": "Acceso no autorizado.",
            "type": "string"
          },
          "debug_message": {
            "example": "Please include your access key in your request.",
            "type": "string"
          }
        },
        "title": "details_error",
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  }
}
```