Skip to main content
This page defines the common request/response patterns used across Payfonte APIs.

​
Request Conventions

Transport

Use HTTPS endpoints and JSON payloads for API requests.

Authentication

Send client-id and client-secret headers on every request.

Amounts

Send integer minor-unit amounts only. Decimals are not supported.

​
Required Headers

client-id: <your-client-id>
client-secret: <your-client-secret>
Content-Type: application/json

​
Base URLs

EnvironmentBase URL
Sandboxhttps://sandbox-api.payfonte.com
Productionhttps://api.payfonte.com

​
Response Structure

​
Success Responses (2xx)

Most successful responses follow this shape: 
{
  "data": {}
}
Some list endpoints also return pagination metadata: 
{
  "statusCode": 200,
  "total": 1253,
  "page": 1,
  "pages": 314,
  "limit": 4,
  "data": []
}

​
Error Responses (4xx/5xx)

{
  "error": "Validation failed",
  "errorCode": "ValidationError"
}
Always branch your handling logic using both HTTP status code and errorCode.

​
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: 
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 for conversion rules.

Authorization

Required auth headers and secure credential handling.

Error Codes

Troubleshoot common API failures.

API Reference

Endpoint-level schema and operation details.