Onboarding

This section outlines the process for onboarding new entities (Parents or Merchants) using the Partner APIs. The API schemas for both are similar, with a few key parameters that define the new entity.

The primary fields to consider when onboarding are the entity's name, its position in the hierarchy, and the security credentials returned in the response.

• entityName: This is a simple, required string that defines the name of the new entity being onboarded (e.g., parentName or merchantName).

• grandparentId or parentId: This parameter is crucial for establishing the hierarchy. It's the unique identifier (ID) of the entity under which the new entity will be onboarded.

  • If not specified while onboarding a parent as a grandparent or merchant as a parent, this value will default to the grandparentId or parentId of the auth token you are using.

• theme: This optional object allows for the customization of the UPP Optty portal's appearance for the new entity. It provides granular control over the UI, including:

  • logo: A string representing the URL for the entity's logo.

  • Color Fields: Strings for background, active, hover, and text colors for both the left sidebar and top bar, allowing for brand alignment.

  • paymentLinkMenuAlias: A string to customize the name of the payment link (optty direct) menu item.

• popupOverlayConfig

  • The title and message displayed on your page when the inContext checkout flow is in progress (either in an iframe or seperate popup)

If you are completely replicating the portal functionality via API, the theme object will have no effect on this process and can be passed as an empty object ({}).

The fields returned are

• parentId or merchantId: This parameter is crucial for establishing the hierarchy. It's the unique identifier (ID) of the entity under which the new entity will be onboarded.

• authSecret: This is a crucial security credential. Along with the entity's ID, it is used to generate an access token for making API calls as that specific entity.

• hmacKey: This security-related field is only relevant for Merchants. It is used for signature validation when checking the return signature.

The parentId and merchantId also act as the respective clientId when generating an auth token for the newly onboarded entity