RoxPay API Documentation

Webhooks let your application receive real-time HTTP notifications when events happen in your RoxPay account — payment settled, refunded, disputed, and more.

Setting Up Webhooks

Via API

curl -X POST https://app.roxpay.eu/api/v4/webhooks/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Url": "https://yourshop.com/api/webhooks/roxpay",
    "EventTypes": ["payment.settled", "payment.refunded", "payment.disputed"]
  }'

Per-Link Webhook

You can also set a webhook URL on individual payment links:

{
  "WebhookUrl": "https://yourshop.com/api/webhooks/roxpay",
  "Purpose": "Order #123",
  "Amount": 5000
}

Available Event Types

List all available event types:

curl -X GET https://app.roxpay.eu/api/v4/webhooks/event/type \
  -H "Authorization: Bearer YOUR_TOKEN"

Webhook Payload

{
  "EventType": "payment.settled",
  "TransactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "Amount": 2999,
  "Currency": "EUR",
  "Status": "SETTLED",
  "Timestamp": "2026-07-22T14:30:00Z",
  "Metadata": {
    "order_id": "12345"
  }
}

Verifying Webhooks

Always verify webhook authenticity before processing:

Check the request originates from RoxPay's IP range
Validate the payload signature (if configured)
Verify the TransactionId exists in your system

Managing Webhooks

# List webhooks
curl -X GET https://app.roxpay.eu/api/v4/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update webhook
curl -X PUT https://app.roxpay.eu/api/v4/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "Url": "https://yourshop.com/api/v2/webhooks" }'

# Delete webhook
curl -X DELETE https://app.roxpay.eu/api/v4/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test webhook
curl -X POST https://app.roxpay.eu/api/v4/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer YOUR_TOKEN"

Delivery & Retries

Webhooks are delivered via HTTP POST with Content-Type: application/json
Your endpoint must respond with 2xx within 30 seconds
Failed deliveries are retried with exponential backoff
Check delivery history:

curl -X GET https://app.roxpay.eu/api/v4/webhooks/deliveries \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

Respond quickly (< 5s) and process asynchronously
Handle duplicate events idempotently (use TransactionId + EventType)
Log all webhook payloads for debugging
Use HTTPS endpoints only
Monitor delivery failures via the deliveries endpoint

Webhooks