Troubleshooting

Payments

The customer paid but my order is not marked paid

Work through this in order.

1. Call POST /v1/payment/verify with the token, from your server. This is authoritative — do not diagnose from your own database.

2. Read body.orderStatus. success: false with WaitingToConfirm means it is confirming normally. Wait.

3. If it is PartialPaid, the customer sent less than the amount owed. Compare expectedCryptoAmount and receivedCryptoAmount in the settlement object.

4. If it is Paid but your system did not act, your IPN did not land. Check your endpoint's logs. Verify is the fix — treat it as your reconciliation path.

5. If verify returns Invalid Token, either the token is wrong or you are using a different store's API key.

success: false but the payment looks fine

This is expected. success only means "the order is in Approve after this call". Branch on orderStatus. See Payment States and Confirmations.

The customer sent slightly too little

The order is PartialPaid and the checkout shows the remainder. Wallets that deduct their own fee from the amount sent cause this routinely.

If it is a recurring nuisance, set an underpayment tolerance for the store — up to 5%. Otherwise decide per order: wait, refund, or accept the shortfall.

The customer sent too much

The order is Paid and the whole amount received is yours. Nothing is refunded automatically. If you want to return the difference, issue a refund for the excess.

The customer paid after the window expired

Contact support with the transaction hash and the payment token. Do not fulfil until it is resolved, and do not assume the payment is lost.

The order timed out but the customer says they paid

Check the transaction hash on a block explorer against the address they were shown. Only orders still in Pending are timed out — if funds arrived, the order should not have timed out, so this usually means the payment went somewhere other than the address for that order. Contact support with the hash.

A second payment arrived on the same order

The remainder shown to the customer accounts for money already broadcast but not yet confirmed, specifically to avoid this. If it happened anyway, contact support with both transaction hashes.

Notifications

I am not receiving IPNs

• Confirm the IPN URL is set for the correct store in the merchant panel.

• It must be publicly reachable over HTTPS — not localhost, not behind a VPN, not IP-restricted to an office network.

• Return a 2xx quickly. A slow handler reads as a failure and gets retried.

• Check whether the method (POST or PUT) matches what your endpoint accepts.

Paymento retries up to 7 times over roughly 24 hours. Retries stop once you verify the payment.

Signature verification fails

• HMAC the raw request body exactly as received. Do not parse and re-serialise it first — key order and whitespace will change and the hash will not match.

• Use your store's secret key, not the API key.

• The header is X-HMAC-SHA256-Signature.

• Compare in constant time.

• Confirm you are using the secret from the same store that owns the payment.

I got the same IPN twice

Expected. Retries and your own polling can both arrive. Make the handler idempotent on the payment identifier.

API

API_KEY_MISSING / API_KEY_EMPTY / API_KEY_INVALID

The header is Api-Key. Missing means the header was absent; empty means it was present with no value; invalid means the key is not recognised. Check you are not sending a test key to production or the other way round.

Invalid Token on verify

Either the token does not exist, or it belongs to a different store than the API key you used. Store isolation is enforced — a key for store A cannot read store B's payments.

HTTP 429

You are being rate limited. Honour the Retry-After header. Back off rather than retrying tightly — tight retries extend the throttle.

Embedded wallet settlement

"Settlement destination is not configured"

Set a destination address for that asset in the merchant panel. Paymento will not choose one for you.

"Settlement destination is not authorized for this store"

Settlement can only go to the destination you configured for that asset, or back to your store wallet's own main address. If you want to send elsewhere, change the configured destination first.

Settlement will not start — balance

Network fees are covered from your Available balance. You need at least $5, or the estimated fee plus a 15% buffer if that is higher. Top up and retry.

My passkey prompt does not appear

• Are you on the device and browser where the passkey was registered? The panel shows recovery hints — device, browser, and passkey provider — to help you identify it.

• If your passkey is synced through a password manager or platform account, make sure that account is signed in on this device.

• Some browsers suppress the prompt in private/incognito windows or inside embedded webviews. Use a normal window.

The email code does not work

The code lasts five minutes, and so does the verified window after you enter it. If you took longer than that between steps, request a new one. Check spam.

A settlement failed

Failures are recorded per batch with a reason, and a failed batch can be retried from the panel. You will be asked for a fresh passkey approval — the previous signing session has expired by design.

Before retrying, check the transaction hash on a block explorer. A settlement that broadcast but isslow to confirm resolves on its own; re-running it is not what you want.

The panel says pending but the explorer says confirmed

Pending transactions are polled to confirmation in the background. Give it a few minutes. If it persists, contact support with the transaction hash.

Refunds

The refund option is not available

• The order must be Paid, Approve or PartialPaid.

• A payment can only be refunded once. If any refund has already been recorded against it — including a partial one — further refunds are closed. Contact support if you need to go beyond that.

• Passkey-signed refunds require an embedded-wallet store. Manual refunds, where you send from your own wallet and record the transaction, are available to all store types.

My manual refund hash was rejected

The hash is validated on-chain. Check that it is the right transaction, on the right network, to the right payer address, and that it has actually been broadcast.

The refund amount was rejected

Refunds may exceed the order amount by at most 10%, and any amount above the order amount requires an explicit confirmation. Check the remaining refundable amount shown in the panel.

Store and account

My store cannot accept payments

Only stores with status Active process payments. Check the store's status in the panel.

A store may be suspended because of an account, billing, compliance, security, or administrative restriction. Contact Paymento Support for the reason and available next steps.

My store is suspended and I have funds in the embedded wallet

A suspended store cannot run settlement from the panel. Restore the store — bring billing current and contact support — and settlement becomes available again.

Your keys and on-chain funds are not affected by the suspension. Custody does not run through Paymento's account state, so with a wallet backup you retain access to the wallet regardless.

My customer cannot pay — there is no address or QR code

Check the combination. On a Bring Your Own Wallet store, Ethereum, ERC-20, Solana, SPL, Tron and TRC-20 all require the customer to connect a wallet — there is no deposit-address option. On an embedded wallet store, Tron and TRC-20 (including USDT-TRC20) also require a connected wallet.

If your customers pay from exchange accounts or wallets that cannot connect to a website, move them to an asset that supports plain deposits for your store type — see Supported Networks and Assets.

Why can't I get a deposit address for USDT-TRC20?

Because an embedded wallet receives all Tron payments at a single address, so a payment cannot be matched to an order by where it landed — it has to be identified by transaction hash, which requires the payer's wallet to report it. This follows from how Tron settlement works. There is no setting to change it. USDT on Ethereum or Solana gives you the deposit-address flow.

I cannot create a store

Store creation is restricted to the account owner, and your plan limits how many embedded-wallet stores you can hold. See Pricing.

Still stuck

Contact Paymento support with:

• your store identifier

• the payment token or payment id

• the transaction hash, if any

• timestamps in UTC

• what you expected and what happened

For a suspected security issue, use the disclosure contact at api.paymento.io/.well-known/security.txt rather than a general support channel.