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

# Acquiring API

Choose and integrate the MusePay crypto acquiring mode that fits your payment flow.

MusePay supports two crypto acquiring modes. Choose **Wallet Mode (Dedicated User Address)** when each user needs a reusable deposit address, or **Checkout Mode (Per-Order Address Allocation)** when your system creates a payment order before every payment.

Both modes notify your system after a deposit is detected. The main difference is when you create the local order and how long the receiving address remains associated with the payment context.

## Choose an integration mode

|                    | Wallet Mode (Dedicated User Address)               | Checkout Mode (Per-Order Address Allocation)          |
| ------------------ | -------------------------------------------------- | ----------------------------------------------------- |
| Address allocation | One fixed address for each user                    | One temporary address for each order                  |
| Address lifetime   | Reusable for future deposits                       | Valid for one day by default                          |
| Local order timing | Create it after receiving the deposit notification | Create it before requesting a payment address         |
| Amount handling    | Credit the actual amount reported by MusePay       | Reconcile the deposit against the amount in the order |
| Best suited for    | Wallet top-ups, stored balances, recurring users   | E-commerce checkout and one-time payments             |

## Wallet Mode (Dedicated User Address)

Wallet Mode assigns a fixed deposit address to each user. The user can deposit to that address at any time. After MusePay detects and confirms the deposit, it sends your system an order webhook with the received amount. Your system then creates a local order and credits the user's balance.

<figure><img src="https://4031060132-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F847OCU8wHOemogNwwSWc%2Fuploads%2Fgit-blob-5ba964aa575472d8d02f0d914aed2bd6b0c4cf4f%2Facquiring-wallet-mode.png?alt=media" alt="Dedicated User Address flow"><figcaption><p>One reusable deposit address is associated with each user.</p></figcaption></figure>

### Integration flow

1. Complete [Authentication](/integration/authentication.md) and implement [order webhooks](/integration/webhook/order.md).
2. Call the [Deposit Address](/reference/api-reference/acquiring-api/wallet-mode.md#deposit-address) endpoint with the asset and your `customer_ref_id` to obtain the user's address.
3. Store the relationship between the user, asset, and returned address.
4. Allow the user to deposit to the address whenever needed.
5. When the webhook arrives, verify it and use the reported amount and `customerRefId` to create a local order and credit the correct user.
6. Use the [Query](/reference/api-reference/acquiring-api/wallet-mode.md#query) endpoint when you need to retrieve the transaction details.

{% hint style="warning" %}
Treat webhook processing as idempotent. The same event must not credit a user's balance more than once.
{% endhint %}

## Checkout Mode (Per-Order Address Allocation)

Checkout Mode creates a new payment context for each order. Your system creates the order first, and MusePay returns a temporary receiving address that is valid for one day by default. MusePay sends an order webhook after the user deposits.

<figure><img src="https://4031060132-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F847OCU8wHOemogNwwSWc%2Fuploads%2Fgit-blob-b2134347b6c790a888f821b805852a7baf44d6d4%2Facquiring-order-mode.png?alt=media" alt="Per-Order Address Allocation flow"><figcaption><p>Each order receives its own temporary payment address.</p></figcaption></figure>

### Integration flow

1. Complete [Authentication](/integration/authentication.md) and implement [order webhooks](/integration/webhook/order.md).
2. Create the local order in your system with a unique request ID and the expected amount.
3. Call [Create Checkout Order](/reference/api-reference/acquiring-api/checkout-mode.md#create-checkout-order) to obtain the order number, receiving address, and checkout URL.
4. Present the address or checkout URL to the user before it expires.
5. When the webhook arrives, verify it and reconcile the reported payment with your local order before fulfilling it.
6. Use [Query Order](/reference/api-reference/acquiring-api/query-order.md) to retrieve the latest order status when needed.

{% content-ref url="/pages/XI9bfA8ABdjduaNk4pZj" %}
[Checkout Payment Methods](/integration/acquiring-api/checkout-payment-methods.md)
{% endcontent-ref %}

{% hint style="info" %}
Payments can be underpaid, overpaid, or received after the address expires. Review [Checkout Payment Amount Handling](/integration/acquiring-api/checkout-payment-amount-handling.md) before defining your fulfillment rules, and base fulfillment on the webhook or query result rather than the initial create-order response.
{% endhint %}

{% content-ref url="/pages/AOFk2tim2pUyjnItChNX" %}
[Checkout Payment Amount Handling](/integration/acquiring-api/checkout-payment-amount-handling.md)
{% endcontent-ref %}

## Related references

* [Supported Assets](/reference/supported-assets.md)
* [Wallet Mode endpoints](/reference/api-reference/acquiring-api/wallet-mode.md)
* [Checkout Mode endpoint](/reference/api-reference/acquiring-api/checkout-mode.md)
* [Checkout Payment Methods](/integration/acquiring-api/checkout-payment-methods.md)
* [Checkout Payment Amount Handling](/integration/acquiring-api/checkout-payment-amount-handling.md)
* [Order webhook](/integration/webhook/order.md)
* [Order statuses](/reference/enums/order-status.md)