Troubleshooting by Symptom
For a specific code, go to /agents/errors/error-<code>, for example error 420. The Errors page has the full list.
Payments
| Symptom | Cause | Fix |
|---|---|---|
| Every card fails on the hosted page | No terminal connected to the account | Error 420: PayMe connects one |
generate-sale fails only in development |
A local callback or return URL | Error 21: leave the field out |
| A payment charged a hundredth of the expected amount | Whole currency units sent instead of minor units | Money |
| A saved card worked once and then stopped | The token wasn't permanent | Error 604 |
| A marketplace token says "Buyer not found" | The uuid was sent as buyer_key |
Send it as token: Saved Cards |
Sale shows partial-refund after a full refund in parts |
Expected | Track the total yourself: Capture, Refund, Void |
An authorized sale isn't in get-transactions |
The default query skips uncaptured authorizations | Send transaction_type: 40 |
| Error messages in Hebrew | No language field |
Send language: "en" |
| A plain refusal arrives as HTTP 500 | Normal for PayMe | It's a refusal, not an unknown outcome: Reading a failure |
A sale is failed, then later completed |
The buyer retried on the same page | Expected: Checkout |
get-buyer-key answers 603 with the MPL |
The sale didn't send buyer_is_private: true |
Saved Cards |
A voided sale has no rows in get-transactions |
The default query leaves it out | Void |
Callbacks
| Symptom | Cause | Fix |
|---|---|---|
| A real sale callback is rejected as wrongly signed | Wrong partner secret, partner key and secret from different accounts, or the wrong transaction_id field hashed |
Fix the settings. Never loosen the check. See Callbacks (Partner) |
| A forged test callback is rejected | Expected | Nothing |
| A paid subscription stays initial, with callbacks recorded as unsigned or rejected | The handler expects signed subscription callbacks | Re-read with get-subscriptions: Subscriptions |
| No seller callbacks arrive | They go only to the Default Callback URL | Ask PayMe to set it |
| No callbacks arrive at all | The address is unreachable, or PayMe is skipping a failing domain | Check it from outside your network, answer below 400, and reconcile meanwhile |
| The same callback arrives repeatedly | Your endpoint answers 400 or above, or too slowly | Answer below 400 quickly, and work afterwards |
Your own setup
| Symptom | Cause | Fix |
|---|---|---|
Startup log shows a localhost callback address after a tunnel was configured |
The server started before the settings changed | Restart it |
| The configured public address is an example value | The placeholder was copied | Use the real address the tunnel printed |
| Public address returns Cloudflare 1033 | The tunnel process exited, and a quick tunnel's address has gone | Restart it, update the settings, restart the server, and tell PayMe the new address if it's the Default Callback URL. A named tunnel on your own domain avoids this |
| Public address returns 502 | The tunnel is up and your server isn't listening | Start the server |
Server refuses to start on market_fee |
A value like 1% |
A plain number |
| Pasted error lines don't match what you see now | They may predate the fix | Compare their timestamps with the server's start time |
If none of this helps, send partners@payme.io the session value with the request and response, after removing credentials.