Troubleshooting

❌Errors

Things don’t always go as planned. This section lists the most common errors you might encounter when using the API, what they mean, and how to resolve them. Use it as a quick reference during development and debugging.

HTTP Code	Endepoint	Typical Cause	Quick Check
400 Bad Request	POST /payment/request	Missing or malformed JSON; required field omitted	Ensure body includes amount, currency, and redirect_url exactly as documented
401 Unauthorized	Any	Missing or expired access_token	Call POST /oauth/token again and set Authorization: Bearer <token>
403 Forbidden	POST /oauth/token	Wrong client_id / client_secret or bad Basic Auth header	Re‑encode credentials and retry
404 Not Found	GET /payment/ request/{id}	ID not present in environment	Confirm the ID and that you are using the correct base URL (sandbox vs. production)
422 Validation Exception	POST /payment/request	Business‑rule failure (e.g., unsupported currency, negative amount)	Use a valid ISO 4217 code; amount must be a positive integer
500 Server Error	Any	Unexpected internal condition	Retry with back‑off; contact support if persistent
429 Too Many Requests	Any	Rate limit exceeded (more than 5 requests per second per API key)	Slow down requests, implement retry with exponential backoff, and ensure you stay within rate limits

---

📚Glossary

The glossary breaks down key concepts, technical terms, and acronyms used throughout the API and dashboard. It’s a handy reference to help you stay on the same page while building your integration.

Term	Definition
access_token	Bearer credential returned by POST /oauth/token used to authorize further requests
amount	Smallest currency unit (e.g., "100" = $100 USD)
client_id / client_secret	Credentials created in the dashboard; used with Basic Auth to obtain a token
currency	Three‑letter code such as USD
grant_type	OAuth field indicating the authentication flow; always client_credentials here
Payment Request	Resource representing a one‑time charge and hosted checkout link
redirect_url	HTTPS location where the payer is sent after checkout
reference_id	Optional string you supply for internal correlation
status	Lifecycle stage of a Payment Request: pending, paid, expired, cancelled
token_type	Value identifying the auth scheme, always Bearer
UUID	Universally Unique Identifier used for resource IDs