Toss Payments Test Guide(EN)

1. Overview

This document is a guide provided for overseas developers to reference when testing the integration of various domestic payment methods, including domestic cards and local simple payment methods (Toss Pay, Naver Pay, Kakao Pay), after integration.

All instructions provided here are only available when using the test key of the MID (Merchant ID) with a completed contract. They will not work with a live key. You may not be able to test properly with the MID of a development integration test store.

To perform tests in the live environment, you must have the actual payment method available. For integration documentation, please refer to docs.tosspayments.com.

If you cannot find the relevant page, please proceed with the contract for the payment method and request the documentation by sending your contracted MID information to techsupport@tosspayments.com.

2. Guide by Payment Module

The currently supported method can be used for all development means, but the response is fixed to card payment. Please use it for the purpose of integrating the authentication and approval process. For actual response accuracy, please use the real payment method in the live environment.

2-1. Payment Window, SDK V1, requestPayments() method

If you add the following to the JSON parameter when calling requestPayments:

“_skipAuth” : “FORCE_SUCCESS”

The payment window UI will be skipped, and authentication will be processed as successful, operating as follows:

•

Promise method: Returns RequestPaymentResult

•

Redirect method: Redirects to successURL

“_skipAuth” : “FORCE_FAIL” 

The payment window UI will be skipped, and authentication will be processed as failed, returning the following error:

•

Promise method: Returns {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"}

•

Redirect method: Redirects to failURL with code=REJECT_CARD_COMPANY&message=카드사 거절

Afterward, when you call the confirm API, the response will always indicate a card payment method, regardless of the requested payment method. The card information will be fixed as dummy values, as shown below:

"issuerCode":"61","acquirerCode":"61","number":"94313300***123*","installmentPlanMonths":0,"isInterestFree":false,"interestPayer":null,"approveNo":"00000000","useCardPoint":false,"cardType":"신용","ownerType":"개인"

2-2. Payment Widget, SDK V1, requestPayments() method

requestPayments 를 호출하는 JSON 파라미터에

If you add the following to the JSON parameter when calling requestPayments:

“_skipAuth” : “FORCE_SUCCESS”

The payment window UI will be skipped, and authentication will be processed as successful, operating as follows:

•

Promise method: Returns RequestPaymentResult

•

Redirect method: Redirects to successURL

“_skipAuth” : “FORCE_FAIL” 

The payment window UI will be skipped, and authentication will be processed as failed, returning the following error:

•

Promise method: Returns {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"}

•

Redirect method: Redirects to failURL with code=REJECT_CARD_COMPANY&message=카드사 거절

2-3. Payment Window, SDK V2, requestPayments() method

If you add the following to the JSON parameter when calling requestPayments:

sandbox: {paymentResult: 'SUCCESS'}

The payment window UI will be skipped, and authentication will be processed as successful, operating as follows:

•

Promise method: Returns RequestPaymentResult

•

Redirect method: Redirects to successURL

sandbox: {paymentResult: 'FAIL'}

The payment window UI will be skipped, and authentication will be processed as failed, returning the following error:

•

Promise method: Returns {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"}

•

Redirect method: Redirects to failURL with code=REJECT_CARD_COMPANY&message=카드사 거절

2-4. Payment Widget, SDK V2, requestPayments() method

If you add the following to the JSON parameter when calling requestPayments:

sandbox: {paymentResult: 'SUCCESS'}

The payment window UI will be skipped, and authentication will be processed as successful, operating as follows:

•

Promise method: Returns RequestPaymentResult

•

Redirect method: Redirects to successURL

sandbox: {paymentResult: 'FAIL'}

The payment window UI will be skipped, and authentication will be processed as failed, returning the following error:

•

Promise method: Returns {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"}

•

Redirect method: Redirects to failURL with code=REJECT_CARD_COMPANY&message=카드사 거절

2-5. Billing, SDK V1, requestPayments() method

This section explains the process of issuing a billing key for testing through the Toss Payments billing payment window. Enter the following information in the payment window:

•

Select ”personal card”

•

For the card number, as long as it is a valid BIN number issued in Korea, the rest of the numbers can be random.

•

For the expiration date, enter a future month/year.

•

The name can be any value.

•

For the resident registration number, enter 000101-1.

•

For the mobile carrier, select any carrier and enter 01000001234 as the phone number.

•

For the authentication number, enter 000000.

2-6. Billing, SDK V2, requestPayments() method

This section explains the process of issuing a billing key for testing through the Toss Payments billing payment window. Enter the following information in the payment window:

•

Select ”personal card”

•

For the card number, as long as it is a valid BIN number issued in Korea, the rest of the numbers can be random.

•

For the expiration date, enter a future month/year.

•

The name can be any value.

•

For the resident registration number, enter 000101-1.

•

For the mobile carrier, select any carrier and enter 01000001234 as the phone number.

•

For the authentication number, enter 000000.

3. Guide by Payment API

3-1. Key-in API

This section explains how to perform tests when integrating card payments using the Key-in API.

For domestic (Korean) cards:

•

For the card number, as long as it is a valid BIN number issued in Korea, the remaining digits can be entered arbitrarily.

•

For the expiration date, enter a future month/year.

•

For the date of birth, enter 000101.

Proceed with the payment using these values.

If you send an invalid BIN, you will receive an error response as shown below.

If the request is processed successfully, you will receive a successful payment response based on the card number you provided.

3-2. Billing API

This section explains how to perform tests when issuing a billing key using the Billing API.

The Billing API requires the same information as the billing payment window. However, identity verification is not performed.

•

For the card number, as long as it is a valid BIN number issued in Korea, the remaining digits can be entered arbitrarily.

•

For the expiration date, enter a future month/year.

•

For the date of birth, enter 000101.

Proceed with the billing key request using these values.

If you send an invalid BIN, you will receive an error response as shown below.

If the request is processed successfully, you will receive a successful billing key issuance response based on the card number you provided. You can then use this billing key to request payments through the automatic payment API.