Merchant Provisioning occurs after an onboarding application is approved and is responsible for creating and managing gateway credentials and terminals.

Merchant Provisioning is separate from the Onboarding API and operates as a downstream system.

While onboarding collects and reviews merchant application data, provisioning:

• Creates the merchant record on the gateway
• Generates terminal credentials (termID + password)
• Enables or disables terminals
• Pushes credential updates to the Partner

Relationship to Onboarding

Once an onboarding application reaches a terminal state (Approved or Declined), the onboarding lifecycle is complete.

If the application is Approved, SportsPay begins the provisioning process.

1. The merchant is provisioned on the gateway.
2. One or more terminals (termID) are created.
3. Gateway credentials are generated.
4. The Merchant Credential Callback is sent.

The approval webhook does not include gateway credentials.
Provisioning occurs after approval and may complete minutes later.

An organization may hold more than one application through the Onboarding API, and therefore more than one merchant account, where SportsPay has enabled multiple applications for the Partner platform. See Multiple Terminals per Organization.

Merchant Credential Callback

The Merchant Credential Callback is a server-to-server POST request sent by SportsPay when gateway credentials are created or updated.

Partners should use this callback to store or update the merchant's gateway credentials in their system.

This callback is separate from onboarding webhooks.

Important Distinction

The credential callback may be triggered for:

• API-onboarded merchants
• Merchants onboarded through legacy or embedded flows
• Terminal enable events
• Terminal disable events
• Account closures

Endpoint Configuration

Unlike onboarding webhooks (which use the webhookURL provided in the application request), the Merchant Credential Callback is sent to a fixed endpoint configured internally within SportsPay.

This endpoint:

• Is environment-specific (Test vs Production)
• Is not dynamically defined per application
• Must be configured with SportsPay prior to go-live

Contact SportsPay to update this endpoint.

When Is the Callback Sent?

The callback is triggered when:

• A merchant is approved and provisioned
• A terminal (termID) is created
• A terminal is enabled
• A terminal is disabled
• Gateway credentials are updated

The callback may occur at any time during the merchant’s lifecycle.

Example Callback Payload

{
  "orgName": "Little Tigers Club",
  "merchID": "ABCD1234",
  "orgID": "1ebbdbb7-4a55-6ec6-ac8c-02bb3c474244",
  "partnerID": "432341",
  "termID": "ABCD1265",
  "password": "iyPZVvdD",
  "platform": "Acme Registration",
  "status": "active"
}

Field Definitions

While merchID and termID may sometimes appear similar, they are configured independently. Both values should be stored.

Identifier Model & Merchant Mapping

The Merchant Credential Callback may include several identifiers used for merchant mapping:

• orgID
• merchID
• partnerID

The presence of certain identifiers depends on how the merchant was onboarded.

Identifier Availability

• appID is not included in the credential callback.
• orgID is only present if the merchant was onboarded via the API.
• partnerID is optional and may be included for both API and non-API merchants. When provided, it can be used to group multiple merchants for reporting.
• A single orgID may appear across multiple callbacks, each carrying a different termID, where the organization holds more than one merchant account.

Not all identifiers will be present in every callback payload.

Partners should map each identifier to its purpose:

Uniqueness Rules

The orgID, merchID, termID, and partnerID serve different purposes and have different uniqueness requirements.

orgID (Required for Onboarding API)

• Assigned by the Partner when creating an onboarding application
• Identifies the organization a merchant account belongs to
• Is not guaranteed to be unique per merchant account

By default, orgID maps to a single application through the Onboarding API, and therefore to one merchID and one termID.

Where SportsPay has enabled multiple applications for the Partner platform, an organization may hold several merchant accounts under the same orgID, each with its own merchID, termID, and password.

partnerID (Optional / External Reference)

• Provided by the Partner
• Used as a reporting/grouping identifier so Partners can view financial reporting aggregated across multiple merchant accounts.
• Does not need to be unique

For example, a Partner may assign the same partnerID to multiple merchIDs in order to view deposits, fees, and transaction reporting as a single grouped set.

Summary

* Unique per organization, but a single orgID may map to multiple merchant accounts where multiple applications are enabled.

partnerID is treated as a reference value, not a primary key

Multiple Terminals per Organization

Through the Onboarding API, an organization is provisioned with a single merchant account by default.

Partners who need an organization to hold more than one SportsPay merchant account — for example a separate account per program, season, division, or location — can request this. The configuration is applied by SportsPay on the back end; there is no request parameter for it.

See Onboarding → Multiple Applications per Organization.

Where this is enabled, each approved application is provisioned as its own merchant account, with its own merchID, termID, and password.

Required Partner Behaviour

Before multiple applications can be enabled for a Partner platform, the Partner must confirm their credential storage handles the following.

Callback Handling Logic

on credential_callback(orgID, merchID, termID, password, status):

    existing = lookup_credential_by(termID)

    if existing:
        # enable / disable / credential update for a known terminal
        update(existing, password, status)
    else:
        # new merchant account for this organization
        insert_new_credential(orgID, merchID, termID, password, status)

Terminal Status

A callback will be sent if a terminal is disabled or re-enabled. Partners should update their records accordingly.

Status applies to the individual terminal, not the organization. Where an organization holds multiple terminals, disabling one does not affect the others.

Platform-Specific Implementation

The Merchant Credential Callback may be customized for each Partner integration.

While the core credential fields (termID, password, merchID) remain consistent, the overall payload structure, authentication method, and supplemental metadata may vary based on the Partner’s integration requirements.

Customizations may include:

• Additional identifiers required for merchant mapping
• Platform-specific metadata fields
• Custom platform values
• Custom authentication mechanisms
• Extended payload structures
• Whether the platform supports multiple applications and merchant accounts per organization

SportsPay defines the final callback contract during integration. Partners must confirm their production callback specification prior to going live.

Security

The Merchant Credential Callback supports:

• Custom header authentication (e.g., X-Api-Key)
• Separate keys for Test and Production environments

Your endpoint should:

• Validate authentication headers
• Return HTTP 200–299 on success
• Be idempotent (duplicate callbacks may occur)