Payment Integration Flow

POS Hub is the provider-neutral payment ledger. The selected payment application remains the source of truth for provider state and translates that state into POS Hub statuses.

Payment creation

The creator sends an amount in the currency's minor unit, its external order reference, and customer details. currency may be omitted and defaults to the selected location's currency. The creator may also send a POS Hub orderId; when present, POS Hub verifies that the order exists in the selected location before accepting the payment. POS Hub stores the payment before calling a provider so every attempt has a durable audit trail.

The payment application must return PENDING and an HTTPS paymentLink after the provider payment is created. The creator should persist the POS Hub payment.id and use the returned link for the hosted customer journey.

Provider selection and failover

POS Hub selects connected payment applications in the location's configured rank order. Up to three applications can be attempted when failover is enabled.

Timeouts, network failures, malformed success responses, and responses that do not explicitly prove failure are ambiguous. POS Hub records UNKNOWN and does not try another provider.

Status updates and reconciliation

The provider translates its native states into the normalized model:

FAILED, CANCELLED, and REFUNDED are terminal. PARTIALLY_REFUNDED and REFUNDED are derived by POS Hub from confirmed refund results; they are not provider PATCH values.

Use two complementary update paths:

• Push: after receiving a provider webhook, the selected payment application calls the account payment PATCH endpoint.
• Reconciliation: POS Hub calls getPaymentUrl when a consumer requests consistentRead=true and before a cancellation or refund.

UNKNOWN means the outcome could not be proved, not that the payment failed. Reconcile it with the provider before permitting another customer attempt.

Cancellation

Cancellation is controlled through the POS Hub cancellation endpoint. The creator application or an authorised operations user requests it; consumers must not simulate cancellation with a payment PATCH.

POS Hub first reconciles the payment, then calls cancelPaymentUrl. A payment application that completes provider-side cancellation returns a final CANCELLED result and the provider's final status.

When the provider has no cancellation operation, the application can acknowledge a POS Hub-only cancellation with status: "CANCELLED" and externalProviderStatus: "CANCELLATION_NOT_SUPPORTED". This makes POS Hub terminally cancelled but does not disable the provider's hosted payment link. The application and operations team must account for that risk explicitly.

If neither provider-side nor POS Hub-only cancellation is appropriate, return the explicit CANCELLATION_NOT_SUPPORTED error. Ambiguous cancellation results move the payment to UNKNOWN.

Already FAILED or CANCELLED payments return idempotently. A captured or refunded payment cannot be cancelled.

Refunds

Refund amounts are positive minor-unit integers and cannot exceed the remaining refundable amount. POS Hub permits refunds only from SUCCEEDED or PARTIALLY_REFUNDED and counts only confirmed SUCCEEDED refunds toward refundedAmount.

Lifecycle events

POS Hub emits redacted PAYMENT_INSERT and status-changing PAYMENT_MODIFY events to the reseller and the creator application's webhook, subject to its enabled webhook events. Customer details, the hosted payment link, return URL, and metadata are not included.

The updatedBy field suppresses an event to the application that made the change. A payment application should therefore treat a successful PATCH response as acknowledgement and must not wait for its own change to be echoed back. See Webhooks for delivery and signature handling.