# Activate a Merchant

Enable merchants to activate your loyalty program so their locations can participate and generate loyalty activity.

## Overview

Merchant activation is the process that allows a Tyro merchant to enable your loyalty program at their location/s.

When a merchant submits a request to onboard to your loyalty program, Tyro creates an onboarding request and notifies your system. You are responsible for reviewing the request, configuring your system, and submitting a decision.

If approved, Tyro completes onboarding and the merchant location becomes active in your loyalty program.

Activation happens after your Loyalty API integration has been completed and certified. However, your integration must support this flow before merchants can successfully use loyalty at their locations.

## Roles and responsibilities

Merchant

- Requests onboarding to your loyalty program
- Enables loyalty on terminals once onboarding is complete


Tyro

- Creates onboarding requests
- Sends notifications to your system
- Completes onboarding after your decision


Loyalty partner (you)

- Retrieve onboarding requests
- Configure merchant locations
- Submit APPROVE or REJECT decisions


## How it works

Merchant activation follows a request-and-response model:

1. Merchant requests onboarding to your loyalty program
2. Tyro creates an onboarding request
3. Tyro publishes a NEW_ONBOARDING_REQUEST notification to your endpoint
4. You retrieve the onboarding request details
5. You review and configure the request in your system
6. You submit a decision: APPROVE or REJECT
7. Tyro completes or rejects onboarding based on your response


Once onboarding is approved and completed, the merchant location becomes active and will begin generating loyalty activity.

p
img
## Activation lifecycle

A merchant location progresses through the following lifecycle:

1. Merchant authorises your loyalty program
2. Tyro creates an onboarding request (**PENDING**)
3. You review and configure the location
4. You approve the request (**READY**)
5. Merchant enables loyalty on terminals
6. First transaction occurs (**ACTIVE**)


Once a location is ACTIVE, transactions at that location will begin generating loyalty activity events.

## What you must build

To support merchant activation, your system must:

- Receive `NEW_ONBOARDING_REQUEST` notifications
- Retrieve onboarding requests using `onboardingReference`
- Store the `tcLocationId` for each location
- Configure locations in your system
- Submit APPROVE or REJECT decisions


## Receiving onboarding requests

When a merchant onboarding request is created, Tyro publishes an event to your registered notification endpoint.

### Notification payload


```json
{
  "type": "NEW_ONBOARDING_REQUEST",
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resource": "loyalty/merchant-onboarding",
    "uri": "https://api.tyro.com/connect/locations/merchant-onboarding/loyalty/3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}
```

| Field | Type | Description |
|  --- | --- | --- |
| `type` | string | Always `NEW_ONBOARDING_REQUEST` for this event. |
| `data.id` | string | The unique `onboardingReference` for this request. Use this value to interact with the onboarding endpoints. |
| `data.resource` | string | The resource type. Always `loyalty/merchant-onboarding`. |
| `data.uri` | string | The fully qualified URL to retrieve the onboarding request details. |


Notifications are delivered on a best-effort basis. It is recommended that your system handles idempotency for repeated deliveries of the same event.

## Retrieving onboarding request details

Use the `onboardingReference` from the notification payload to fetch the full details of the onboarding request.

For the full request and response specification, see the  [`Get merchant onboarding request by reference`](/app/apis/loyalty/0.9#operation/get-merchant-onboarding-request-by-reference)  operation in the API reference.

## Submitting your decision

Once you have reviewed the onboarding request, submit your decision using the [`Submit a decision for a merchant onboarding request`](/app/apis/loyalty/0.9#operation/submit-merchant-onboarding-decision)  endpoint.

You must respond with either:

- `APPROVE`
- `REJECT`


## About loyaltyProgramId

The `loyaltyProgramId` is created during partner onboarding and identifies the loyalty program that merchant locations will participate in.

All locations sharing the same `loyaltyProgramId` will collect points across all venues using the same criteria for points accumulation.

`loyaltyProgramId` is a required field when submitting an APPROVE decision. Tyro uses it to associate the merchant location with the correct loyalty program in your system.

Currently, partners are not able to manage programs themselves. If you need to create a new program or make changes to an existing one, please contact partner support at [connect-support@tyro.com](mailto:connect-support@tyro.com).

## The tcLocationId

The `tcLocationId` is Tyro Connect’s globally unique identifier for a merchant location. It is returned in the [`GET`](/app/apis/loyalty/0.9#operation/get-merchant-onboarding-request-by-reference) response under the `tcLocationId` field and is assigned when the onboarding request is created.

You should store this value in your system. It acts as the canonical identifier for the merchant location and must be used for all subsequent loyalty interactions, including loyalty activity events.

## Important considerations

- Decisions are final. Once you submit an APPROVE or REJECT decision for an `onboardingReference`, it cannot be changed. Any subsequent attempt will receive a `409 Conflict` response
- `loyaltyProgramId` is required for approvals. Ensure the value is valid before submitting
- Notifications are best-effort. If your system does not receive a notification, implement a polling or reconciliation mechanism to check for pending onboarding requests