Reference

7. Transaction Statuses

Status	Description
pending	Created, awaiting result
approved	Approved (callback approve)
rejected	Rejected/cancelled (callback reject)

---

8. Rate Limiting

• Default: 100 requests/minute (token bucket, per API key or IP).
• On limit, HTTP 429:

{ "success": false, "message": "Rate limit exceeded. Please try again later." }

---

9. Error Codes

HTTP	Meaning
200	Success
400	Bad request / validation error / invalid callback URL
401	Authentication failed (HMAC)
403	Insufficient permission
404	Not found
413	Request too large (>1 MB)
429	Rate limit exceeded
500	Server error

One error envelope everywhere: { "success": false, "message": "<reason>" }.

Produced by	Envelope	Applies to
The endpoints themselves	{ "success": false, "message": "<reason>" }	Validation errors, business rejections, callback-URL errors, transaction not found, internal errors
The auth and rate-limit middleware (before the endpoint runs)	{ "success": false, "message": "<reason>" }	All 401 responses (section 9.1) and the 429 rate-limit response
The global request-size middleware	{ "status": false, "msg": "Request too large" }	413 only — the one exception (see below)

413 is the single exception. RequestSizeLimitMiddleware is registered globally (it also guards the internal panel API, not just this payment API), so its body deliberately stays on the older { status, msg } shape. Every other error you can receive uses { success, message }.

Always branch on the success flag rather than the HTTP code alone — business rejections can arrive as HTTP 200.

9.1 Authentication failures (401)

AuthMiddleware rejects the request before it reaches any endpoint. Each returns HTTP 401 with { "success": false, "message": … }:

message	Cause & fix
Authentication required: missing headers	One of X-API-Key / X-Signature / X-Timestamp / X-Nonce is absent
Invalid API key	X-API-Key doesn't match an active account
Invalid signature	HMAC mismatch — recompute the signature per section 4 and make sure the body you sent is byte-identical to the body you signed
Invalid timestamp: …	X-Timestamp is outside the accepted skew window (too old or in the future) — send the current Unix time in seconds and sync your clock
Invalid nonce: …	X-Nonce is malformed or replayed (nonce already used (replay detected)) — generate a fresh random nonce for every request

9.2 Request errors (4xx)

Returned by the endpoint after auth passes, in the { "success": false, "message": … } envelope:

HTTP	message (examples)
400	Invalid request format, Validation failed: <FieldName> …, X-Callback-URL must match the firm's registered webhook host, Callback URL not configured on provider, Invalid callback URL: … (SSRF guard)
403	Firm not identified, Firm is not linked to an active provider
404	transaction not found (status query endpoints)
413	Request body larger than 1 MB — returned by the global size middleware in the legacy { "status": false, "msg": "Request too large" } envelope
500	An internal error occurred. Please try again later.

The 429 rate-limit response uses the same envelope: { "success": false, "message": "Rate limit exceeded. Please try again later." }.

A duplicate reference is not an HTTP error: the API returns 200 with { "success": false, "message": "Bu islem numarasi zaten kullanilmis" }. Always check the success field, not just the HTTP code.

Validation messages use the Go field name, not the JSON field name. A missing bank_code yields Validation failed: BankCode is required, not bank_code is required. The mapping is: bank_code → BankCode, user_id → UserID, national_id → NationalID, first_name → FirstName, last_name → LastName, reference → Reference, amount → Amount, username → Username, iban → IBAN, return_url → ReturnURL. Only the first validation error is reported.

Tags with no dedicated case in the validator's switch fall back to <Field> is invalid. The conditional tags behind the hosted payment page (required_if, excluded_if) do have dedicated cases, so the amount/redirect rule reports which direction was violated rather than a generic message. See section 5.5.

---