Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

PreviousSecurity Model
NextTroubleshooting

Last updated