Payment Links

Payment links are the primary way to accept payments with RoxPay. A payment link generates a hosted checkout page where your customer can pay using cards, SEPA Direct Debit, or Pay by Bank — depending on your configuration.

Creating a Payment Link

POST /api/v4/payments/link

Minimal Example

curl -X POST https://app.roxpay.eu/api/v4/payments/link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Purpose": "Order #12345",
    "Amount": 2999,
    "SuccessRedirectUrl": "https://yourshop.com/success",
    "FailureRedirectUrl": "https://yourshop.com/failure",
    "CancelRedirectUrl": "https://yourshop.com/cancel"
  }'

Response

{
  "Message": "Well done! Paylink correctly created.",
  "StatusCode": 200,
  "Result": true,
  "TransactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "PaymentUrl": "https://app.roxpay.eu/payments/en/general/checkout/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ExpirationDate": "2026-08-21 23:59:59"
}

Redirect your customer to PaymentUrl to complete the payment.

---

Request Fields

Required Fields

Field	Type	Description
Purpose	string	Payment description shown to the customer. Max 450 characters.
Amount	integer	Amount in minor units (cents). E.g. 2999 = €29.99. Range: 1–10,000,000.
SuccessRedirectUrl	string	HTTPS URL where the customer is redirected after successful payment.
FailureRedirectUrl	string	HTTPS URL for failed payments.
CancelRedirectUrl	string	HTTPS URL when the customer cancels.

Optional Fields

Field	Type	Default	Description
Title	string	—	Checkout page title. Max 450 chars.
Description	string	—	Longer description shown on checkout. Max 450 chars.
Notes	string	—	Internal notes (not shown to customer). Max 1500 chars.
Currency	string	"EUR"	One of: EUR, USD, GBP, CHF, CAD, RON, JPY.
Providers	string[]	["RoxDirect"]	Payment providers to offer. See Providers.
AutoCapture	boolean	true	false = pre-authorization (funds held, not captured).
Moto	boolean	false	Mail/Telephone Order — disables 3D Secure. Requires company permission.
TransactionId	string	auto-generated	Your reference ID. Max 30 chars. Must be unique per company.
Type	string	"standard"	"standard" or "embedded". See Embedded Checkout.
LinkDurationSeconds	integer	30 days	Link validity in seconds. Range: 1–7,776,000 (90 days).
Lang	string	auto-detected	Checkout language: en, it, fr, de, es, ru, tr, pl, ro, cz, hu, il, kr.
WebhookUrl	string	—	Per-link HTTPS webhook URL (overrides company default).
ShopperStatement	string	—	Text on the customer's bank statement. Max 22 chars.
StoreReference	string	—	Must match an active store in your account.
DebtorFiscalCode	string	—	Italian fiscal code (16 chars) or VAT number (11 digits).
SendConfirmationEmail	boolean	false	Email the customer when payment completes.
HideEmailInput	boolean	false	Remove the email field from checkout.
AllowTokenization	boolean	true	Allow saving the card for future payments.
Metadata	object	—	Custom key-value pairs. See Metadata.
Items	array	[]	Line items. See Line Items.
PaymentMethods	string[]	—	Restrict payment methods: VIS, ECA, SEPA, BANK.
SubscriptionOnCompletion	object	—	Create a subscription after payment. See Subscriptions.

---

Providers

The Providers field controls which payment methods are available on the checkout page.

Provider	Methods	Notes
RoxDirect	Cards (Visa, Mastercard, etc.), SEPA, Pay by Bank	Default. RoxPay direct payment provider.
FlowPay	Bank transfer	Requires fiscal code + IBAN on file.
Fabrick	Open banking (PIS)	Requires synced IBAN.

You can offer multiple providers on a single link:

{
  "Providers": ["RoxDirect", "FlowPay"],
  "Purpose": "Invoice #9876",
  "Amount": 15000,
  "SuccessRedirectUrl": "https://yourshop.com/success",
  "FailureRedirectUrl": "https://yourshop.com/failure",
  "CancelRedirectUrl": "https://yourshop.com/cancel"
}

The customer will see a provider selection step on the checkout page.

---

Line Items

Provide an itemized breakdown of the payment. The sum of all items must equal the Amount.

{
  "Amount": 5998,
  "Items": [
    {
      "Name": "Widget Pro",
      "Quantity": 2,
      "UnitPrice": 2499,
      "VatRate": 22,
      "VatCode": "22"
    },
    {
      "Name": "Shipping",
      "Quantity": 1,
      "UnitPrice": 1000,
      "VatRate": 22,
      "VatCode": "22"
    }
  ]
}

Field	Type	Required	Description
Name	string	Yes	Item name.
Quantity	integer	Yes	Quantity (1–100).
UnitPrice	integer	Yes	Price per unit in cents.
VatRate	number	Yes	VAT percentage (e.g. 22 for 22%).
VatCode	string	Yes	VAT code identifier.

Constraints:

• 1 to 100 items per link
• SUM(Quantity × UnitPrice) must equal Amount

---

SEPA Direct Debit

To offer SEPA on a payment link, include SEPA in PaymentMethods and provide debtor details:

{
  "Providers": ["RoxDirect"],
  "PaymentMethods": ["SEPA"],
  "DebtorIban": "IT60X0542811101000000123456",
  "DebtorName": "Mario Rossi",
  "Purpose": "Monthly subscription",
  "Amount": 1999,
  "Currency": "EUR",
  "SuccessRedirectUrl": "https://yourshop.com/success",
  "FailureRedirectUrl": "https://yourshop.com/failure",
  "CancelRedirectUrl": "https://yourshop.com/cancel"
}

Constraints:

• SEPA is EUR-only
• DebtorIban and DebtorName are required when SEPA is selected
• AutoCapture must be true

---

Metadata

Attach custom data to a payment link. Metadata is returned in webhook payloads and visible in the dashboard.

{
  "Metadata": {
    "order_id": "ORD-2026-001",
    "customer_segment": "premium",
    "custom_css": "https://yourshop.com/checkout-theme.css"
  }
}

Reserved Keys

These keys are used internally and should not be set:

Key	Purpose
transaction_uuid	Internal transaction identifier
company_id	Company identifier
invoice_id	Linked invoice
accepted_cards	Card brand configuration
custom_css	Custom checkout stylesheet URL
moto	MOTO flag
sepa_only	SEPA-only flag
bank_only	Pay by Bank flag

---

Validation Rules

The API enforces strict validation. Common rejection reasons:

Rule	Error
Redirect URLs must use HTTPS	"URL must use HTTPS protocol."
Redirect URL domain must be whitelisted	"Domain not authorized."
TransactionId must be unique	"Transaction already exists."
Provider must be active for your company	"Provider not available."
Amount must be > 0 and ≤ 10,000,000	"Amount out of range."
Line items sum must equal Amount	"Items total does not match amount."
MOTO requires company permission	"MOTO not enabled for this company."
SEPA requires EUR currency	"SEPA is only available for EUR."

---

Full Example

A complete payment link with all common options:

curl -X POST https://app.roxpay.eu/api/v4/payments/link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Purpose": "Order #12345 - Premium Plan",
    "Title": "Complete your purchase",
    "Description": "Premium Plan - Annual subscription",
    "Amount": 29900,
    "Currency": "EUR",
    "Providers": ["RoxDirect"],
    "AutoCapture": true,
    "TransactionId": "ORD-2026-12345",
    "Type": "standard",
    "Lang": "it",
    "LinkDurationSeconds": 86400,
    "ShopperStatement": "ROXPAY PREMIUM",
    "SendConfirmationEmail": true,
    "AllowTokenization": true,
    "SuccessRedirectUrl": "https://yourshop.com/success?order=12345",
    "FailureRedirectUrl": "https://yourshop.com/failure?order=12345",
    "CancelRedirectUrl": "https://yourshop.com/cancel?order=12345",
    "WebhookUrl": "https://yourshop.com/api/webhooks/roxpay",
    "Metadata": {
      "order_id": "12345",
      "plan": "premium-annual"
    },
    "Items": [
      {
        "Name": "Premium Plan (Annual)",
        "Quantity": 1,
        "UnitPrice": 29900,
        "VatRate": 22,
        "VatCode": "22"
      }
    ]
  }'

---

Pre-Authorization

Set AutoCapture: false to hold funds without capturing. You can later capture or release:

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

# Release (void)
curl -X POST https://app.roxpay.eu/api/v4/payments/release \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "TransactionIds": ["a1b2c3d4-..."] }'

See Payment Lifecycle for the full status flow.