Payment Application Prerequisites

POS Hub payment applications provide a hosted payment page while POS Hub owns provider selection, normalized payment state, reconciliation, cancellation, refunds, and lifecycle events.

There are two application roles in a payment flow:

• A creator application creates a payment through the POS Hub API and sends the customer to the returned paymentLink.
• A payment application is the selected provider integration. POS Hub calls its HTTPS endpoints and the application reports the provider's source-of-truth state back to POS Hub.

This guide focuses on building the payment application.

Application setup

Create an application in the POS Hub developer area with category set to PAYMENT. See Create Application and Application Anatomy for the general setup.

Configure all four HTTPS endpoints before connecting the application to a location:

Application field	Responsibility
createPaymentUrl	Create a provider payment and return a hosted payment link.
getPaymentUrl	Return the latest provider-owned payment state.
cancelPaymentUrl	Cancel an unpaid provider payment or explicitly acknowledge a POS Hub-only cancellation.
refundPaymentUrl	Create a full or partial refund and return its result.

POS Hub signs calls to these endpoints with the application's secret in X-Webhook-Signature. Each endpoint must:

• use HTTPS without redirects;
• accept POST requests with Content-Type: application/json;
• verify the signature against the exact raw request body before parsing it;
• return within 10 seconds; and
• be idempotent for the POS Hub payment or refund identifier.

The Developer Guide defines each request and response.

Permissions

Request only the payment scopes the application needs:

Scope	Used for
payments.read	Read an assigned payment or reconcile its current POS Hub state.
payments.write	Report provider-owned status and reference fields with PATCH.
payments.cancel	Request a controlled cancellation when acting as a payment creator.
payments.refund	Request a controlled refund when acting as a payment creator.

Provider callbacks are authenticated by their HMAC signature. Calls from the payment application to the POS Hub API use an OAuth2 access token; see Authentication.

Connect and rank the application

The payment application must have a COMPLETED connection to the location. A location can then select providers with:

• paymentApplicationSelectionStrategy: "RANK";
• paymentApplicationSelectionRanking: the ordered application IDs, with a maximum of three; and
• paymentApplicationFailoverEnabled: whether POS Hub may try the next ranked application after an explicitly safe failure.

If exactly one valid payment application is connected, an explicit ranking is optional. When multiple payment applications are connected, the ranking must include every valid application exactly once. Stale, duplicate, partial, or invalid rankings stop payment initialization.

Failover safety

Only return failoverSafe: true when you can prove that no provider payment was created. A timeout or an ambiguous provider result must remain UNKNOWN; creating the payment with another provider could otherwise charge the customer twice.

Hosted-payment boundary

POS Hub stores references, customer contact details, amount, currency, and provider-neutral state. The payment application hosts the customer-facing payment page and owns all provider credentials and payment-method data.

Do not send PAN, CVV, bank credentials, access tokens, or other payment secrets to POS Hub in metadata, provider status fields, errors, or logs. The creator's returnUrl is retained by POS Hub and is not included in requests to the payment application.

Before development

You should have:

1. A SIT developer account and PAYMENT application.
2. Four reachable HTTPS endpoints.
3. Secure access to the application secret for signature verification.
4. OAuth2 client credentials and the required payment scopes.
5. A completed location connection and valid provider ranking.
6. A provider sandbox account and test credentials.

Continue with the Payment Integration Flow, then implement the callbacks using the Payment Application Developer Guide.