Payment APIs

The PayoFlux Payment API provides a unified interface for processing payments across multiple payment methods, including charge (card), alternative payment methods (APM), crypto payments, reconciliation, and payment links.

All API requests should be made to the following base URL:

https://api.payoflux.com

The difference between live and test environments is in the API path:

https://api.payoflux.com/api/live/...

https://api.payoflux.com/api/test/...

All payment API endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer your_api_key_or_sandbox_api_key

You can obtain your API keys from your merchant dashboard after completing the onboarding process.

For server-to-server integrations, encrypt your request body before sending it to PayoFlux and decrypt the encrypted response on your server. This protects sensitive payment data in transit using AES-256-CBC with your merchant-specific Encryption Key.

{
  "payload": "{iv_hex}:{ciphertext_hex}"
}

Your 64-character Encryption Key is available in the merchant dashboard under Config after onboarding. See the full encryption guide for algorithm details and code examples in Node.js, PHP, and Python.

Charge endpoints use /api/live/charge and /api/test/charge. Other payment APIs use /api/live and /api/test prefixes.

/api/live/charge
/api/test/charge

Content-Type

All requests must include the Content-Type: application/json header and Authorization: Bearer your_api_key.

Request body (wire format)

Build your JSON payload per endpoint docs, encrypt it with your Encryption Key, then send:

{
  "payload": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a:8e4f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0"
}

Response body (wire format)

Responses are returned encrypted. Decrypt the payload field to get the JSON result:

{
  "success": true,
  "payload": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7:4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8"
}

Decrypted success example

After decryption, a typical success response looks like:

{
  "success": true,
  "data": {
    "transactionId": "TXN-20240101-ABC123",
    "status": "SUCCESS",
    "amount": 100.50,
    "currency": "USD"
  }
}

The API uses standard HTTP status codes to indicate success or failure:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request parameters are invalid",
    "details": {
      "field": "amount",
      "reason": "Amount must be greater than 0"
    }
  }
}

To ensure fair usage and system stability, API requests are rate-limited:

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

For payment endpoints, you can include an idempotencyKey in the request header to ensure that duplicate requests are not processed multiple times:

Idempotency-Key: unique-key-per-request

If you make the same request (with the same idempotency key) multiple times, only the first request will be processed. Subsequent requests will return the same response as the first request.

Webhooks allow you to receive real-time notifications about transaction status changes. Configure your webhook URL when creating a payment, and we will send POST requests to your endpoint when events occur.

Webhook requests include a signature header for verification:

fs-webhook-hash: HMAC-SHA256 signature

Transactions can have the following statuses:

Encrypt your charge payload before sending. Example using the encrypted wire format:

curl -X POST https://api.payoflux.com/api/test/charge \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_or_sandbox_api_key" \
  -d '{
    "payload": "3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8:8e4f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a"
  }'

The payload value is your encrypted JSON (see Encryption guide). The API returns encrypted data in the payload field — decrypt it on your server.