Webhooks & API
Integrate Rheopay into your own systems using API keys and outgoing webhooks.
Webhooks & API
Rheopay exposes a REST API and an outgoing webhook system so you can integrate payment events into your own applications, automations, and back-office systems.
API keys
API keys let your server-side code call the Rheopay API on behalf of your merchant account.
Creating an API key
- Go to Settings → API Keys → New Key.
- Give it a descriptive name (e.g.
CRM integration,Automation server). - Copy the key immediately — it is shown only once.
API keys have full merchant-level access. Store them in environment variables or a secrets manager, never in source code or client-side JavaScript.
Revoking an API key
Go to Settings → API Keys, find the key, and click Revoke. Any requests using that key will immediately return 401 Unauthorized.
Using an API key
Pass your API key in the Authorization header on every request:
Authorization: Bearer <your-api-key>REST API overview
The base URL for all API requests is https://yourdomain.com/api.
Authentication
All endpoints require either a logged-in session (cookie-based) or an Authorization: Bearer <api-key> header.
Core endpoints
Payment links
| Method | Path | Description |
|---|---|---|
GET | /api/links | List all payment links. |
POST | /api/links | Create a new payment link. |
GET | /api/links/:id | Get a single link by ID. |
PUT | /api/links/:id | Update a link. |
DELETE | /api/links/:id | Delete a link. |
POST | /api/links/:id/activate | Activate a draft link. |
POST | /api/links/:id/deactivate | Deactivate an active link. |
POST | /api/links/:id/send-email | Send the link by email. |
POST | /api/links/:id/duplicate | Duplicate a link as a new draft. |
Transactions
| Method | Path | Description |
|---|---|---|
GET | /api/transactions | List transactions with filters. |
GET | /api/transactions/:id | Get transaction detail. |
POST | /api/transactions/:id/refund | Refund a transaction. |
Customers
| Method | Path | Description |
|---|---|---|
GET | /api/customers | List customers. |
POST | /api/customers | Create a customer. |
GET | /api/customers/:id | Get a customer. |
PUT | /api/customers/:id | Update a customer. |
DELETE | /api/customers/:id | Delete a customer. |
Products
| Method | Path | Description |
|---|---|---|
GET | /api/products | List products. |
POST | /api/products | Create a product. |
PUT | /api/products/:id | Update a product. |
DELETE | /api/products/:id | Delete a product. |
Analytics
| Method | Path | Description |
|---|---|---|
GET | /api/analytics/stats | Summary stats for a date range. |
Creating a payment link via API
POST /api/links
Content-Type: application/json
Authorization: Bearer
{
"description": "Invoice #1042",
"amount": 12500,
"currency": "EUR",
"customerName": "Jane Smith",
"customerEmail": "jane@example.com",
"expiresAt": "2025-12-31T23:59:59Z",
"status": "ACTIVE"
} Amounts are in the smallest currency unit (e.g. cents for EUR/USD). 12500 = €125.00.
Response:
{
"id": "clx...",
"token": "abc123xyz",
"url": "https://yourdomain.com/pay/abc123xyz",
"status": "ACTIVE",
"createdAt": "2025-06-01T10:00:00Z"
}Outgoing webhooks
Rheopay can send an HTTP POST to your server whenever a payment event occurs.
Configuring a webhook
- Go to Settings → Webhooks → New Webhook.
- Enter your endpoint URL (must be publicly reachable, HTTPS recommended).
- Select the events to subscribe to.
- Save. Rheopay will send a test event to verify the endpoint.
Webhook events
| Event | Triggered when |
|---|---|
transaction.succeeded | A payment is completed successfully. |
transaction.failed | A payment attempt fails. |
transaction.refunded | A refund is issued. |
link.created | A new payment link is created. |
link.activated | A link is activated. |
link.expired | A link reaches its expiry date or max-use limit. |
link.paid | A link transitions to Paid status. |
Webhook payload
All events share the same envelope:
{
"event": "transaction.succeeded",
"timestamp": "2025-06-01T10:05:00Z",
"data": {
"transactionId": "txn_...",
"linkId": "clx...",
"amount": 12500,
"currency": "EUR",
"customerEmail": "jane@example.com",
"status": "SUCCEEDED"
}
}Verifying webhook signatures
Each request from Rheopay includes an X-Rheopay-Signature header. Verify it to confirm the request is genuine:
- Take the raw request body as a string.
- Compute
HMAC-SHA256(body, your-webhook-secret). - Compare the result (hex-encoded) to the
X-Rheopay-Signatureheader value.
Your webhook secret is shown once when you create the webhook endpoint. Store it securely.
Retry policy
If your endpoint returns anything other than a 2xx status code, Rheopay retries with exponential back-off up to 5 times over 24 hours.
Testing webhooks
From the webhook detail page, click Send test event to fire a sample payload to your endpoint and verify your handler is working.
Delivery log
Go to Settings → Webhooks → [your webhook] → Delivery Log to see a history of all sent events, their HTTP response codes, and any error details.
Global search API
GET /api/search?q=jane
Authorization: Bearer Returns matching links, customers, and transactions in a single response. Useful for building internal dashboards or search interfaces.
Related pages
- Security — API key security and session management.
- Payment Links — creating links from the dashboard.
- Analytics & Reporting — transaction data and exports.