Skip to main content

App connections

A Hubpay app connection lets a partner act on behalf of a customer that has explicitly granted them access. The partner creates a connection request scoped to exactly what it needs; the customer approves it from the Hubpay Business app; and from then on the partner can make scoped requests on that customer's behalf until the connection is revoked.

Partners use app connections to access a customer's Hubpay account without handling the customer's login credentials.

Use this model for multi-tenant software that serves independent Hubpay customers. If one business is connecting its own ERP, CRM or finance platform using credentials it controls, start with Banking and money movement instead.

Connection lifecycle​

Steps​

Step 1: Create a connection request​

Call Create connection with the scopes your integration needs. The request carries no Hubpay customer identifier: at this point there is no connected customer yet, so the partner is acting purely as itself.

The request accepts:

  • scopes: the scopes your integration needs (at least one).
  • accountEmail (optional): the email the customer uses with your product. If supplied, it may be used to help confirm the right customer is approving the connection.

The response contains:

  • connectionId: the identifier for this connection.
  • token and deepLink: hand the deep link to the customer to complete the connection.
  • expiresAt: when the token expires if the customer does not act in time.

Step 2: Customer approves the connection​

Direct the customer to the deepLink. It opens the Hubpay Business app, where the customer reviews the requested scopes and approves or declines. On approval the connection moves to ACTIVE.

Track the outcome by polling Get connection until the status is no longer PENDING.

Step 3: Act on the customer's behalf​

Once the connection is ACTIVE, the partner can make requests on behalf of the connected customer, limited to the scopes that were granted. These on-behalf-of requests identify the customer with the AccountId header set to the customerAccountId returned on the active connection. Connection-management calls do not carry an account header.

Managing connections​

  • List connections: review every connection the partner owns and its current status.
  • Revoke connection: end a connection the partner owns. The connection moves to REVOKED and on-behalf-of access stops.

Scopes​

A connection grants only the scopes the partner requested and the customer approved.

ScopeGrants
WALLET_BALANCE_READRetrieve the customer's account balances.
FUNDING_ACCOUNT_READRetrieve the customer's funding account details by currency.
COLLECTIONS_WRITECreate and manage payers and payment requests (collections) on the customer's behalf.

Transaction-feed and payment-initiation grants are planned but cannot yet be requested.

Account linking is not SSO​

An app connection authorises access to account data and actions. It does not sign the customer into your product and should not be described as OAuth login, OpenID Connect or SSO.

If the same integration also needs enterprise SSO, design that as a separate identity flow. Keep the Hubpay connection as the customer consent and authorisation layer.

For a customer that does not yet have a Hubpay account, complete business account onboarding before creating the connection.

Connection statuses​

StatusMeaning
PENDINGRequest created; waiting for the customer to approve in the Hubpay Business app.
ACTIVECustomer approved. The partner can make scoped requests on the customer's behalf.
DECLINEDCustomer declined the request.
REVOKEDThe connection was ended by the partner or the customer.
EXPIREDThe customer did not act before the token expired.