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 ( Approved, Declined, Expired or Cancelled), 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

The link can be reused until the application is submitted, expires or is cancelled. Share it only with the merchant completing the application.

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

Applications expire 30 days after creation. A reminder email goes to the merchant 3 days before expiry. Only SportsPay can reset the expiry.

Base URLs

Endpoints below are appended to the base URL. Example: POST https://api.sportspay-test.com/onboard/{offerID}

Authentication

Onboarding API requests are authorized by your Offer ID, which SportsPay issues uniquely to your platform. No additional headers are required.

Keep your Offer ID and application IDs on your server. Never expose them in client-side code or public URLs.

API Endpoints

Create vs Update

Create and Update share the path /onboard/{ID}. The server decides by the length of the ID:

An ID of the right length that does not exist returns 1007. A GET with an offerID returns 1003.

Responses

Every response returns HTTP 200, including errors. Always check result.status and result.code, never the HTTP status.

{
  "result": { "status": true, "code": 0, "message": "Success" },
  "application": { "appID": "...", "appLink": "...", "state": "Created" }
}

The Content-Type header is text/json.

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:

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

View full request schema →

Update Application

POST /onboard/{appID}

Replaces the whole application. It is not a partial update.

• Send the complete appInfo and appData objects on every update.
• orgID, appEmail and orgName are required every time (else 1001).
• Any field you omit is cleared.
• Updates do not extend the 30-day expiry.
• The application is locked (1010) once it is Submitted, Approved, Declined, Expired or Cancelled.

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)

State-change webhooks are sent once, with no retries, when:

• the merchant saves, submits or forwards the application
• SportsPay cancels the application
• the application is approved and becomes a merchant

They are not sent when the link is opened or the application expires.

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 with a short response body (for example OK) to acknowledge receipt.
• Each state change is sent once. Respond quickly and process the payload after acknowledging.
• 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.

The error response includes the existing application, so you can recover its appID if you no longer have it.

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.

The error response includes the existing application, so you can recover its appID if you no longer have it.

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 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.

Applications that are never submitted expire 30 days after creation, after which a new application can be created

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