API Reference
The XelPay REST API provides programmatic access to payment creation, verification status, transaction history, webhook management, and merchant configuration. All endpoints return structured JSON with standard HTTP semantics.
Authentication
Every API request must include a valid API key in the Authorization header as a Bearer token: Authorization: Bearer <YOUR_API_KEY>. Keys are scoped to a single merchant account. Rotate compromised keys immediately from the dashboard — revoked keys are invalidated within 60 seconds globally.
Base URL & Versioning
All API requests target: https://api.xelpay.com/v1. The API version is embedded in the path to ensure backward compatibility. Breaking changes are released as new major versions with a minimum 6-month deprecation notice and migration guides.
Webhook Signature Verification
Every webhook payload is signed using HMAC-SHA256. Compute the expected signature by hashing the raw request body with your webhook secret and compare it against the X-XelPay-Signature header. Reject payloads with mismatched signatures immediately. Timestamp validation (X-XelPay-Timestamp) prevents replay attacks beyond a 5-minute tolerance window.
Rate Limits
Standard merchants are permitted up to 300 API requests per minute. Sustained bursts beyond this threshold will receive HTTP 429 responses with Retry-After headers. Enterprise plans have configurable limits. Rate limit consumption data is available in the X-RateLimit-Remaining and X-RateLimit-Reset response headers.
Error Handling
XelPay uses conventional HTTP status codes: 2xx for success, 4xx for client errors, 5xx for infrastructure issues. Error responses include a machine-readable error code, a human-readable message, and a request_id field for use in support escalations. Always handle 409 Conflict responses for idempotency-key collisions.