RoxPay API Documentation

Understand the full lifecycle of a RoxPay payment, from creation to settlement, refund, and dispute.

Every payment link goes through a series of statuses during its lifetime. Understanding these statuses is essential for building reliable integrations.

Status Flow

CREATED → OPENED → INITIALIZED → AUTHORIZED → SETTLED
                                    ↓
                                RELEASED (void)
                                    
SETTLED → REFUNDED / PARTIALLY_REFUNDED
SETTLED → DISPUTED → CHARGEBACK_ACCEPTED

Any stage → DECLINED / TECHNICAL_ERROR / TIMEOUT / EXPIRED / CANCELLED

Status Reference

ID	Status	Description
1	`CREATED`	Link generated, not yet opened by the customer.
13	`OPENED`	Customer opened the checkout page.
14	`INITIALIZED`	Customer started entering payment details.
8	`AUTHORIZED`	Pre-authorized — funds held but not captured.
2	`SETTLED`	Payment captured and settled. Money is on its way.
15	`PENDING`	Awaiting async settlement (e.g. SEPA, bank transfer).
3	`EXPIRED`	Link validity period elapsed without payment.
4	`RELEASED`	Pre-authorization voided. Funds released back to customer.
5	`REFUNDED`	Fully refunded.
9	`PARTIALLY_REFUNDED`	Partially refunded.
10	`DECLINED`	Payment declined by the bank or PSP.
6	`TECHNICAL_ERROR`	PSP technical error during processing.
7	`DISPUTED`	Customer initiated a chargeback.
11	`TIMEOUT`	Payment attempt timed out.
12	`CANCELLED`	Cancelled by the customer or merchant.
16	`CHARGEBACK_ACCEPTED`	Chargeback accepted — funds returned to customer.

Terminal States

These statuses are final — no further transitions are possible:

SETTLED (unless refunded or disputed later)
EXPIRED
RELEASED
REFUNDED
DECLINED
TECHNICAL_ERROR
TIMEOUT
CANCELLED
CHARGEBACK_ACCEPTED

Checkout Availability

Customers can only access the checkout page in these statuses:

CREATED
OPENED
INITIALIZED

Once a payment reaches AUTHORIZED, SETTLED, or any terminal state, the checkout page is no longer accessible.

Monitoring Status Changes

Use webhooks to receive real-time notifications when a payment changes status. Polling the transaction endpoint is possible but not recommended for production use.

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

Refunds

Refunds can be full or partial, and only apply to SETTLED transactions:

curl -X POST https://app.roxpay.eu/api/v4/payments/refund \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "TransactionIds": ["a1b2c3d4-..."],
    "Amount": 1500
  }'

Omit Amount for a full refund.

Payment Lifecycle