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

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

---

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.

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

---

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.

What identifiers should the Partner store?

Store both:

• orgID
• appID

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