> 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/guides/merchant-guide.md).

# Merchant Guide

Complete guide for merchants using MakaPay to accept cryptocurrency payments.

***

## Dashboard Overview

### Payments

View and manage all your payment links:

* Create new payment links
* Filter by status, date, network
* View payment details and transaction history
* Cancel pending payments
* Manually withdraw partial payments

### Gas Tank

Manage your unified gas balance:

* View current balance
* Deposit USDT
* Track deposit history
* Monitor gas usage

### API Keys

Manage programmatic access:

* Create new API keys
* View key usage statistics
* Revoke compromised keys

### Webhooks

Configure event notifications:

* Set webhook URL
* View delivery logs
* Retry failed deliveries

### Referrals

Earn rewards by referring other merchants:

* Generate referral links with your configured markup
* Track referred users and per-merchant earnings
* Earn 90% of your markup on every transaction from referred merchants

***

## Payment Configuration

### Fee Modes

MakaPay offers flexible fee configurations with two independent toggles:

#### Gasless Mode

Controls **WHERE** fees come from:

| Gasless           | Fee Source                            |
| ----------------- | ------------------------------------- |
| `false` (default) | Gas Tank (merchant pays)              |
| `true`            | Payment Chain (deducted from payment) |

#### Payer Covers Fee

Controls **WHO** pays fees:

| Payer Covers Fee  | Fee Handling                   |
| ----------------- | ------------------------------ |
| `false` (default) | Deducted from payment amount   |
| `true`            | Added on top of payment amount |

#### Combined Modes

| Gasless | Payer Covers | Customer Sends | Merchant Receives | Gas Tank  |
| ------- | ------------ | -------------- | ----------------- | --------- |
| OFF     | OFF          | $100           | $100              | Pays fees |
| OFF     | ON           | $100 + fees    | $100              | $0        |
| ON      | OFF          | $100           | $100 - fees       | $0        |
| ON      | ON           | $100 + fees    | $100              | $0        |

### Block Confirmations

Configure reorg protection:

* **Default**: 1 confirmation
* **High-value payments**: Consider 3-6 confirmations
* **MakaChain**: Instant finality, 0 confirmations safe

### Payment Expiration

* Payment links expire after **24 hours**
* Expired payments can be cancelled
* Funds sent to expired addresses can be recovered

***

## Gas Tank Management

### How It Works

1. You deposit USDT to your Gas Tank on MakaChain
2. When payments are settled, gas costs are deducted from your balance
3. Your balance covers settlements across ALL supported networks

### Deposit Process

1. Navigate to **Gas Tank** in the dashboard
2. Click **Get Deposit Address**
3. Send USDT (on MakaChain) to the displayed address
4. Funds are credited automatically after confirmation

### Balance Recommendations

| Monthly Volume   | Recommended Balance |
| ---------------- | ------------------- |
| < 100 payments   | $10 - $25           |
| 100-500 payments | $25 - $50           |
| 500+ payments    | $50+                |

### Low Balance Alerts

When your balance falls below $5, you'll receive:

* Dashboard notification
* Email alert (if configured)
* Payments will show "Awaiting Gas" status

***

## Handling Special Cases

### Partial Payments (Underpayments)

When a customer sends less than the requested amount:

1. Payment shows status `withdraw_request`
2. Navigate to payment details
3. Click **Manual Withdraw**
4. Process occurs in two steps:
   * Deploy wallet (if needed)
   * Withdraw funds
5. You receive the partial amount minus fees

### Overpayments

When a customer sends more than requested:

* The full amount is settled to your wallet
* No action required

### Wrong Token / Wrong Chain Recovery

If a customer sends the wrong token or on the wrong blockchain:

1. Navigate to the payment in your dashboard
2. Click **Recover Tokens** button
3. The system scans all supported chains for recoverable tokens
4. Click **Recover** next to any found tokens
5. Tokens are sent directly to your merchant address

**Requirements**:

* Minimum **$0.10 USDT** in Gas Tank for recovery fees
* No platform fee - merchant receives 100% of recovered tokens

For detailed instructions, see the [Token Recovery Guide](https://docs.makapay.io/guides/token-recovery.md).

### Expired Payments

If funds are sent after expiration:

1. Payment remains in expired state
2. Use **Manual Withdraw** to recover funds
3. Standard fees apply

***

## Address Book

Save frequently used merchant addresses:

1. Go to **Dashboard > Settings > Address Book**
2. Click **Add Address**
3. Enter the address and a label
4. Use saved addresses when creating payments

For accounts with [Recipient Wallets enforcement](https://docs.makapay.io/security/recipient-wallets.md) turned on, this list becomes the *only* set of addresses that can receive payments — adding a wallet there requires a 2FA code and is the recommended pattern for any account with API keys or POS terminals.

***

## Fee Structure

### Rates

| Merchant Type      | Platform Fee | Details                                              |
| ------------------ | ------------ | ---------------------------------------------------- |
| **Direct**         | 1.0% + $0.10 | Standard rate for all merchants                      |
| **Agent-Referred** | 1% + $0.10   | Same fee as direct; your agent is paid out of the 1% |
| **Member**         | 0%           | Invite-only, no fees                                 |

***

## Security Best Practices

### Recipient Wallets enforcement

For accounts that issue API keys or operate POS terminals, turn on **Recipient Wallets** enforcement under **Dashboard → Settings**. This restricts every payment destination — dashboard, API, POS, vault, and Telegram — to a list you've personally approved with a 2FA code. Even a leaked API key cannot redirect funds to an unknown wallet. See [Recipient Wallets & 2FA Enforcement](https://docs.makapay.io/security/recipient-wallets.md) for setup.

### API Key Security

* Never expose API keys in client-side code
* Rotate keys periodically
* Use separate keys for development and production
* Revoke unused keys immediately
* Pair keys with [Recipient Wallets enforcement](https://docs.makapay.io/security/recipient-wallets.md) so a leaked key cannot redirect funds

### Wallet Security

* Use a dedicated merchant wallet
* Consider a multi-sig for high-value operations
* Never share private keys

### Webhook Verification

* Always verify webhook signatures
* Use HTTPS endpoints only
* Implement idempotency for duplicate events

***

## Compliance

### OFAC Screening

MakaPay screens transactions against OFAC sanctions lists:

* Payments from sanctioned addresses are blocked
* View screening status in **Dashboard > Compliance**

### Transaction Records

* All transactions are recorded on-chain
* Export transaction history from the dashboard
* Maintain records for tax and compliance purposes

***

## Integrations

### E-commerce Platforms

* **WooCommerce**: Plugin available (coming soon)
* **Shopify**: App available (coming soon)
* **Custom**: Use the REST API

### Point of Sale

* Generate payment links on-demand
* Display QR codes for in-person payments
* Use webhooks for real-time confirmation

### Invoicing

* Create payment links for each invoice
* Include `orderId` to match payments to invoices
* Track payment status via dashboard or API

***

## FAQ

### How long does settlement take?

* **MakaChain**: Instant (1-2 seconds)
* **Ethereum**: 1-2 minutes (depends on block confirmations)
* **Polygon/BSC**: 30 seconds - 1 minute

### What if my Gas Tank runs out?

* Payments remain in "Paid" or "Awaiting Gas" status
* Settlement resumes automatically after you deposit
* No payments are lost

### Can I accept payments without a Gas Tank?

Yes, use **Gasless mode**:

* Fees are deducted from the payment amount
* No Gas Tank balance required
* Customer or merchant absorbs fees (configurable)

### What tokens can I accept?

Built-in tokens:

* USDT on all networks
* USDC on Ethereum, Polygon, BSC
* XRP, TRX on BSC (non-stablecoin)

You can also accept **any ERC-20 token** on Ethereum, Polygon, BSC, or Base using the [Custom Tokens](https://docs.makapay.io/guides/custom-tokens.md) feature. Add a token by its contract address and MakaPay will handle the rest.

### How do refunds work?

* MakaPay does not process refunds
* Refund customers directly from your wallet
* Or create a payment link for the customer to receive funds

***

## Support

* **Dashboard**: Use the support chat
* **Email**: <support@makapay.io>
* **Response Time**: 24-48 hours (business days)


---

# 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/guides/merchant-guide.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.
