> 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/faq.md).

# FAQ

Frequently asked questions about MakaPay.

***

## Payments

### How long does settlement take?

* **MakaChain**: Instant (1-2 seconds)
* **Ethereum**: 1-2 minutes (depends on block confirmations)
* **Polygon/BSC**: 30 seconds - 1 minute
* **Cross-chain via deBridge**: \~60–90s + destination block confirmations (similar end-to-end to same-chain on Ethereum)

### What if my Gas Tank runs out?

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

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

Yes, use **Gasless mode**. Fees are deducted directly from the payment amount, so no Gas Tank balance is required. Note that gasless mode only works with stablecoins or tokens that have a known USD price.

### How do refunds work?

MakaPay does not process refunds. Refund customers directly from your wallet, or create a new payment link for the customer to receive funds.

### Can a customer pay with a different token or chain than I requested?

**Yes**, via the **Cross-Chain Payments** feature. The customer connects their wallet (EVM, Solana or Tron) on the payment page, picks any supported token from any supported chain, and we use [deBridge](https://debridge.com/) to swap and deliver exactly what you asked for to your CREATE2 address. From your perspective, nothing changes — you receive the same amount, same token, same chain. See the [Cross-Chain Payments guide](https://docs.makapay.io/features/cross-chain-payments.md) for details.

### Why is my payment expiry getting extended automatically?

When a customer initiates a cross-chain swap, Makapay extends the payment's expiration window by 15 minutes so the system keeps watching the destination address while the swap settles. You'll see a blue "Cross-chain payment in flight" banner on the payment page during this window. Once the swap fulfils (or is auto-cancelled), the regular expiry rules apply.

### Can I cancel a payment while a cross-chain swap is in flight?

No — the cancel button is locked while a deBridge order is being filled. This protects the customer's funds from being orphaned at the CREATE2 address. The lock releases after the swap fulfils (payment completes normally) or auto-cancels (after 5 minutes in `Created` state).

### How do I export all my payments?

Use the `GET /api/v1/payments` endpoint — it returns your payments newest-first with cursor pagination. Walk `nextCursor` until `hasMore` is `false`. Authentication accepts either an `x-api-key` header or an active dashboard session cookie. Filter by `?status=` to narrow the result. See [API Reference: List Payments](https://docs.makapay.io/developers/api-reference.md#list-payments).

***

## Custom Tokens

### Can I accept any ERC-20 token?

**Yes.** Using the [Custom Tokens](https://docs.makapay.io/guides/custom-tokens.md) feature, you can accept any ERC-20 token on Ethereum, Polygon, BSC, or Base. Go to **Dashboard > Payments > Create Payment**, click the token dropdown, and select **"+ Add Custom Token"** at the bottom. Paste the token's contract address, click **Lookup**, and save it. The token will then appear in your token dropdown for future payments.

### What if there's no price for my custom token?

If the Alchemy Prices API and the TrustedOracle do not have a price for your token, you must provide a **custom USD price** manually. When adding the token, a "Price (USD)" field will appear with a warning that no automatic price is available. Enter the current USD price per token (e.g., `0.00001234`). You can also provide the price via the API using the `customPriceUsd` field in the payment creation request.

Keep in mind that custom prices are static and do not update automatically. If the token is volatile, set a **1-hour expiration** on payment links to limit price drift.

### How are fees calculated for custom tokens?

Custom tokens use the **same fee structure** as all other tokens:

| Component          | How It Works                                                               |
| ------------------ | -------------------------------------------------------------------------- |
| **Platform Fee**   | Percentage of the requested amount (same as stablecoins)                   |
| **Processing Fee** | $0.10 USD converted to token units using the token's price                 |
| **Gas Fee**        | Estimated gas cost in USD converted to token units using the token's price |

The conversion formula is:

```
Fee in tokens = Fee in USD / Token Price in USD
```

For example, if a token is worth $0.05, the $0.10 processing fee equals 2.00 tokens. See [Fee Structure - Custom Token Fee Calculation](https://docs.makapay.io/guides/fee-structure.md#custom-token-fee-calculation) for detailed examples.

### Do custom tokens work with all fee modes?

Yes. Gas Tank mode, Gasless mode, and Payer Covers Fee mode all work with custom tokens. The only restriction is that gasless mode requires a known token price (from Alchemy, the TrustedOracle, or a custom price). If no price is available, MakaPay automatically falls back to Gas Tank mode.

### Can I use custom tokens in POS?

Yes. Custom tokens appear in the POS token selection grid alongside built-in tokens. They are marked with a **"Custom"** badge. The POS automatically fetches the token's price to calculate the equivalent amount.

***

## Fees

### Why is there a processing fee?

The $0.10 processing fee covers settlement event recording on MakaChain, cross-chain coordination infrastructure, and 24/7 monitoring and settlement services.

### Can I avoid gas fees entirely?

Yes, by accepting payments only on MakaChain (free gas) or by using gasless mode where gas fees are deducted from the payment amount.

### Do fees change?

Platform fees are fixed based on your merchant type (direct, agent-referred, or Member). The processing fee ($0.10) is fixed. Gas fees vary with network congestion.

***

## Vault

### What does a vault deposit cost?

One fixed **1% Vault fee**. If no conversion succeeds, the fee is taken from the token being swept. After a successful Auto-Conversion, deBridge's route includes MakaPay's **6 bps affiliate fee**, then the single 1% Vault fee is charged from the realized converted output; no source-token 1% is also charged. See [Vault System — Fee Structure](https://docs.makapay.io/guides/vault.md#fee-structure) for details.

### How do withdrawals work with the vault?

Vault withdrawals are **non-custodial** — MakaPay never holds or moves your funds. Your backend files a withdrawal request via the API, an operator approves it in the dashboard (**Platform Wallets → Withdrawals**) by signing the payout from your own wallet, and MakaPay verifies the transfer on-chain before marking it completed. MakaPay charges no fee on withdrawals; the wallet that signs the payout pays the on-chain network gas directly. If a request is rejected (or you cancel it via the API), re-credit the player's balance on your side. See [Vault System — Withdrawals](https://docs.makapay.io/guides/vault.md#withdrawals) for the full lifecycle, API, and webhook reference.

***

## Support

Questions not answered here?

* Email: <support@makapay.io>
* Dashboard: Use the support chat
* POS-specific questions: See [POS FAQ](https://docs.makapay.io/point-of-sale-pos/faq.md)


---

# 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/faq.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.
