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

# Merchant Responsibilities

Paymento secures custody, monitoring and notification. Your integration secures the rest. This page is what you own.

### 1. Never mark an order paid because a browser said so

**This is the single most important item on this page.** It is the mistake that most often turns a\
correct payment gateway into a free shop.

After paying, your customer's browser is redirected back to your site. That redirect carries\
parameters. Those parameters come from the customer's browser, which means they come from the customer, which means anyone can set them to anything.

**Wrong:**

```
GET /payment/return?status=7&order=1234
    → order marked paid
```

Anyone can place an order, skip paying, and request that URL by hand.

**Right.** Your return URL is a **redirect and nothing more**. It reads the order's existing status\
and sends the customer to the appropriate page. It writes nothing.

Only two things may change an order's state:

1. **The signed IPN.** Recompute the HMAC-SHA256 of the raw request body using your store's secret key, compare it to the `X-HMAC-SHA256-Signature` header **in constant time**, and only then trust the payload.
2. **Your own server-side verify call.** `POST /v1/payment/verify` with the token, from your server, using your API key.

Belt and braces is fine: verify the signature *and* call verify.

### 2. Read `orderStatus`, not just `success`

`success: false` from verify does **not** mean the payment failed. It means the order is not yet in `Approve` — it may be waiting for confirmations, partially paid, or still pending.

Branch on `body.orderStatus`. Treating `success: false` as failure will cancel orders your customers have genuinely paid for. See Payment States and Confirmations.

### 3. Make your IPN handler idempotent

Paymento retries failed notifications — up to 7 attempts over roughly 24 hours. Your endpoint may be called more than once for the same payment, including when your first response was slow rather than wrong.

Key your handling on the payment identifier and make a repeat call a no-op. Respond quickly with a 2xx and do slow work asynchronously; a handler that times out looks like a failure and will be retried.

### 4. Protect your keys

Your store's API key and secret key are bearer credentials.

* Server-side only. Never in browser JavaScript, a mobile app bundle, or a public repository.
* Environment variables or a secrets manager, not source control.
* Rotate if exposed, and rotate on staff changes.
* Separate stores for test and production, so a leaked test key touches nothing real.

The secret key is what makes signature verification meaningful. If it leaks, an attacker can forge IPNs that pass your check.

### 5. Look after your wallet

**Bring Your Own Wallet** — backups and recovery of your wallet are yours. Paymento never had the key and cannot help you recover it. Verify that addresses Paymento derives appear in your wallet before taking real payments: send a small test payment and confirm you can spend it.

**Embedded wallet** — your passkey is the wallet. Use a synced passkey provider, protect the account that syncs it, and settle regularly so the balance at risk stays small. 

### 6. Keep your Paymento account secure

Enable TOTP two-factor authentication. Use scoped sub-user permissions rather than sharing the owner login. Remove access when people leave.

The account owner controls store creation, settlement destinations and API keys — treat it as privileged.

### 7. Keep your settlement destination correct

Settlement can only go to the destination you configured or back to your own wallet. That protects you from an attacker redirecting funds; it does not protect you from your own typo.

Check the address whenever you change it, and check the destination shown to you before you approve a settlement. On-chain transfers do not reverse.

### 8. Keep a Paymento balance

Fees and settlement network fees are drawn from your Available balance. If it runs dry, settlements will not start and subscription lapses can suspend a store. Top up before you need to.

### 9. Handle partial payments deliberately

A customer can send less than the full amount. The checkout shows them the remainder, but you should decide your own policy: wait for the balance, refund, or accept the shortfall.

If small shortfalls from fee-deducting wallets are a recurring nuisance, set an underpayment\
tolerance for your store — maximum up to 5%.

### 10. Test before you go live

Use testnet assets and a test store to run the full path end to end: request, checkout, payment, confirmation, IPN, verify, refund. Deliberately test the failure cases — an IPN your server rejects, a partial payment, an expired token because those are the paths you will meet in production.

### 11. Keep integrations current

If you use the WooCommerce, WHMCS or OpenCart integration, run the latest release and watch for security updates. If you wrote your own, re-read item 1 on this page whenever you touch the return-URL or IPN handler.

### Quick checklist

* [ ] Return URL redirects only — writes nothing
* [ ] IPN signature verified with constant-time comparison
* [ ] Server-side verify call before fulfilment
* [ ] Branch on `orderStatus`, not `success`
* [ ] IPN handler is idempotent and responds fast
* [ ] Keys server-side, out of source control
* [ ] Two-factor authentication on your Paymento account
* [ ] Wallet backup verified (or passkey synced and settlement scheduled)
* [ ] Settlement destination checked
* [ ] Available balance topped up
* [ ] Full path tested on testnet, including failures
* [ ] Plugins on the current version