# Merchant registration

Open Registrations in the sidebar (`/wallets/deposit`). The page is titled "Merchant registrations". Any member can read it; owners, admins and project leads can register and manage.

## What registration is

A merchant registration is your record on chain, one per project per chain. On Solana it is a `Merchant` account of the recv.fund program. On Robinhood Chain it is your own merchant contract (`MerchantVault`), which your admin wallet creates through the recv.fund factory contract (`RecvFundFactory`). The record holds:

| Field | Set from | Can change later |
| --- | --- | --- |
| Merchant ID | 32 random bytes generated by your server | No |
| Admin | The browser wallet you connect | No |
| Settlement wallet | The address you type as "Cold wallet (settlement address)" | Yes, signed by the admin |
| Sweeper | The hot wallet assigned to the project | Yes, signed by the admin |
| Active | Set on registration | Yes, signed by the admin |
| Fee rate and fee collector | Copied from the program (Solana) or the factory (Robinhood Chain) when the registration transaction runs | No. No function exists that changes them. |

Funds at a deposit address can move only to the settlement wallet and to the fee collector recorded in this registration. Customer deposit addresses are derived from the registration (a program-derived address on Solana, a CREATE2 address computed by your merchant contract on Robinhood Chain), so the registration must be confirmed before a customer can be given an address. The admin key stays in your browser wallet; the server prepares unsigned transactions and never receives a private key.

On Robinhood Chain your merchant contract has no owner, cannot be upgraded or paused, and has no function that sends funds to any other address. recv.fund has no role in it. Its address is computed from the factory, your admin address and the merchant ID, so a different wallet that uses the same merchant ID gets a different contract.

## Before you start

- The installation is connected to the recv.fund deployment for the network. This happens by itself; Nodes shows its state. Otherwise the form shows "An installation administrator must configure this network's deployed program in Nodes before registration."
- An active hot wallet of the right family is assigned to the project. The form links to "Manage hot wallet assignments". Preparation is refused without it.
- One project is selected in the sidebar workspace selector. With "All projects" selected the page only lists registrations.
- Your browser has an injected wallet with a little native currency for the transaction fee: an EVM wallet such as MetaMask for Robinhood Chain, or Phantom, Solflare or another injected wallet for Solana. WalletConnect is not available in this release. On Robinhood Chain use MetaMask: if several EVM wallets are installed, the form shows a button for each (for example "Connect MetaMask" and "Connect Phantom"), and when you sign, the page asks MetaMask to switch to Robinhood Chain and adds the network if MetaMask does not have it. On Solana, wallets supporting `signTransaction` sign locally and the installation sends the signed transaction through its configured RPC. If a wallet only supports `signAndSendTransaction`, select the installation’s network in that wallet; on a testnet install, use Solana Devnet. Keep enough SOL on that network for the registration fee.

## 1. Prepare registration

A registration records three wallets, each with a different job:

| Wallet | What it does | Who holds the key |
| --- | --- | --- |
| Admin wallet | Signs and pays for the registration. Afterwards it is the only wallet that can change the cold wallet or the hot wallet, or pause the registration. No funds go to it. It cannot be replaced. | You, in your browser wallet |
| Cold wallet (settlement address) | Receives your money: every sweep sends deposits here, minus the fee. It can be the same address as the admin wallet. | You; the server only stores its address |
| Hot wallet (sweeper) | Signs sweeps and pays their network fees. Sweeps can only send to the cold wallet, with the fee to recv.fund in the same transaction. | The server, encrypted |

Fill in the "Prepare registration" form:

1. **Network**: the chain to register on.
2. **Admin wallet (your browser wallet)**: press "Connect browser wallet" to fill it from the wallet, or paste it. Keep this wallet: it controls the registration from now on.
3. **Cold wallet (settlement address)**: the wallet on that network that will receive your funds when deposits are swept. Type it carefully; it is checked for format, not ownership.
4. The form shows the **Hot wallet (sweeper)** assigned to the project for that network. Assign one under Hot wallets first if it says none.
5. **Label (optional)**: a name for the row.

Press "Prepare registration". The prepared transaction must be signed within about a minute on Solana; if it has expired, select **Manage** on the pending row and **Resume registration** to prepare it again. The server locks the project and chain, creates a registration row in `pending` with a new merchant ID, and returns the transaction to sign. The row appears in the "Registered merchants" table (Project / network, Cold wallet, Sweeper, Status, Actions).

If you prepared a registration with the wrong admin or cold wallet and have not sent its transaction, select **Manage** on the pending row and **Discard and start over**, then prepare it again. The server first checks that the registration does not exist on chain; once its transaction has executed, it can only be confirmed.

## 2. Sign

The "Sign and confirm" panel opens. It shows the current fee: "Current fee: N bps of each sweep. The rate in force when this transaction executes is stored with the registration and never changes; later changes apply only to new registrations." Below it is one transaction block with the signer, the contract and a button.

Registration is one transaction signed by the admin wallet on both chains:

- **Robinhood Chain**: "1. Create merchant contract". The transaction calls `createMerchant(merchantId, settlementWallet, sweeper)` on the factory, which creates your merchant contract with the settlement wallet, the hot wallet as sweeper, and the fee terms in force at that moment. Press "Sign step 1" and approve it in the wallet. The page polls for the receipt for up to three minutes; if it is still pending, the button changes to "Check inclusion". A reverted transaction stops the flow; prepare again.
- **Solana**: "1. Register merchant". The transaction contains one `register_merchant` instruction, which creates the merchant account with the settlement wallet, the hot wallet as sweeper, and the fee terms in force at that moment.

The wallet must have the signer account selected. EVM wallets switch to the transaction’s chain before sending; Solana transactions normally use the installation’s RPC relay. The page explains an account mismatch, expired transaction or insufficient fee balance. The submitted hash is shown in the block. Write it down if you might leave the page.

## 3. Confirm on server

Signing puts the record on-chain; the server does not know until you tell it. The field "Transaction hash to verify" is prefilled with the submitted hash. Press "Confirm on server".

The server reads the transaction from the RPC pool and checks: the network, that the code at the configured address is the supported build (on Robinhood Chain, the factory and your new merchant contract), that the transaction succeeded, that it was signed by the merchant admin and creates or updates this merchant, that it has the required confirmations (1 on Solana, 12 on Robinhood Chain by default), and that the record on-chain now shows the expected admin, settlement wallet, sweeper and active flag. If confirmations are still short, the response says so; wait and press the button again. On success the row's status becomes `active`.

On Robinhood Chain the server can derive deposit addresses only after your merchant contract exists, which is why checkout opens only after this step.

## Leaving and resuming

Local step state is dropped when you leave the page, but the pending row stays. Press "Manage" on it and then "Resume registration". The server reuses the original admin and settlement addresses (they cannot be changed on a pending row) and returns only the steps that are not yet on-chain. If everything is already on-chain, the panel says so and you only need to enter a hash and confirm.

## After registration

- Checkout on that chain is open for the project: the currencies of that chain that are enabled under Projects appear on the checkout page, and a customer who picks one is assigned a deposit address.
- The sweeper is the hot wallet's address. The sweep worker can now sign sweeps for this merchant.
- The fee rate and fee collector of this registration are fixed. If recv.fund later changes the terms for new registrations, this registration keeps its own.
- The row shows `active`. Its merchant ID and admin address are visible under "Manage".

Repeat the whole page for each other chain, and for each other project. Each combination gets its own merchant ID.

## Managing an active registration

Press "Manage" on an active row. Every change is an unsigned transaction prepared by the server, signed by the merchant admin wallet in the same "Sign and confirm" panel, and then confirmed with "Confirm on server", which reads the actual on-chain state back into the database.

| Action | Form | Notes |
| --- | --- | --- |
| Change settlement wallet | "New settlement address", then "Prepare settlement update" | Later sweeps go to the new address once confirmed. Deposit addresses do not change. |
| Update sweeper | "Assigned hot wallet", then "Prepare sweeper update" | Assign the new hot wallet to the project first; the list shows only active wallets assigned to this project for this chain family. |
| Prepare deactivation / Prepare activation | One button | The active flag has no effect on chain. Your server reads it: while a registration is inactive, the checkout page stops offering that chain and no new deposit addresses are assigned on it. Sweeps still work, so funds already at deposit addresses can always be moved to the settlement wallet. |

## Next

[Test payment](https://docs.recv.fund/onboarding-guide/test-payment.md): create a link and pay it.