> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payfonte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoint Specification

> Request and response conventions for Payfonte APIs, including authentication, pagination, filtering, and error envelopes.

This page defines the common request/response patterns used across Payfonte APIs.

## Request Conventions

<CardGroup cols={3}>
  <Card title="Transport" icon="server">
    Use HTTPS endpoints and JSON payloads for API requests.
  </Card>

  <Card title="Authentication" icon="key">
    Send `client-id` and `client-secret` headers on every request.
  </Card>

  <Card title="Amounts" icon="hashtag">
    Send integer minor-unit amounts only. Decimals are not supported.
  </Card>
</CardGroup>

## Required Headers

```bash theme={null}
client-id: <your-client-id>
client-secret: <your-client-secret>
Content-Type: application/json
```

## Base URLs

| Environment | Base URL                           |
| ----------- | ---------------------------------- |
| Sandbox     | `https://sandbox-api.payfonte.com` |
| Production  | `https://api.payfonte.com`         |

## Response Structure

### Success Responses (2xx)

Most successful responses follow this shape:

```json theme={null}
{
  "data": {}
}
```

Some list endpoints also return pagination metadata:

```json theme={null}
{
  "statusCode": 200,
  "total": 1253,
  "page": 1,
  "pages": 314,
  "limit": 4,
  "data": []
}
```

### Error Responses (4xx/5xx)

```json theme={null}
{
  "error": "Validation failed",
  "errorCode": "ValidationError"
}
```

<Warning>
  Always branch your handling logic using both HTTP status code and `errorCode`.
</Warning>

## Pagination and Filtering

List endpoints such as `GET /payments/v1/checkouts` and `GET /billing/v1/disbursements` support:

* `page` (default: `1`)
* `limit` (default: `4`, max: `100`)
* `dateFrom` (optional, `YYYY-MM-DD`)
* `dateTo` (optional, `YYYY-MM-DD`)

Example:

```bash theme={null}
curl --location 'https://sandbox-api.payfonte.com/payments/v1/checkouts?page=1&limit=20&dateFrom=2025-01-01&dateTo=2025-01-31' \
  --header 'client-id: <your-client-id>' \
  --header 'client-secret: <your-client-secret>'
```

## Webhook Override Fields

Certain endpoints allow request-level webhook overrides:

* Collections endpoints use `webhook`
* Disbursement request uses `webhookURL`

Use these only when you need an endpoint-specific callback different from your dashboard default.

## Amount Formatting Rule

Payfonte does not support decimal amounts in API requests.

* Incorrect: `"amount": 1250.75`
* Correct: `"amount": 125075`

See [Amount Specification](/en/guides/introductions/amount-specification) for conversion rules.

## Related Docs

<CardGroup cols={3}>
  <Card title="Authorization" icon="key" href="/en/guides/introductions/authorization">
    Required auth headers and secure credential handling.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/en/guides/introductions/error-codes">
    Troubleshoot common API failures.
  </Card>

  <Card title="API Reference" icon="file-code" href="/en/api-reference/introduction">
    Endpoint-level schema and operation details.
  </Card>
</CardGroup>