# Referral API

Refer merchants to Tyro from within your own platform or workflow, without using the Tyro Partner Portal. Submit referrals at volume and follow their progress as they move through Tyro’s identity, risk, and approval checks.

## What is it?

Tyro’s Referral API lets partners create and manage merchant referrals programmatically. Create a [Referral](/api-explorer/referrals/1.0#operation/create-referral-request) with the merchant’s details, product of interest, pricing, and your `partnerChannelAgreementId`, then track its progress using its `referralId` and [Get referral](/api-explorer/referrals/1.0#operation/get-referral).

## Requirements

| Requirement | Description |
|  --- | --- |
| **Integration type** | Business operations (referrals) |
| **Webhooks** | Subscribe to [referral notification events](/api-explorer/referrals/1.0/notification-events) to track status changes |
| **Setup steps** | You need a Tyro `partnerId` and a `partnerChannelAgreementId` enabled for the referral type you want to submit — see Prerequisites below |
| **Limitations** | Referrals are limited to merchants new to Tyro - existing Tyro merchants cannot be referred for additional payment products via this API |
| **API reference** | [Jump to API reference](#api-reference) |


## Prerequisites

To create a referral, you need:

* Your Tyro `partnerId`.
* A `partnerChannelAgreementId` enabled for the referral type you want to submit.
* The merchant's ABN, company name, estimated monthly card turnover, and contact details.
* The product the merchant is interested in.
* The pricing fields required for the selected referral type.


## Key concepts

**Referral type** — determines which product you're referring and which pricing fields are required. Sending pricing fields that don't match your referral type, such as including `wholesaleRate` on an ISO referral, is rejected.

**Partner channel agreement ID** — identifies the commercial agreement under which you're referring the merchant. It must be enabled for the referral type you submit.

## How it works

1. **Submit** — Call [Create referral](/api-explorer/referrals/1.0#operation/create-referral-request) with the merchant's details, product of interest, referral type, and any pricing required for that referral type.
2. **Track** — Store the `referralId` returned when creating the referral. Use it with [Get referral](/api-explorer/referrals/1.0#operation/get-referral) to fetch the latest status, or subscribe to [notification events](/api-explorer/referrals/1.0/notification-events) to be notified as the merchant's application progresses through Tyro's approval workflow. See [Referral statuses](/docs/business-operations/referrals/referral-statuses) for the full list — not every referral passes through every status.


## Referral types and pricing

Every referral specifies a `referralType`, which determines which product you are referring and which pricing fields are required. Use the table below to find the right combination for your referral. See the [Create referral](/api-explorer/referrals/1.0#operation/create-referral-request) reference for payload examples for each referral type.

| Referral type | Description | Products you can refer | Required pricing |
|  --- | --- | --- | --- |
| `WHOLESALE` | Referring a merchant for an in-store Tyro product under a wholesale arrangement. | In-store products* | `pricingDetails.wholesaleRate` |
| `ISO` | Referring a merchant for an in-store Tyro product under an Independent Sales Organisation (ISO) agreement. | In-store products* | `pricingDetails.retailRate` |
| `EFTPOS_REFERRAL` | Referring a merchant for an in-store Tyro product where Tyro will set and manage pricing directly (a simple referral). | In-store products* | None — omit pricing entirely |
| `ECOMM_ISV` | Referring a merchant for the Tyro eCommerce product under an Independent Software Vendor (ISV) wholesale arrangement. | `ECOMMERCE` | `dollarPerTransaction.rate` (`dollarPerTransaction.value` optional) |


*In-store products: `TYRO_PRO_KEY`, `TYRO_PRO_TOUCH`, `TYRO_PRO_LITE`, `BYO_PHONE`, `EMBEDDED_PAYMENTS_SDK`.*

## Conditions and limitations

* **Merchant eligibility**: Referrals are limited to merchants new to Tyro. Referring an existing Tyro merchant to add another site isn't yet supported.
* **Pricing must match referral type**: Sending pricing fields that don't match your `referralType` is rejected — see Referral types and pricing above.


## API reference

| Endpoint | Description |
|  --- | --- |
| [`POST /referrals`](/api-explorer/referrals/1.0/other/create-referral-request) | Create referral |
| [`GET /referrals/{referralId}`](/api-explorer/referrals/1.0/other/get-referral) | Get referral |