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.

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.

Partners should match merchants using identifiers in the following priority:

1. orgID (preferred when available)
2. merchID
3. partnerID

Not all identifiers will be present in every callback payload.

Uniqueness Rules

The orgID and partnerID serve different purposes and have different uniqueness requirements.

orgID (Required for Onboarding API)

• Assigned by the Partner when creating an onboarding application
• Must be unique per onboarding application
• Used to uniquely identify a merchant application within the Onboarding API

Each merchant account provisioned through the API must have its own unique orgID.

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

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

Terminal Status

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

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

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)