> For the complete documentation index, see [llms.txt](https://docs.makapay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.makapay.io/security/recipient-wallets.md).

# Recipient Wallets & 2FA Enforcement

Recipient Wallets is an opt-in security feature that restricts which wallet addresses can receive money from your MakaPay account. When you turn enforcement on, every payment-link `merchant` address and every vault sweep address — from the dashboard, the Mini App, POS terminals, and the public API — must come from a list you've explicitly approved with a 2FA code.

This protects you against a leaked API key being used to redirect funds to an attacker-controlled address. The leaked key can still create payments, but only to wallets you've personally verified.

***

## How it works

1. You add wallets to your **Recipient Wallets** list under **Dashboard → Settings**. Each add requires the 6-digit code from your authenticator app (the same one you use for referral withdrawals).
2. You turn on the **Recipient enforcement** toggle. This also requires a 2FA code.
3. From then on, every payment created on your account is validated against the list. Unknown addresses are rejected with a clear error.

The feature is fully opt-in. If you never turn enforcement on, your account behaves exactly as before — addresses are free-text and not validated.

***

## Enabling enforcement

### Step 1 — Make sure 2FA is enabled

Go to **Dashboard → Settings → Two-Factor Authentication** and enable an authenticator app (Google Authenticator, 1Password, Authy, etc.) if you haven't already. The same TOTP code is used for adding wallets and toggling enforcement.

### Step 2 — Add your wallets

In **Dashboard → Settings → Recipient Wallets**:

1. Click **Add Recipient Wallet**
2. Paste the EVM address (`0x...`)
3. Optionally give it a name — if you leave it blank we'll call it **Wallet 1**, **Wallet 2**, etc.
4. Enter your 6-digit 2FA code
5. Click **Add wallet**

You can add as many wallets as you need. The list supports rename and delete.

### Step 3 — Turn on enforcement

In **Dashboard → Settings → Recipient enforcement**:

1. Flip the switch
2. A confirmation dialog opens — read it
3. Enter your 6-digit 2FA code
4. Click **Enable**

When you turn enforcement on, we automatically allowlist every destination wallet you've already used: payment-history merchant addresses, your current vault sweep address, your POS terminal addresses, and your POS global settings. The success toast tells you how many were imported. This means flipping the switch does not break your existing payment links, POS terminals, vault config, or API integrations.

You can flip enforcement off again at any time — that also requires a 2FA code, since disabling it removes a security guard.

***

## What changes when enforcement is on

### Dashboard payment-link form

The recipient address field becomes a dropdown listing your verified wallets. Free-text input is no longer available. The Token / Network selectors and everything else are unchanged.

### Vault Settings

The Wallet Address field becomes a dropdown of verified wallets.

### POS Terminal Setup

Creating or editing a POS terminal restricts the Wallet Address field to your verified wallets.

### Telegram Mini App

The "Enter merchant wallet address" step shows a picker of your verified wallets instead of a free-text input.

### Public API

Every endpoint that accepts a wallet address validates it against your verified list:

| Endpoint                     | Field checked                           |
| ---------------------------- | --------------------------------------- |
| `POST /api/payments`         | `merchant`                              |
| `POST /api/vault/v1/config`  | `walletAddress`                         |
| `PATCH /api/vault/v1/config` | `walletAddress`                         |
| `POST /api/pos/payments`     | terminal's configured `merchantAddress` |

Unknown addresses return **HTTP 422** with a typed error body so your integration can detect this case and surface a helpful message:

```json
{
  "error": "RECIPIENT_NOT_ALLOWLISTED: Recipient 0x... is not in your verified address book. Add it under Settings → Recipient Wallets first.",
  "code": "RECIPIENT_NOT_ALLOWLISTED",
  "helpUrl": "https://app.makapay.io/dashboard/settings#recipient-wallets"
}
```

If you receive a 422 with `code: "RECIPIENT_NOT_ALLOWLISTED"`, the address in the request needs to be added to your Recipient Wallets list with a 2FA code, then the same request will succeed.

***

## What does NOT change when enforcement is on

* Your API keys keep working as before. They can still create payments and update vault config — just only to wallets you've personally verified.
* Customer-side payment pages are unaffected. Customers paying your links don't see any change.
* Cross-chain payments, fees, plan tiers, and webhooks are unchanged.
* Existing payment links remain valid and continue to settle normally.
* Top-up payments (extending an existing payment) inherit the parent's wallet and don't re-run the check.

***

## Managing the list later

### Add a new wallet

You can add wallets at any time, whether enforcement is on or off. Each add requires a 2FA code.

### Rename a wallet

Inline edit in the Recipient Wallets list. No 2FA needed — a rename doesn't unlock a new destination.

### Remove a wallet

Click the trash icon. The wallet is removed from your verified list. If enforcement is on, you can no longer use that address as a payment destination until you re-add it.

### Backfilled wallets

Wallets imported during the OFF → ON flip carry a **backfilled** tag. They are valid recipients but you may want to review them — rename, remove ones you no longer use, or keep as-is.

***

## When to enable

Enable Recipient Wallets if any of the following apply:

* You issue API keys to scripts, servers, or third-party services.
* You operate POS terminals where staff or integrators can configure wallet addresses.
* You use the Telegram Mini App from devices that other people occasionally access.
* You want a second factor between a leaked credential and funds leaving your control.

If you run a small, single-operator setup with no API integrations and no POS, the feature still adds value but is less critical.

***

## FAQ

**Q: I lost access to my authenticator app — how do I manage wallets?** A: Recovery goes through your account's standard 2FA reset flow under **Settings → Two-Factor Authentication**. Once 2FA is re-enrolled, you can add wallets again. If enforcement is currently on and you cannot complete recovery, contact support before flipping it off so we can verify your identity through other means.

**Q: Can I have different lists per API key?** A: No — the list is account-level. Every API key on the account uses the same verified list. This makes the security model simple to reason about and impossible to bypass by creating a new key.

**Q: Does this affect customers who pay my links?** A: No. The check happens at payment-link **creation** time, not at payment time. Customers paying an already-created link see no change.

**Q: What about gas tank withdrawals or referral payouts?** A: Those are payout destinations, not payment recipients — they have their own dedicated 2FA flow and are not affected by this feature.

**Q: Can I bulk-import addresses via the API?** A: Not at the moment. Adding a wallet requires an interactive 2FA step that the API does not support. You add wallets through the dashboard; the API consumes them.

**Q: What happens to scheduled / recurring payments if I remove a wallet?** A: Existing payment links remain valid — the check only runs at creation. New payments targeting a removed wallet will be rejected with HTTP 422 until you re-add it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.makapay.io/security/recipient-wallets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
