Workflows

Workflows are the orchestration layer of a PISP. Each workflow drives a single use-case from start to finish: it advances the payment state machine, calls the bank connector when it is time to move money, sends inter-PISP protocol messages, and triggers notifications to requesters.

Workflows sit between the counterparty interface layer and the data/bank connectivity layer. They do not know about HTTP request objects or response formats, and they do not know which bank or integration is behind the bank connector.

Workflow	Description
Payments	Standard payment — payer scans a URI, consents, funds transfer
Mandates	Pre-authorised recurring payments without interactive payer consent
Future-dated payments	Payments scheduled for a future value date
Refunds	Requester-initiated refund against a settled payment
Disputes	Three-stage dispute resolution between payer, requester, and SA

---

Payment URI resolution

Before a payment request enters the inter-PISP protocol, the requester PISP resolves an opaque payment URI into a concrete, immutable payment request. This resolution step is entirely internal to the requester PISP — the payer PISP never sees it, and the protocol makes no assumptions about how it works.

The only protocol invariant is: by the time a PAYMENT_REQUEST message is sent, the payment request is fixed. Amount, creditor account, and reference cannot change after that point.

What happens before that point is the requester PISP's product decision. See Payment URI resolution for a discussion of the range of policies a requester PISP might implement.

---

Expiry and cleanup

Payment requests that reach their expiry time without settling must be moved to EXPIRED. A background process is responsible for this:

1. Periodically scans for payments in non-terminal states with expires_at < now.
2. Advances each to EXPIRED.
3. Sends PAYMENT_FAILED with REQUEST_EXPIRED to the payer PISP (if one is known).
4. Fires the requester notification.

The dispute Stage 1 deadline follows the same pattern: disputes that have not received a merchant proposal within the scheme-defined window are automatically escalated to Stage 2.

---

Idempotency

Workflows must handle duplicate messages and retries correctly:

• Duplicate CONSENT_CONFIRMED: accept only if the payment is in CREATED or ACKNOWLEDGED state; drop silently otherwise.
• Duplicate SETTLEMENT_CONFIRMED: accept only in CONSENTED or DISPATCHED state; treat as a no-op if already SETTLED.
• Webhook replay: check payment status before advancing — already-settled payments are acknowledged without reprocessing.

When a workflow step fails after a state transition has already been committed, the payment stays in its intermediate state. The next retry should detect the current state and continue from there rather than starting over.