If you have any questions or need help with the APIs, you can open a ticket on our support portal. Click on the button below to open a ticket.

As a Payment Service Provider (PSP), FlowPay is regulated by the Bank of Italy and we are authorised to provide payment services to our customers.

We believe that the best API a payment institution can provide is one that is tailored to the payment use case, allowing customers to focus on their business and not the payment process.

On the end user side, FlowPay ensures that users own their data, can access it at any time and fully manage it. They can choose which data to share with third parties in the most transparent way possible.

FlowPay welcomes contributions from partners. The OpenAPI file is publicly available on GitHub: FlowPay/client-openapi.

Partners can propose changes by forking the repository and submitting a pull request.

The APIs are REST over HTTPS. Some endpoints are restricted; partners must register their application and obtain an API key from the developer portal to access them. API keys can be rotated, scoped, and revoked at any time from the backoffice.

FlowPay is authorised to provide AIS. In the Simplified Flow model, consents are collected directly by FlowPay via a hosted flow to minimise partner burden.

Endpoints:

• POST /ais/consents: create a consent session; returns a link to complete SCA with the bank.
• GET /ais/consents/{consentId}: retrieve consent status (pending, active, expired, ...).
• GET /ais/accounts: list available bank accounts under active consents.
• GET /ais/accounts/{accountId}/balances: current and available balances.
• GET /ais/accounts/{accountId}/transactions: list transactions, filterable by date.

For field-level semantics, see the AIS schema descriptions in the OpenAPI file. In short: bookingDate is the booking/posting date, valueDate is the bank's effective/value date when provided, and category is best-effort transaction enrichment rather than a normalized taxonomy. On the consent side, canceled means the flow stopped before authorization, while revoked means an already-authorized consent was withdrawn.

If no active consent exists, AIS endpoints return 403 and partners can create a new consent using the consent endpoint.

When a consent session has expired, the consent-session PATCH operation can be used to re-arm it with a minimal body. Any field omitted in the request is inherited from the existing session, so callers only need to send the values they want to change.

FlowPay is an authorised PIS Provider (PISP). In the Simplified Flow, partners create Request To Pay objects and direct users to a hosted checkout to perform Strong Customer Authentication with their bank and authorise the payment.

APIs allow users to initiate traditional payment types:

• Simple account-to-account payment: user can initiate a SEPA Credit Transfer (SCT) payment from one of its bank accounts.
• Future date payment: the payer can schedule a payment for a future date.

In addition, FlowPay extends traditional payment methods by providing value-added services such as

• Bulk payment: payer can initiate a single payment with a single Strong Customer Authentication (SCA) to pay multiple payment requests or documents at once.
• Payment Chain: user can authorise an RTP that executes when admitted FlowPay funding operations have credited a dedicated technical position. See docs/payment_chain.md.
• Locked payment: the user can authorise a payment to be executed if a previous payment has been successfully received. The check is performed by the client application that initiated the payment request.

Each of these services may route funds via a FlowPay technical account when required by business rules, while preserving original payer/payee information in remittance data.

See checkout behavior, redirects, callbacks, and branding in docs/checkout.md.

Partners register their application in the developer portal (https://developer.flowpay.it) and obtain one or more API keys with configurable scopes. Keys can be rotated or revoked at any time. Access to the portal requires a company account enabled for FlowPay services.

FlowPay provides a sandbox environment to allow partners to test the APIs before going into production. The sandbox is a safe space where you can experiment with the APIs without affecting real accounts or transactions.

FlowPay APIs implement offset-based pagination on all list endpoints, following a standard response structure.

When requesting a paginated resource, the following query parameters are supported:

• limit (integer): the maximum number of items to return. Default is 50, maximum is 100.
• offset (integer): the number of items to skip before starting to return results.

Each paginated response follows the PaginatedResult format:

• total: total number of available items.
• limit: maximum number of items returned in this page (as requested).
• offset: number of items skipped from the beginning of the collection.
• count: number of items actually returned in this response.
• items: array of objects representing the current page results.

Request

### Request
GET /payment-requests?limit=20&offset=0
X-API-Key: {api_key}

Response

{
  "total": 147,
  "limit": 20,
  "offset": 0,
  "count": 20,
  "items": [
    {
      "id": "req_12345",
      "amount": 1000,
      "currency": "EUR",
      "created_at": "2024-06-01T10:00:00Z",
      "status": "created"
    }
  ]
}

This structure allows clients to calculate pagination UI and control navigation across multiple pages using offset and limit.

Requests are limited to 100 requests per minute per source IP; exceeding this limit results in 429 responses. A burst limit of 10 requests per second also applies. Production limits can be customised per partner on request.

Operations related to banks and supported payment methods.

Operations related to charges on tokenised methods.

Operations related to registered customers.

Operations related to managing files attached to payments.

Operations related to managing tokenised payment methods.

Operations related to payment refunds

This chapter explains how each Request To Pay (RTP) product works functionally: actors, lifecycle, routing, and constraints. Use it to understand behavior before jumping into payloads.

Simple RTP is the shortest path from a payment request to a successful bank transfer. Your backend creates a request that describes what the user is paying (title, description, remittance), who receives the funds (payee), and optional URLs for redirect and server‑to‑server callbacks. You receive a hosted checkout link where the user completes Strong Customer Authentication (SCA) with their bank. From the user’s perspective it’s a clean, guided flow; from your side you track status via callbacks and finalise your order by reading the request status from the API.

State evolution: a Simple RTP typically flows created → inProgress when the user starts checkout, then authorized on a successful SCA with the provider. Settlement goes straight to the payee (fast transition to forwarded); it passes through the Technical Account (onHold) only when the ultimateDebtor differs from the debtor (payer). User cancellations, OTP expirations, or bank denials keep the request non-terminal until a successful attempt occurs or the request expires. Refunds, when issued, move the request to refunded for the affected amount.

What it enables: one‑off payments, invoice settlement, donations, deposits, and any flow where a user authorises a bank transfer to a known beneficiary.

How to enable specific flavors (copy‑paste ready):

Fixed amount (default)

Set amount to the exact value you want to charge.

State evolution: most flows are linear. From created the first user attempt moves to inProgress; on a positive outcome the session is authorized and the request proceeds to forwarded. Settlement goes straight to the payee; the Technical Account (onHold) path applies only when ultimateDebtor ≠ debtor. Errors or cancellations do not change the aggregate state to terminal; a later successful attempt completes the flow. Post-settlement reversals are reflected as refunded.

BASE_URL="https://api.sandbox.flowpay.it/v2/"; API_KEY="sk_test_xxx"
curl -sS -X POST "$BASE_URL/payment-requests" -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" -d '{
  "payer": "+39 333 1234567",
  "title": "Invoice #1001",
  "description": "Settlement for invoice 1001",
  "remittanceInformation": "INV-1001",
  "amount": 49.90,
  "currency": "EUR",
  "redirectUrl": "https://merchant.example.com/return",
  "callbackUrl": "https://merchant.example.com/api/payment/callback"
}'

Open amount (donations or pay‑what‑you‑want)

Omit amount entirely to let the payer enter the amount at checkout. Keep allowPartialPayments at its default (false). Enforce your business rules (min/max) when processing callbacks or before fulfilling the order.

State evolution: identical to fixed-amount, with the value chosen during checkout. Expect multiple inProgress attempts as the payer can re-enter and adjust the amount; only attempts that reach authorized affect the financial outcome. Settlement behaves like Simple RTP (direct to payee; Technical Account hop only if ultimateDebtor ≠ debtor); any reversal is reflected as refunded.

BASE_URL="https://api.sandbox.flowpay.it/v2/"; API_KEY="sk_test_xxx"
curl -sS -X POST "$BASE_URL/payment-requests" -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" -d '{
  "payer": "+39 333 1234567",
  "title": "Donate to ACME Foundation",
  "description": "Thank you for your support",
  "remittanceInformation": "DON-2024-09",
  "currency": "EUR",
  "redirectUrl": "https://merchant.example.com/thank-you",
  "callbackUrl": "https://merchant.example.com/api/payment/callback"
}'

Optional: allow the payer to edit the remittance at checkout by setting allowRemittanceChange: true.

Partial settlement (multiple payments until total is reached)

Set allowPartialPayments: true and provide the target amount to be fully settled across one or more sessions.

State evolution: each successful session independently reaches authorized and then forwarded for its portion. The request remains non-terminal until the cumulative authorized amount meets the target; it can cycle back to inProgress for additional attempts. Temporary onHold/locked can appear per session when funds pause on the Technical Account. Once the target is covered, the request is effectively complete in forwarded. Refunds operate per session without reopening the request.

BASE_URL="https://api.sandbox.flowpay.it/v2/"; API_KEY="sk_test_xxx"
curl -sS -X POST "$BASE_URL/payment-requests" -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" -d '{
  "payer": "+39 333 1234567",
  "title": "Installments for Order #A2001",
  "description": "Pay in multiple steps",
  "remittanceInformation": "A2001",
  "amount": 300.00,
  "currency": "EUR",
  "allowPartialPayments": true,
  "redirectUrl": "https://merchant.example.com/return",
  "callbackUrl": "https://merchant.example.com/api/payment/callback"
}'

To compute the outstanding: list sessions with /payment-requests/{requestId}/sessions, sum succeeded amounts, and subtract from the target amount.

Scheduled execution (future date)

Set executionDate (ISO 8601). The user authenticates now; execution occurs at/after the scheduled time (bank support dependent).

State evolution: after inProgress and authorized, the request remains pending execution until the scheduled time. You will not see forwarded until the bank executes. If execution fails or is revoked, the provider emits a negative outcome and the request converges to rejected. Refunds are available only after execution.

BASE_URL="https://api.sandbox.flowpay.it/v2/"; API_KEY="sk_test_xxx"
EXEC_AT="2025-01-10T10:00:00Z" # choose your date/time (UTC)
curl -sS -X POST "$BASE_URL/payment-requests" -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" -d '{
  "payer": "+39 333 1234567",
  "title": "Scheduled payment",
  "description": "Executes later",
  "remittanceInformation": "SCH-10JAN",
  "amount": 120.00,
  "currency": "EUR",
  "executionDate": "'"$EXEC_AT"'",
  "redirectUrl": "https://merchant.example.com/return",
  "callbackUrl": "https://merchant.example.com/api/payment/callback"
}'

Bulk turns many payouts into a single user authorisation. You compute a total amount and provide the allocation list with additional payees. The user performs SCA once; FlowPay collects the total and then splits it to the designated beneficiaries.

What it enables: mass invoice runs, bill aggregation, marketplace or platform settlements with a single frictionless checkout. Repeated beneficiaries in your allocation are grouped automatically. Keep allowPartialPayments disabled; if the sum of additional payees is less than the total, the remainder goes to the primary payee.

Mixed bulk can combine ordinary and locked movements. Set lockedUntil on an individual additionalPayees item to hold only that movement. A top-level lockedUntil applies only to the positive residual amount assigned to the main payee; it is not propagated to the additional payees, and the aggregate root remains a bulk request. Locked movements are not supported for split requests (ultimateDebtor: payee).

State evolution: authorization is single from the user’s perspective and the aggregate funding first lands on the Technical Account. After that collection is reconciled, ordinary movements follow the normal bulk dispatch flow. Each locked movement is instead funded into its own dedicated locked wallet and remains independent until early release, refund, or automatic release at its own lockedUntil. The aggregate can remain onHold while the collection is being reconciled and does not introduce a separate aggregate locked state for mixed or all-locked bulks.

When outcomes depend on a later verification (delivery, inspection, return window, milestone approval), use Locked payments. You specify a lockedUntil date; after a successful checkout the funds are held on FlowPay’s technical perimeter and attributed to a dedicated technical wallet for that operation. Before the date, the partner may release the funds to the beneficiary or refund the payer. If no earlier decision is taken, FlowPay automatically releases the funds to the beneficiary at lockedUntil.

What it enables: escrow‑like experiences, milestone‑based projects, dispute/return windows, and any flow where the partner needs immediate authorization but delayed availability to the beneficiary.

State evolution: after a successful checkout the session is authorized, may pass briefly through onHold while funds are reconciled, and then enters locked. From that state the partner may release early to the beneficiary or refund the payer. If no explicit action is taken, expiry leads to forwarded through automatic release. Additional user attempts do not alter funds that are already locked.

Split payment directs portions of a single checkout to different parties — for example, retaining a platform fee while paying a vendor. You define a primary payee and one or more additional payees with explicit amounts. The platform collects once and allocates the proceeds accordingly, preserving the original payer identity for beneficiaries.

What it enables: marketplaces, app stores, franchise models, partner revenue sharing with full transparency in remittances.

State evolution: similar to Bulk, the user authorizes once and funds always pass via the Technical Account, are processed immediately, and re-forwarded according to the split. The request may show a short onHold during dispatch, then advances to forwarded. Errors on outbound legs are handled by the dispatch engine and do not return the request to inProgress. Refunds mirror the original allocation proportions.

Payment Chain lets a partner create an RTP whose execution depends on funds expected later. The chain subject is the RTP payer and, when specified, the RTP debtor; the payout destination is defined by payee and, for split or bulk scenarios, additionalPayees.

What it enables: chained settlement, supplier or platform payouts funded by expected incoming FlowPay payments, convergence of multiple funding operations into one controlled technical position, and automatic execution of the RTP after the request amount is funded.

State evolution: the chain is created with the standard Request To Pay API and paymentMethod set to chain. After authorization it moves to authorized; once admitted funds arrive it uses onHold while FlowPay reconciles balance, amount, deadline, excesses, and operational conditions. When the reconciled balance reaches the RTP amount, FlowPay forwards the RTP payout to payee and additionalPayees. If the amount is not reached within the operational window, available funds are liquidated to the payer/debtor or the request is rejected if no valid liquidation path exists.

Detailed examples, lifecycle diagrams, and callback handling are documented in Payment Chain.

For public‑service payments in the Italian PagoPA ecosystem, RTP integrates a dedicated branch. You provide the entity tax code and payment notice number, and an email to receive the receipt. The hosted checkout guides the user through the PagoPA‑specific steps, while your integration pattern (redirects, callbacks, receipt download) remains the same.

What it enables: PagoPA notice payments with consistent checkout and server‑side integration semantics. Bulk isn’t natively supported with PagoPA; contact FlowPay for options.

State evolution: follows PagoPA’s own flow as defined in the Simplified Flow document. The request goes created → inProgress during the PagoPA journey, then to authorized on a positive PagoPA outcome, and to forwarded once remittance to the Creditor Entity completes. Invalid notices or cancellations converge to rejected. No Technical Account hop is used unless explicitly mandated by PagoPA reconciliation policies.

How to enable PagoPA payment

Provide the PagoPA‑specific fields (pagopaEcFiscalCode, pagopaPaymentNotice, email) alongside your standard request data.

BASE_URL="https://api.sandbox.flowpay.it/v2/"; API_KEY="sk_test_xxx"
curl -sS -X POST "$BASE_URL/payment-requests" -H "Content-Type: application/json" -H "X-API-Key: $API_KEY" -d '{
  "payer": "+39 333 1234567",
  "title": "PagoPA payment",
  "description": "PagoPA notice 1234567890",
  "remittanceInformation": "PPA-123",
  "amount": 49.90,
  "currency": "EUR",
  "redirectUrl": "https://merchant.example.com/return",
  "callbackUrl": "https://merchant.example.com/api/payment/callback",
  "pagopaEcFiscalCode": "01234567890",
  "pagopaPaymentNotice": "123456789012345678",
  "email": "payer@example.com"
}'

This section explains the lifecycle of a payment request as defined in the Simplified Flow document. The payment goes through well-defined states from creation to completion or termination.

• created: request created and visible to the user.
• inProgress: user starts a session and authenticates with the provider.
• authorized: provider confirms a positive outcome for the operation.
• rejected: provider rejects/cancels the operation.
• onHold: funds are on the FlowPay technical account (TA) awaiting dispatch rules.
• locked: funds have been reconciled on the dedicated technical wallet and are waiting for partner release, refund, or automatic release at lockedUntil.
• forwarded: funds dispatched to the beneficiaries, including automatic release at lockedUntil for locked payments.
• refunded: refund executed for the transaction; in locked flows this is the explicit alternative final outcome to release.
• deleted: request removed by the partner (only if not in progress and not paid).

Final states are: deleted, forwarded, rejected, refunded.

This chapter collects hands‑on Request To Pay (RTP) examples and the technical explanation of how each use case works end‑to‑end. It covers actors, data fields, settlement paths, and status lifecycles so you can reason about behavior beyond the JSON payloads.

• Actors: payer (user initiating payment), payee (final beneficiary), optional debtor (if different from payer).
• Flow: your backend creates a payment request and receives a hosted link. The user completes SCA with their bank at checkout. FlowPay sends callbackUrl events and redirects the user to redirectUrl with ?status.
• Security: authenticate API calls with X-API-Key.
• Settlement: funds are transferred from the payer’s bank to the configured payee IBAN. If no payee is provided, the partner’s default configuration is used.
• Status: the request follows the Payment State Machine (created → inProgress → authorized → onHold/locked → forwarded or terminal rejected/refunded/deleted). Inspect attempts with /payment-requests/{requestId}/sessions (session statuses: succeeded, pending, expired, failed, cancelled).

Inline example (Sandbox):

1. Create a payment request and get requestId + link.

BASE_URL="https://api.sandbox.flowpay.it/v2/"
API_KEY="sk_test_xxx" # replace with yours

curl -sS -X POST "$BASE_URL/payment-requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "payer": "+39 333 1234567",
    "title": "Order #A1001",
    "description": "Payment for order A1001",
    "remittanceInformation": "A1001",
    "amount": 49.90,
    "currency": "EUR",
    "redirectUrl": "https://merchant.example.com/checkout/return",
    "callbackUrl": "https://merchant.example.com/api/payment/callback"
  }'

2. Redirect the customer to the returned link to complete payment.

Verify and download receipt:

REQUEST_ID="..."

curl -sS -X GET "$BASE_URL/payment-requests/$REQUEST_ID" -H "X-API-Key: $API_KEY"

curl -sS -X GET \
  -H "X-API-Key: $API_KEY" \
  -H "Accept: application/pdf" \
  "$BASE_URL/payment-requests/$REQUEST_ID" \
  -o receipt.pdf

3. Treat the callbackUrl as the primary source of truth; use the APIs for on‑demand confirmation.

• Goal: distribute a single user payment across multiple beneficiaries (e.g., platform fee + vendor payout).
• Data model: set total amount, primary payee, and an array of additionalPayees with their individual amounts. The remainder flows to the primary payee.
• Settlement: the payer authorises once; funds are collected and then allocated. When multiple beneficiaries are involved, settlement routes via FlowPay’s Technical Account and fans out to beneficiaries (grouped by IBAN+name), preserving the original payer in remittance.
• Constraints: Sum(additionalPayees.amount) ≤ amount. Do not combine additionalPayees with allowPartialPayments=true.

How to enable Split payment

Set the total amount, define a primary payee, and list additionalPayees with their explicit amounts. Keep allowPartialPayments set to false. Ensure the sum of all additionalPayees.amount is less than or equal to the total; the remainder goes to the primary payee.

BASE_URL="https://api.sandbox.flowpay.it/v2/"
API_KEY="sk_test_xxx"

curl -sS -X POST "$BASE_URL/payment-requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "payer": "+39 333 1234567",
    "title": "Order #SP-1001",
    "description": "Split payment",
    "remittanceInformation": "SP-1001",
    "amount": 100.00,
    "currency": "EUR",
    "redirectUrl": "https://merchant.example.com/return",
    "callbackUrl": "https://merchant.example.com/api/payment/callback",
    "payee": { "name": "ACME Vendor", "iban": "IT60X0542811101000000123456" },
    "additionalPayees": [
      { "amount": 5.00, "name": "Platform Fee", "iban": "IT60X0542811101000000654321" }
    ],
    "allowPartialPayments": false
  }'

Notes:

• Use remittanceInformation to correlate the whole order across all beneficiaries.
• Refunds operate per successful session; maintain your allocation map for proportional refunds if needed.

• Goal: escrow‑like behavior with optional early release and deterministic automatic release at expiry.
• Data model: add lockedUntil (ISO 8601) at creation time. The beneficiary must be identified before authorization; final payout coordinates may already be known at creation time or completed later before release.
• Lifecycle: after successful collection, funds are reconciled and the request enters locked. Before expiry you may retrieve the dedicated locked payment method and release the funds through POST /charges, or refund the payer through POST /refunds. If no explicit action is taken, FlowPay automatically releases the funds to the beneficiary at lockedUntil.

How to enable Locked payment

Add lockedUntil (ISO 8601). After reconciliation, use GET /payment-requests/{requestId} to retrieve lockedDetails.lockedPaymentMethod.id. The webhook payload exposes the same technical method as payload.paymentMethod.id. Before expiry, either release the funds with POST /charges or refund the payer with POST /refunds.

BASE_URL="https://api.sandbox.flowpay.it/v2/"
API_KEY="sk_test_xxx"
LOCK_UNTIL=$(date -u -v+3d +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "+3 days" +"%Y-%m-%dT%H:%M:%SZ")

curl -sS -X POST "$BASE_URL/payment-requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "payer": "+39 333 1234567",
    "title": "Escrow order #L-2001",
    "description": "Locked until verification",
    "remittanceInformation": "L-2001",
    "amount": 59.00,
    "currency": "EUR",
    "redirectUrl": "https://merchant.example.com/return",
    "callbackUrl": "https://merchant.example.com/api/payment/callback",
    "payee": { "name": "ACME Vendor", "iban": "IT60X0542811101000000123456" },
    "lockedUntil": "'"$LOCK_UNTIL"'"
  }'

Early release example:

REQUEST_ID="..." # from create response or callback

LOCKED_TOKEN_ID=$(curl -sS -X GET "$BASE_URL/payment-requests/$REQUEST_ID" \
  -H "X-API-Key: $API_KEY" | jq -r '.lockedDetails.lockedPaymentMethod.id')

curl -sS -X POST "$BASE_URL/charges" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "tokenId": "'"$LOCKED_TOKEN_ID"'",
    "payee": {
      "name": "ACME Vendor",
      "iban": "IT60X0542811101000000123456"
    },
    "remittanceInformation": "L-2001 RELEASE"
  }'

Refund example (alternative final outcome):

SESSION_ID="..." # locked collection session id from sessions or callback

curl -sS -X POST "$BASE_URL/refunds" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "sessionId": "'"$SESSION_ID"'",
    "amount": 59.00,
    "reason": "other"
  }'

Notes:

• Locked payments are all-or-nothing: the release amount is implicit in the locked token and matches the original locked amount; refunds are documented for the full amount only.
• If the final payee coordinates were not already available, provide them in the payee field of the locked release payload before expiry.
• Treat callbackUrl as the primary orchestration signal and use GET /payment-requests/{requestId} as the recovery path if a webhook is missed.

• Goal: let a user pay many targets with a single SCA (single checkout), reducing friction.
• Data model: same allocation primitives as split (additionalPayees) but used for larger lists; total amount equals the sum of all components intended for beneficiaries.
• Settlement: FlowPay’s Technical Account receives the total, then issues outgoing wires by allocation, grouping repeated entries (same IBAN+name). The original payer is preserved in remittance data to ease reconciliation.

How to enable Bulk payments

Compute the total amount as the sum of all components, set the primary payee, and provide the allocation list in additionalPayees. Keep allowPartialPayments set to false. Repeated beneficiaries are allowed; FlowPay groups them by IBAN+name during settlement.

BASE_URL="https://api.sandbox.flowpay.it/v2/"
API_KEY="sk_test_xxx"

curl -sS -X POST "$BASE_URL/payment-requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "payer": "+39 333 1234567",
    "title": "Bulk order #B-9001",
    "description": "Bulk payout to A,B,C",
    "remittanceInformation": "B-9001",
    "amount": 250.00,
    "currency": "EUR",
    "redirectUrl": "https://merchant.example.com/return",
    "callbackUrl": "https://merchant.example.com/api/payment/callback",
    "payee": { "name": "Beneficiary A", "iban": "IT79Q0300203280941591243326" },
    "additionalPayees": [
      { "amount": 50, "name": "Beneficiary B", "iban": "IT79Q0300203280941591243327" },
      { "amount": 25, "name": "Beneficiary C", "iban": "IT79Q0300203280941591243328" },
      { "amount": 75, "name": "Beneficiary A", "iban": "IT79Q0300203280941591243326" }
    ],
    "allowPartialPayments": false
  }'

Notes:

• Combine with attachments for richer payer context (e.g., PDF invoice).
• Rely on callbackUrl + GET /payment-requests/{id} for authoritative status.

• Two kinds of attachments: attachments (visible to payer at checkout) and privateAttachments (compliance‑only, not shown to payer).
• Upload options: multipart/form‑data (preferred) or JSON with base64 data.
• Receipt: GET /payment-requests/{requestId} with Accept: application/pdf returns a PDF with details and a QR for device handoff; if paid, it acts as a receipt.

BASE_URL="https://api.sandbox.flowpay.it/v2/"
API_KEY="sk_test_xxx"

# Upload (multipart)
FILE_ID=$(curl -sS -X POST "$BASE_URL/files" -H "X-API-Key: $API_KEY" -F "file=@./invoice.pdf;type=application/pdf" | jq -r .id)

# Create RTP with attachments
curl -sS -X POST "$BASE_URL/payment-requests" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "payer": "+39 333 1234567",
    "title": "Order #A1002",
    "description": "Payment with attachment",
    "remittanceInformation": "A1002",
    "amount": 129.00,
    "currency": "EUR",
    "redirectUrl": "https://merchant.example.com/checkout/return",
    "callbackUrl": "https://merchant.example.com/api/payment/callback",
    "attachments": ["'"$FILE_ID"'"]
  }'

# Download receipt (PDF)
REQUEST_ID="..."
curl -sS -X GET -H "X-API-Key: $API_KEY" -H "Accept: application/pdf" "$BASE_URL/payment-requests/$REQUEST_ID" -o receipt.pdf