FAQ

FAQ

Now, let’s learn more about Tosspay service.
This part will continue to be updated, and please contact the Tosspay team (support-pay@toss.im) if you have any questions.

Firewall Set-up for Toss Integration

If the payment result doesn’t come through the merchant retUrl even if the purchaser completed authentication, or if a resultCallback result from the Toss server was not received, the firewall settings should be checked first.

1. When the merchant accesses the Toss server (payment creation, payment authorization, etc. API)
   Merchant --> Merchant firewall --> Tosspay

In such cases, please add the following Toss IP in the outbound policy of the merchant firewall.
domain : pay.toss.im (port : 443)
• 117.52.3.202
• 117.52.3.210
• 211.115.96.202
• 211.115.96.210


2. When the Toss server accesses the merchant (used only when including resultCallback)
   Tosspay --> Merchant firewall --> Merchant

In such cases, please add the following Toss IP in the inbound policy of the merchant firewall.
domain : pay.toss.im (port : 443)
• 117.52.3.4
• 117.52.3.11
• 117.52.3.80~87
• 211.115.96.4
• 211.115.96.11
• 211.115.96.80~87

✓ The Tosspay firewall is open without restrictions.

✓ If it is difficult to distinguish each case, the Toss IPs can all be added, according to the outbound and inbound policies.

✓ Please be aware that accessing may not be possible if there are other ports other than 443 in the resutCallback URL set by the merchant.

✓ A notification email will be sent out when a Toss server IP is added.

Toss Encoding Method

The Toss encoding method uses the UTF-8 format.
To get a valid response value, values (order number, product name, etc.) sent from the merchant to the Toss server that includes Korean should be sent in UTF-8 form.
Please note that if the Toss server receives distorted Korean text, the Toss server will be unable to check the mandatory values and result in errors such as 500 error.

What is the Time Out processing time recommended by Toss?

When Toss Money is charged through a normal bank account, Toss sets the Time Out time at a maximum of 10 seconds.
Therefore, if the merchant sets a waiting time of 10 + 3~5 seconds reconciliation mismatch cases will not occur. (This is to avoid cases in which a payment is authorized by Toss due to a delay in processing, despite the merchant canceling the payment.)
Excluding bank network-related issues that do not originate from Toss, transaction delays will not occur due to time out.

✓ The time can be set the same for all payment methods.
✓ We recommend integrating the settlement reconciliation as well to check transactions between both companies.
This is provided upon request of the merchant. Please apply through support-pay@toss.im.

Can retUrl redirection fail?

retUrl Redirection is a logic processed in the Toss webpage. Generally, the processing is guaranteed, but it may fail in special cases.
Special cases refer to churn cases in which JavaScript logic cannot be processed due to the purchaser closing the app during a payment or background processing.
In such cases, if the purchaser returns to the payment screen and clicks on the ‘Complete payment’ button, redirection to retUrl is attempted again.
However, if the purchaser doesn’t try again, redirection to retUrl may not be possible.

Do I have to use resultCallback?

Once payment processing is completed in the Toss server, the payment status is changed to PAY_COMPLETE, redirecting the purchaser to retUrl.
Simultaneously, the Toss server requests callback to the merchant server’s result Callback URL.
retUrl is simply a redirection of a web page, meaning that Toss cannot confirm the success or failure of payments, and cannot guarantee the execution of payments depending on the purchaser’s situation. Therefore, we recommend using resultCallback.
Also, resultCallback is the communication between the Toss server and merchant server, which is safe and prevents data loss.

• This is a mandatory value for merchants that set the automatic authorization setting (autoExecute) at true.

Why does resultCallback fail?

Unless it is a failure case, Toss guarantees a resultCallback request.
However, except for the payment firewall issue, processing a callback request may fail due to special reasons,
such as excessive traffic to the merchant server, or bugs during development.
But don’t worry, because when callback fails, Toss requests 4 more tries within 10 minutes to the merchant server.

✓ The callback resending feature can also be found on the Toss merchant manager page.

Payment Error Response Code

✓ Tosspay error codes may be updated without prior notice. Even if updated, please proceed with integration so that errors do not occur.

✓ Toss delivers different error messages for one error code depending on the situation.
Since a variety of situations may occur, please process the error message delivered as is.

Response code (errorCode)	Reason (msg)
Common
COMMON_SYSTEM_ERROR	Unstable communication due to system error. If the issue continues, please contact the Toss customer center. (1599-4905)
COMMON_INVALID_PARAMETER	Invalid parameter
COMMON_PAY_ERROR	An error has occurred
COMMON_NOT_ENOUGH_CASH	Insufficient balance
COMMON_EXCEED_LIMIT	Exceeded limit
COMMON_ASSET_GET_ACCOUNT_ERROR	Failed to find account information
COMMON_REFUND_ERROR	Refund not possible
REFUND_REFUND_NO_DUPLICATE	The refundNo already exists. Please request with a non-duplicate refundNo.
PAYMENT_DUPLICATION_ORDER_NO	Duplicate order number
PAYMENT_EXISTING_PAYMENT	The payment already exists.
TRANSACTION_PENDING_ERROR	The payment you applied for a while ago is still in progress. Please try again in a few minutes. If this condition persists for more than 10 minutes, please contact the Toss team.(1599-4905)
INVALID_ACCOUNT_STATUS	Please check account status.
FRAUD_DETECTION_SYSTEM_ERROR	Financial transactions are blocked by FDS.
USER_STATUS_ERROR	This user is unable to proceed with payment.
REFUND_ALREADY_REFUNDED	The refund has already been completed.
TRANSACTION_NOT_COMPLETE	The transaction is not complete.
TRANSACTION_NOT_FOUND	This transaction does not exist.
INACTIVE_USER	Refund not possible: inactive user
AUTO_CHARGE_NOT_YET_REGISTER_ACCOUNT	The charge account has not been registered.
User
PAY_UNAUTHORIZED	Payment is only possible if the payment requester and Toss account match. Please check and try again.
TOSS_APP_UPDATE_IS_REQUIRED	To make payment, use the latest version of the Toss app.
PAY_CANCEL_ITS_NOT_CANCELABLE_STATUS	Payment cannot be canceled. Please try again in a few minutes. If the problem persists, please contact Toss Customer Center.(1599-4905)
COUPON_ASSIGN_FAIL	Coupon issuance failed.
DISCOUNT_CLOSED	Discount offer has ended.
USER_DISCOUNT_CLOSED	The number of discounts per person has been exceeded.
DISCOUNT_NEED_ISSUE	Please receive a coupon.
DISCOUNT_ALREADY_ISSUED	The coupon has already been issued.
AVAILABLE_ONLY_TOSS_MONEY_UNDER_MIN_AMT	Amounts less than %s won cannot be paid with the %s card.
AUTO_PAY_TERM_INACTIVE_FAIL	You failed to withdraw the terms and conditions.
AGE_POLICY_ERROR	If you are under the age of %d, you cannot use the Toss %s service.
PAY_FRAUD_DETECTED	Toss service is temporarily unavailable. If the problem persists, please contact Toss Customer Center.(1599-4905)
BLOCKED_THE_USE_OF_POINT	Due to a court seizure decision,Toss Points can not be used. If you have any questions, please contact Toss Customer Center (1599-4905)
Card
CARD_SYSTEM_ERROR	Card company system maintenance hours: Please try again later.
CARD_BANK_SYSTEM_ERROR	Card company’s partnering bank system maintenance hours: Please try again later.
CARD_NOT_AVAILABLE_SHOP	This card cannot be used for this merchant. (Please use another card.)
CARD_NOT_AVAILABLE	Authorization declined: stolen/lost/suspended card
CARD_EXCEED_LIMIT	Authorization declined: exceeded limit
CARD_NOT_ENOUGH_BALANCE	Authorization declined: insufficient funds
CARD_SPREADOUT_ERROR	Authorization declined: Card does not support installment payment
CARD_MIN_AMOUNT_ERROR	Payment amount error (card authorization not possible for less than 100 KRW or $1)
CARD_MIN_AMOUNT_FOR_SPREADOUT_ERROR	Installment payment is only possible if the payment amount is 50,000 won or more. Please pay in one lump sum.
BNPL
BNPL_INVALID_REQUEST	Invalid request
BNPL_NOT_EXIST_USER	This is a BNPL user that does not exist.
BNPL_EXCEED_PAYABLE_AMOUNT	BNPL limit has been exceeded.
BNPL_ALREADY_COMPLETED_REQUEST	This request has already been processed.
BNPL_IN_PROGRESS_REQUEST	This request is already being processed.
BNPL_NOT_FOUND_PAYMENT	This is a payment that does not exist.
BNPL_ALREADY_COMPLETED_REFUND	This is a non-refundable payment.
NOT_SET_BNPL_PAYMENT_ACCOUNT	To process deferred payment, User needs to set up a payment account.
Sales Slips
SALES_CHECK_NOT_FOUND_USER	User information does not exist for viewing sales slips.
SALES_CHECK_USER_AUTH_FAIL	Failed to authenticate user information for viewing sales slips
SALES_CHECK_USER_AUTH_DECRYPT_FAIL	Decryption of user information to view sales slip failed.
SALES_CHECK_CARD_ONLY	Sales slips viewing available for card payments only
Reseller
COMMON_PAY_RESELLER_ERROR	An error occurred while processing the reseller payment.
RESELLER_ONLY_CARD_PAYMENT	Not a card payment.
RESELLER_CALLBACK_PROCESS_ERROR	An error occurred while processing the reseller callback.
NOT_APPROVED_CARD_PAYMENT	Payment via card not authorized by user
PAY_CARD_AUTH_REQUEST_ERROR	Failed to request card authorization
NOT_SUPPORTED_RESELLER_SHOP	Not an affiliated store designated as a reseller.
Others
PAYMENT_SHOP_STATE_NOT_NORMAL	This is an affiliated store that does not allow payment. Please contact the affiliated store customer service center.
PAYMENT_SHOP_STATE_CANNOT_REFUND	This is an affiliated store that does not allow payment. Please contact the affiliated store customer service center. (Accident report)
COMMON_INVALID_API_KEY	Invalid API key
NOT_INTERNAL_SHOP	Not an internal Merchant.
COMMON_BREAK_TIME_OF_BANK	Bank system maintenance hours: Please try again later.
COMMON_UNAUTHORIZED	Unauthorized Access
REFUND_EXCEED_DAILY	The refund amount may not exceed the merchant’s daily refund limit.
EXECUTE_PAY_NOT_APPROVED	The purchaser has not yet authorized the payment.
PAUSE_USER	Paused user
COMMON_TIMEOUT	A delay has occurred during processing. Please try again.
COMMON_THROTTLED	There are many payment requests, making service use difficult. Please try again later.
COMMON_ITS_NOT_ABLE_TO_CHANGE_STATUS	The status is not available for request.
ESCROW_IMPOSSIBLE_STATUS	Escrow status cannot be changed.