# Relay

> Collect for sellers who have no Wajub account, and let Wajub work out and pay what each one is owed.

In `relay`, you are the merchant of record. Your sellers have no Wajub account: each one is a
connection tied to their mobile money wallet. You collect every sale on your own balance, and Wajub
keeps, sale by sale, what each seller is owed, then pays them on the schedule you set.

> [!NOTE]
> **Open in live once Wajub has reviewed your platform**
>
> Every call on this page works with a sandbox key. In live, Relay is open to every platform Wajub
> has approved for it: ask for the review under **Settings, Sync, Platform**. Until it is approved, or
> if the approval is withdrawn, `POST /accounts` with `account_type: relay`, a call carrying `X-Sync`
> on a live Relay connection, and a Relay part of a shared payment answer `403` with
> `error_code: sync_mode_not_approved`.

## One connection per seller

Create the connection with the seller's wallet: either a beneficiary you already have, or the
details to create one, with the same fields as `POST /beneficiaries`.

```bash title="A Relay seller"
curl https://api.wajub.com/accounts \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "account_type": "relay",
    "capabilities": ["payments", "refunds"],
    "pricing": { "percentage_fee": 10, "currency": "XAF" },
    "payout_schedule": "weekly",
    "beneficiary": "ben_LRQqYvlhrgUOE225KMKU"
  }'
```

| The wallet                                          | The connection                                                                                                                                  |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Its name is confirmed by the operator               | `active`, with `payment_status: active`, straight away                                                                                          |
| Not checked yet, or the operator could not be asked | `pending`; `relay.pending_reason` says why. It turns `active` as soon as a check succeeds, with `POST /beneficiaries/{id}/verify` or on its own |
| Known to the operator under another name            | `pending` with `wallet_name_mismatch`: correct the name, then check again                                                                       |

There is no onboarding and no `authorization_url`. A wallet carries one Relay connection per
platform: a second answers `409` with `error_code: relay_wallet_taken`.

## What each seller is owed

Charge with `X-Sync` as for any connection. The payment is yours: it lands on your balance. For each
sale that succeeds, Wajub records the seller's due:

|              |                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The due      | What the sale credited you, less Wajub's fee, less your commission (the connection's `pricing`)                                                                                                        |
| Held         | Until the sale clears retention, like the money itself                                                                                                                                                 |
| Payable      | After that, until a payout takes it                                                                                                                                                                    |
| Card reserve | A card sale keeps 10% of its due for 120 days by default, on your balance, against chargebacks: paid to the seller by the first payout after that ([The card reserve](https://docs.wajub.com/sync/payouts#the-card-reserve)) |

A sale you collected on your own provider account never reached Wajub, so it creates no due.

## Payouts

`payout_schedule` (`manual`, `daily`, `weekly`, `monthly`) and `payout_min_amount` work as for
`lite`, and `POST /accounts/{id}/payouts` pays the seller now. Each payout sends the seller's payable
dues, oldest first and whole, **less what they owe** after a refund, from your balance to their wallet.
When what they owe absorbs the whole payout, nothing is sent: the call answers `200` with
`transfer: null` and the amount `netted`.

A Relay seller gets **one payout a day** at most. When two runs meet the same day (the schedule and
your `POST /accounts/{id}/payouts`, or a call you retried), the second answers with that day's payout
and sends nothing more; dues recorded in between leave with the next day's payout, on a payout of
their own. A due is only ever marked paid by the payout that carried it.

| What holds a payout back                              | `payout_hold.reason`                                                       |
| ----------------------------------------------------- | -------------------------------------------------------------------------- |
| Your balance does not hold the amount                 | `insufficient_balance`: nothing leaves, the next run tries again           |
| Your exposure cap                                     | `exposure_cap` ([Your exposure cap](https://docs.wajub.com/sync/payouts#your-exposure-cap))      |
| Wajub withdrew your approval                          | `approval_withdrawn`                                                       |
| The seller passed the name-only tier                  | `identity_required` (below)                                                |
| The seller is new, and only their older dues are paid | `new_seller` ([Seller risk](https://docs.wajub.com/sync/seller-risk#new-sellers-are-paid-later)) |
| You, or Wajub, froze the seller                       | `frozen` ([Seller risk](https://docs.wajub.com/sync/seller-risk#freezing-a-seller))              |

A sale you [hold until delivery](https://docs.wajub.com/sync/holds) keeps its due unpaid until you release it, without a
`payout_hold`.

Each hold sends `account.payout_limited` once, except `identity_required`, which sends
`account.identity_required`. A payout goes through every check of an ordinary
transfer, your reserve and refunds on their way included.

## When a sale is refunded

The refund comes out of your balance, as for any payment of yours: it waits with
`insufficient_balance` if you do not hold it. On the seller's side:

| The due      | What happens                                                                              |
| ------------ | ----------------------------------------------------------------------------------------- |
| Not paid yet | It is reduced by the refunded share, and cancelled if nothing is left                     |
| Already paid | What the seller owes is recorded on their beneficiary, and taken out of their next payout |

A lost dispute works the same way. Each refund or dispute counts once, however often it is replayed.

## The seller's identity, past a tier

A seller is paid on their wallet's name alone until what Wajub paid that wallet over the last 12
months reaches a ceiling (500 000 XAF or XOF). Past it, the part of a payout above the ceiling waits
for an identity document: you receive `account.identity_required`, and send it with
`POST /accounts/{id}/identity`, as `multipart/form-data`.

| Field                 |                                                                    |
| --------------------- | ------------------------------------------------------------------ |
| `full_name`           | As the document prints it                                          |
| `document_type`       | `national_id`, `passport`, `driving_license` or `residence_permit` |
| `document_number`     | Never stored in clear                                              |
| `birth_date`          | `YYYY-MM-DD`                                                       |
| `document_expires_at` | Optional; an expired document is refused                           |
| `document`            | JPG, PNG or PDF, 10 MB at most                                     |

Wajub reviews it, usually within a working day: `account.identity_verified`, and the held payouts
leave from the next run, or `account.identity_rejected` with the reason. In sandbox it is approved at
once. The ceiling may change: Wajub tells Relay platforms before it does.

- [Paying sellers](https://docs.wajub.com/sync/payouts): Lite payouts, the exposure cap, and payout runs.
- [Refunds](https://docs.wajub.com/sync/refunds): Who refunds what, mode by mode.
- [Beneficiaries](https://docs.wajub.com/payouts/beneficiaries): Wallets, and checking the name on one.
