| 401 on every call |
Key mistyped, regenerated, or with stray whitespace |
Regenerate in the portal and update the configuration |
404 code: not_found - The route ... could not be found |
/v1 missing from the base, or a call to an endpoint that is not there |
Fix the URL. No identifier change helps |
404 code: transaction_id_expected |
Numeric payment id passed to void, refund or a receipt |
Pass transaction_id, not id (13.1) |
422 code: tokenized_charge_disabled on a saved-card route |
Mode 3A is not enabled for the account |
Ask ROKI to enable it. No field value fixes it (23.1.0) |
404 code: payment_not_found (Pago no encontrado) |
Id from the other environment (created with sk_test_, queried with sk_live_ or vice versa) |
Use the key from the same environment |
| Errors classified wrongly after upgrading |
Client matches "could not be found" to detect a bad route |
Branch on code - since 2026-08-21 the numeric-id mistake no longer carries that text (12.3) |
422 about currency_code in sandbox |
Sandbox not provisioned for the merchant |
16.2 - ask ROKI to enable it |
| Payment created but without tax/tip/fee |
Field name misspelled and ignored |
12.1 - read warnings in the response, then compare against openapi.yaml |
| No webhooks arriving |
Endpoint registered in the wrong environment, URL not public, or not HTTPS |
Check the sandbox/production toggle and "Entregas recientes" in the portal |
| Webhooks arrive but the signature fails |
Signing re-serialized JSON instead of the raw body |
14.4, rule 1 |
| Paid orders stuck as pending |
Relying on success_url to confirm |
9.3 - confirm via webhook or lookup |
| Duplicate payments |
Missing Idempotency-Key (external_reference is not unique) |
11 |
| Checkout link dead after one payment |
reusable defaults to false and the link is consumed |
8.4 |
| Expiry looks wrong by six hours |
Timestamps parsed as UTC instead of UTC-6 |
12.4 |
