Overview

The SportsPay Onboarding API enables Partners to programmatically create, update, and track merchant onboarding applications. It supports both embedded (immersive) and invite-only onboarding experiences.

Onboarding is responsible for:

• Collecting merchant application data
• Presenting pricing offers (offerID)
• Managing application lifecycle states
• Sending status webhooks

Onboarding is not responsible for:

• Creating gateway credentials
• Creating terminals (termID)
• Delivering transaction credentials

Once an application reaches a final state of Approved or Declined, the onboarding lifecycle is complete.

If approved, the merchant transitions to the Merchant Provisioning phase, where gateway credentials and terminals are created.

For post-approval credential delivery, see:
Merchant Provisioning

---

Quick Start

Typical integration flow:

1. Partner creates an onboarding application using POST /onboard/{offerID}
2. SportsPay returns an appID and secure appLink
3. Partner presents the onboarding UI to the merchant
4. Merchant completes onboarding
5. Partner monitors status via:
   • GET /onboard/{appID}
   • Webhooks
6. If approved, the merchant moves to Merchant Provisioning

---

Integration Models

Immersive (Embedded) Onboarding

The Partner embeds SportsPay’s onboarding UI inside their application.

Flow

1. Partner calls POST /onboard/{offerID}
2. SportsPay returns:
   • appID
   • appLink
3. Partner embeds appLink using:
   • iframe
   • modal
   • new browser window
   • in-app webview
4. Merchant completes onboarding within Partner UI

---

Invite-Only Onboarding

Partner sets emailInvite=true and provides the appEmail.

SportsPay emails the merchant their secure onboarding link.
Partner displays a confirmation message in their system.

---

Hybrid

Partner may enable emailInvite=true while still embedding or using the returned appLink.

---

Core Identifiers

orgID

The Partner-assigned identifier for the organization the application belongs to. Required when creating an application through the API.

By default, an organization may hold only one application. Partners who need an organization to hold more than one merchant account can request multiple applications per organization.

See Multiple Applications per Organization.

offerID

A SportsPay-assigned identifier representing the onboarding “offer” that the Partner is presenting to the merchant.

An offer is a pre-configured merchant application package that includes one or more pricing models set by the Partner. Each offer defines which pricing options the merchant will see and select from during onboarding.

appID

The unique identifier assigned by SportsPay when an application is created.

It is required in order to:

• Retrieve application status
• Update the application

appLink

A secure URL pointing to the merchant’s onboarding interface.

Partners may:

• Embed it
• Redirect the merchant to it
• Allow SportsPay to email it when emailInvite=true

---

Multiple Applications per Organization

Default Behaviour

By default, SportsPay allows one application per orgID.

If POST /onboard/{offerID} is called with an orgID that already exists in the SportsPay database, the request is rejected:

Enabling Multiple Applications

Partners who need a single organization to hold more than one SportsPay merchant account — for example a separate account per program, season, division, or location — can have this enabled on their platform.

This is not enabled by default. The Registration Platform must request it, and SportsPay enables it at the platform level.

When enabled:

• The same orgID may be reused across multiple POST /onboard/{offerID} calls
• Each call creates a new, independent application with its own appID
• Each approved application is provisioned as its own merchant account, with its own termID and password
• 1004 is no longer returned for a repeat orgID

Provisioning Requirement

See Merchant Provisioning for the required storage behaviour.

---

Application Lifecycle

---

Base URLs

---

API Endpoints

---

Create Application

POST /onboard/{offerID}

Creates a new onboarding application tied to the provided identifiers (orgID and offerID).

The request payload contains two primary sections:

• appInfo — Metadata about the onboarding application, including partner identifiers, onboarding configuration, and webhook settings.
• appData — Merchant business information used to pre-populate the onboarding application.

The exact request schema, field descriptions, and validation rules are documented in the API Reference.

View full request schema →

---

Update Application

POST /onboard/{appID}

Updates editable fields on the application.

offerID cannot be changed after creation.

An application can only be updated while it is editable. Once the merchant has submitted the application, or it has otherwise been merged or moved to a final state, it is locked and further updates return 1010.

Refer to UpdateApp API Reference

---

Get Application Status

GET /onboard/{appID}

Returns the application's current state.

The state field indicates the merchant’s progress through onboarding.

Refer to AppStatus API Reference

---

Webhooks

Application State Change (app_state_change)

SportsPay can notify your system whenever an onboarding application changes state.

Triggered States

• Created
• Opened
• InProgress
• Submitted
• UnderReview
• Approved
• Declined
• Expired
• Cancelled
• Error

Enabling Webhooks

Provide a webhookURL when creating or updating an application.

Endpoints:

• POST /onboard/{offerID}
• POST /onboard/{appID}

Webhook Identification

Handling Webhooks

• Return HTTP 200–299 to acknowledge receipt
• Webhooks may be retried
• Implement idempotent processing
• Use appID as the primary identifier

---

Integration Flows

Immersive Flow

sequenceDiagram
Partner->>SportsPay: POST /onboard/{offerID}
SportsPay-->>Partner: appID + appLink
Partner->>Merchant: Embedded onboarding UI
Merchant->>SportsPay: Completes onboarding
Partner->>SportsPay: GET /onboard/{appID}
SportsPay-->>Partner: Status response

Invite-Only Flow

sequenceDiagram
Partner->>SportsPay: POST /onboard/{offerID} (emailInvite=true)
SportsPay-->>Merchant: Sends onboarding email
Partner->>Partner: Displays "Invite Sent"
Merchant->>SportsPay: Completes application
Partner->>SportsPay: GET /onboard/{appID}
SportsPay-->>Partner: Status response

---

Errors

---

Error Details

1004 — OrgID already has a application or merchant account

Returned by POST /onboard/{offerID} when the orgID has already completed an application, or already has a merchant account.

This is only returned when the Partner platform is limited to a single application per organization. If the organization legitimately needs a second merchant account, multiple applications must be enabled on the platform — see Multiple Applications per Organization.

1007 — OfferID or AppID invalid

Returned when the supplied offerID or appID does not exist. Confirm the appID returned at creation is being stored and sent exactly as issued.

1009 — OrgID already has active application in progress

Returned by POST /onboard/{offerID} when the orgID already has an application that has not yet reached a final state.

This applies whether or not multiple applications per organization are enabled — an organization may only have one application in flight at a time.

Retrieve the existing application with GET /onboard/{appID}, or wait for it to reach a final state before creating a new one.

1010 — Application cannot be modified

Returned by POST /onboard/{appID} when the application exists but can no longer be edited.

An application is editable only while the merchant is still working on it. Once it has been submitted, merged, or moved to a final state, its data is locked and it cannot be modified through the API.

Use GET /onboard/{appID} to check the current state before attempting an update. Applications cannot be reopened through the API — SportsPay must reset the application manually.

---

After Approval: Merchant Provisioning

Once an application reaches a final state of Approved, onboarding is complete and the merchant enters the provisioning phase.

Provisioning is responsible for:

• Creating the merchant record on the gateway
• Generating terminal credentials (termID + password)
• Enabling or disabling terminals
• Sending the Merchant Credential Callback

The approval webhook does not contain gateway credentials.

Gateway credentials are delivered separately through the Merchant Credential Callback, which is part of the Merchant Provisioning process.

For details see:
Merchant Provisioning

---

FAQ

Can an application be recreated?

No — SportsPay must reset it manually.

Can an organization have more than one application?

Not by default. Each orgID may hold one application, and a repeat orgID is rejected with 1009 if an application is still in progress, or 1004 if an application or merchant account already exists.

Partners who need an organization to hold multiple merchant accounts can request this. It must be enabled by SportsPay at the platform level, and requires that the Partner's provisioning integration can store multiple termID and password pairs for a single organization.

See Multiple Applications per Organization.

Why am I getting a 1009 when I don't have an open application?

An application is considered in progress until it reaches a final state. An application the merchant opened and abandoned still blocks a new one for that orgID. Call GET /onboard/{appID} to check its state.

What identifiers should the Partner store?

Store both:

• orgID
• appID

Where an organization may hold multiple applications, store each appID against the orgID rather than replacing it.

Where do I obtain an offerID?

offerID values are created in SportsPay’s Rapid Onboarding tool within PaymentsHQ.

• Sandbox / Development: The SportsPay team will provide an offerID for testing.
• Production: offerIDs are generated in PaymentsHQ when you create Offers that bundle one or more pricing models.

Rapid Onboarding (API Context)

Rapid Onboarding defines the pricing options available to merchants during onboarding.

An Offer represents a predefined set of one or more Pricing Models. Each Offer is assigned a unique offerID, which is referenced in API requests to associate a merchant application with a specific pricing configuration.

Key Points for Integrators

• offerID values are not created via API
• offerID must exist in PaymentsHQ before being referenced in API requests
• One offerID maps to a specific set of pricing models
• The same offerID can be reused across multiple merchant applications