FAQ

Payment Sets & POS Rates

Question: Why does an empty list return from /pws/paymentSet or /pws/paymentOptions calls?

Answer

• There may be no active payment set defined under the Tenant associated with the relevant AccessToken.

• The currencyCode or paymentSetId parameters may be sent incorrectly or missing.

• If the submitted BIN number is not defined or the related bank’s POS is not included in the payment set, the list will be empty.

Question: Why are installment rates not visible?

Answer

For some POS definitions, isVisibleCommRate may be false. In this case, the rates are hidden by the system, but calculations continue to be performed in the background.

Payment Initiation (3D / Non-3D)

Question: Why do I receive a redirectUrl when I send use3D = true?

Answer

In the 3D Secure flow, the user must complete OTP verification.

The redirectUrl is the URL where the user must be redirected to the bank’s 3D authentication page.

The payment is not completed unless this redirection occurs.

Question: Does the payment complete without an OTP step when I send use3D = false?

Answer

Yes. In non-3D payments, there is no OTP (one-time password) step.

If bank authorization is successful, the transaction is completed directly and returned with transactionStatusId = 1 (successful).

Question: I get an error when trying consecutive payments with the same card. Why?

Answer

Some banks apply time limits between 3D authentication attempts (e.g. 60 seconds). Frequent payment attempts with the same card may temporarily result in a “Too Many Requests (429)” error.

Question: Why does “autocommit” fail after 3D authentication?

Answer

• The user did not complete the OTP step or the browser redirection was interrupted.

• The bank rejected the authorization (e.g. insufficient balance, limit exceeded).

• The returnUrl is invalid or the system could not detect payment completion after redirection.

Payment Details

Question: Why does the /pws/payment/transaction service return null or empty?

Answer

• The provided transactionId or referenceNumber does not exist in the system.

• The transaction is still in the authorization phase and has not yet been reflected in ERP.

• The relevant AccessToken may belong to a different tenant.

Question: What does transactionStatusId in the response indicate?

Answer

ID	Description
1	Successful
2	Failed
3	Pending
4	OTP Pending (3D Step)

Question: Why does lastAmount return as zero?

Answer

This indicates that the transaction has been canceled or fully refunded. If a partial refund was made, lastAmount represents the remaining balance.

Payment Cancellation

Question: Why can’t I cancel a transaction?

Answer

• The transaction may already have been canceled.

• Transactions that are not approved by the bank (no authorization received) cannot be canceled.

• If the relevant bank service is not responding at that moment, a “503 Service Unavailable” may be returned.

Question: Can the reference code be reused after a cancellation?

Answer

No. Each payment transaction is identified by a unique referenceCode, and canceled references cannot be reused.

Payment Refund

Question: What is the difference between a full refund and a partial refund?

Answer

• Full refund: The entire transaction amount is refunded (refundAmount is not sent).

• Partial refund: Only a portion of the transaction amount is refunded (refundAmount is specified).

Question: Can I refund the same transaction multiple times?

Answer

Yes, multiple partial refunds can be made. However, the total refunded amount cannot exceed the original transaction amount.

If it does, the system returns the “P015 – Partial refund limit exceeded” error.

Question: Why might a refund fail?

Answer

• The bank system may be temporarily unavailable (timeout or maintenance).

• The refund amount exceeds the allowed refund limit.

• The transaction date may have exceeded the bank’s refund period (e.g. 30 days).

• The AccessToken does not have permission for the transaction.

Security & Token Management

Question: How long is the AccessToken valid?

Answer

Token durations depend on system configuration and are typically valid for 60 minutes. Requests made with an expired token return 401 Unauthorized.

Question: In which cases do I get “403 Forbidden”?

Answer

Even if the token is valid, if the user role does not have permission to access the relevant service.

For example, when attempting to access a dealer-only service with a customer token.

Performance & Limits

Question: Why is pagination (page, pageSize) important?

Answer

Especially in listing services such as /pws/paymentSet or /vendor/creditcards, large data sets are returned. Pagination parameters should be used for performance.

Question: Is there a rate limit in the system?

Answer

Yes. If too many requests are made per second from the same IP or with the same AccessToken, a 429 Too Many Requests error is returned. In this case, wait a few seconds and try again.

Other Common Scenarios

Question: Why are card details returned as masked?

Answer

Due to KVKK and PCI-DSS standards, card numbers are displayed only with the first 6 and last 4 digits visible.

Question: Why is returnUrl important?

Answer

In the 3D Secure flow, it is the address to which the system redirects after user authentication. If a valid URL is not provided, the payment may not complete or may return an error.

Question: What is the difference between the sandbox (test) environment and the production environment?

Answer

In the sandbox environment, transactions are performed in test mode; no real authorization is sent to the bank. Real cards are not used, and results are returned as simulations.

In the production environment, all transactions are carried out through real banking infrastructure.

Question: Which fields are masked under KVKK?

Answer

• Card number → masked in ****** format, with the first 6 and last 4 digits visible
• Cardholder name → fake names such as “Test User”, “Demo Customer”
• Email → sample addresses such as [email protected] or [email protected] This ensures that personal data is anonymized in logs and test records.