# Referral API

Use the Referral API to refer merchants to Tyro programmatically — submitting each merchant's details, product of interest, and pricing in a single call — instead of entering referrals manually through the Tyro Partner Portal. Submit referrals at volume, then track each one as Tyro runs identity, risk, and approval checks and moves the merchant toward go-live.

Merchant eligibility
Referrals are currently limited to merchants that are new to Tyro. Referring an existing Tyro merchant to add another site is not yet supported.

## How it works

1. Submit referrals by calling the [Create Referral](/app/apis/referrals/1.0#operation/create-referral-request) endpoint with the merchant's details, product of interest, referral type, and any pricing required for that referral type.
2. Track referral progress by storing the `referralId` returned when creating a referral. Use it with [Get Referral](/app/apis/referrals/1.0#operation/get-referral) to fetch the latest status, or subscribe to [webhook notifications](/app/apis/referrals/events) to track the merchant's status as their application progresses through Tyro's approval workflow.


## Before you start

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.


## Valid referral combinations

Every referral you submit specifies a `referralType`, which determines which product you are referring and which pricing fields are required. Sending pricing fields that do not match your referral type, such as including `wholesaleRate` on an ISO referral, will be rejected.

Use the table below to find the right combination for your referral. See the [Create Referral](/app/apis/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 (i.e. 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`.*

## Track referral progress

Every referral moves through a series of statuses as Tyro processes it. Retrieve the current status by calling [Get Referral](/app/apis/referrals/1.0#operation/get-referral), or subscribe to [webhook notifications](/app/apis/referrals/events) to be notified when it changes.

Not every referral passes through every status.

### Referral submission

| Status | Description |
|  --- | --- |
| `REFERRAL_REQUESTED` | Tyro has accepted your request and is creating the referral. |
| `REFERRAL_RECEIVED` | The referral has been created successfully and is now with Tyro. |
| `REFERRAL_FAILED` | The referral could not be created. See the `error` field for the reason. No further updates will follow. |


### Merchant application

| Status | Description |
|  --- | --- |
| `MERCHANT_APPLICATION_FORM_NOT_YET_ACCESSED_BY_MERCHANT` | Tyro has sent the merchant their application form, but they have not opened it yet. |
| `MERCHANT_APPLICATION_FORM_COMPLETION_IN_PROGRESS_BY_MERCHANT` | The merchant has started filling in their application. |
| `MERCHANT_APPLICATION_FORM_COMPLETED_AND_SIGNED_BY_MERCHANT` | The merchant has completed and signed their application and submitted it to Tyro. |
| `MERCHANT_APPLICATION_IN_REVIEW` | Tyro is reviewing the application, including identity and risk checks. |
| `MERCHANT_APPLICATION_RETURNED_ADDITIONAL_INFORMATION_REQUIRED` | Tyro needs more information from the merchant before the review can continue. |


### Final outcomes

| Status | Description |
|  --- | --- |
| `MERCHANT_CONDITIONALLY_APPROVED` | The merchant has been approved subject to outstanding conditions. |
| `MERCHANT_FULLY_APPROVED` | The merchant is fully approved and onboarded. |
| `MERCHANT_APPLICATION_REJECTED` | Tyro declined the application. |
| `MERCHANT_APPLICATION_CANCELLED_BY_MERCHANT` | The merchant chose not to proceed. |


## API Reference

- [Create Referral](/app/apis/referrals/1.0#operation/create-referral-request): Submit a new merchant referral.
- [Get Referral](/app/apis/referrals/1.0#operation/get-referral): Retrieve the current status of a referral.
- [Notification Events](/app/apis/referrals/events): Subscribe to referral status changes.