--- title: "연동 테스트" description: "결제를 시뮬레이션하여 연동을 테스트하세요." source: "https://docs.tokenz.one/ko-KR/v1/checkout/testing" api_version: "v1" locale: "ko-KR" version_status: "legacy" docs_stage: "prod" --- # 연동 테스트 결제를 시뮬레이션하여 연동을 테스트하세요. ## 소개 실제 결제 없이 거래를 시뮬레이션하여 연동이 올바르게 동작하는지 확인할 수 있습니다. 모든 API 호출에 테스트 API 키를 사용하여 테스트 모드에서 리소스를 생성하고 조작하세요. 전용 테스트 결제 수단으로 테스트 Checkout Session을 완료할 수 있습니다. 모든 테스트 결제 화면 상단에는 테스트 배너가 표시되어 쉽게 구분할 수 있습니다. 테스트 결제 수단으로 다음 시나리오를 시뮬레이션할 수 있습니다. - 결제 성공 - 결제 거절 또는 잘못된 데이터로 인한 결제 오류 - 계좌이체나 편의점 결제 등 비동기 결제 수단으로 인한 결제 지연 테스트 전용 **테스트 승인 결과**(Test Authorization Result) 스위치로 결제 결과를 지정할 수 있습니다. 아래 스크린샷은 영어 화면입니다. - **성공**(Success)을 선택하면 항상 결제에 성공합니다. - **동기 결제 수단**(카드, PayPay 등): 성공 응답을 즉시 받습니다. - **비동기 결제 수단**(편의점 결제, Pay-easy): 10초 후 성공 응답을 받습니다. - **거절**(Decline)을 선택하면 결제가 거절됩니다. - **동기 결제 수단**(카드, PayPay 등): 결제가 거절되고 결제 정보 입력 화면이 표시되어 다른 카드 등으로 다시 시도할 수 있습니다. - **비동기 결제 수단**(편의점 결제, Pay-easy): 결제가 완료되지 않고 주문이 처리 중 상태로 유지됩니다. ![](https://docs.tokenz.one/docs/card_filled_success.png) > 실제 결제를 받을 준비가 되면 테스트 API 키를 라이브 키로 교체하세요. 테스트 API 키로는 실제 결제를 처리할 수 없습니다. ## 테스트 결제 성공시키기 1. Checkout Session 생성 [API](https://docs.tokenz.one/ko-KR/v1/api/main)로 Checkout Session을 생성하세요. - 테스트 API 키를 사용하여 테스트 모드로 생성하세요. ```bash curl --location 'https://api.tokenz.one/v1/checkoutsession' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --data '{ "amount": { "currency": "JPY", "amount": 5200 }, "itemDetails": [ { "product": { "label": "ひとにぎりのエメラルド", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ], "quantity": 3, "price": { "currency": "JPY", "amount": 1200 } } }, { "product": { "label": "エメラルドの荷車", "images": [], "quantity": 1, "price": { "currency": "JPY", "amount": 1600 } } } ], "successUrl": "http://localhost:9000/success", "pendingUrl": "http://localhost:9000/pending", "cancelUrl": "http://localhost:9000/cancel", "customerInfo": { "emailAddress": "user@email.com" }, "description": "description", "reference": "reference", "theme": "LIGHT" }' ``` 1. Checkout 완료 Checkout Session 생성 API가 반환한 `url`을 여세요. - `Card`를 선택하세요. - 이메일 주소와 아래 테스트 카드 중 하나의 정보를 입력하세요. - **테스트 승인 결과** 스위치를 **성공**으로 유지하세요. 주문이 성공적으로 결제됩니다. - `Pay`를 클릭하세요. 결제가 성공적으로 처리되고 성공 페이지가 표시됩니다. 웹훅을 설정했다면 `order.succeeded` 웹훅도 수신합니다. - `ok`를 클릭하면 Checkout Session 생성 시 지정한 `successUrl`로 이동합니다. > 테스트 모드에서 실제 카드 정보를 사용하지 마세요. 아래 테스트 카드를 사용하세요. ### 테스트 카드 번호 | 브랜드 | 번호 | CVC | 유효기간 | | --- | --- | --- | --- | | ![](https://docs.tokenz.one/docs/payment-methods/cc-visa.svg) | `4242 4242 4242 4242` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-visa.svg) | `4111 1111 1111 1111` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-mastercard.svg) | `5555 5555 5555 4444` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-mastercard.svg) | `2222 2222 2222 2224` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-jcb.svg) | `3530 1113 3330 0000` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-jcb.svg) | `3528 0000 0000 0023` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-amex.svg) | `3714 4963 539 8431` | 임의의 숫자 4자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-amex.svg) | `3411 1111 111 1111` | 임의의 숫자 4자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-diners.svg) | `3611 111111 1111` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | ![](https://docs.tokenz.one/docs/payment-methods/cc-diners.svg) | `3636 363636 3632` | 임의의 숫자 3자리 | 미래의 임의 날짜 | | | | | | --- | --- | --- | | ![](https://docs.tokenz.one/docs/payment_method_selection.png) | ![](https://docs.tokenz.one/docs/card_filled_success.png) | ![](https://docs.tokenz.one/docs/card_payment_success.png) | ## 결제 거절 테스트 결제가 거절되면(예: 카드 승인 거절) 고객은 다른 카드 등으로 다시 시도할 수 있습니다. 결제 거절에 대해 판매자가 별도로 처리할 작업은 없습니다. > 결제 성공을 확인한 경우에만 주문을 이행하세요. 1. Checkout Session 생성 [API](https://docs.tokenz.one/ko-KR/v1/api/main)로 Checkout Session을 생성하세요. - 테스트 API 키를 사용하여 테스트 모드로 생성하세요. ```bash curl --location 'https://api.tokenz.one/v1/checkoutsession' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --data '{ "amount": { "currency": "JPY", "amount": 5200 }, "itemDetails": [ { "product": { "label": "ひとにぎりのエメラルド", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ], "quantity": 3, "price": { "currency": "JPY", "amount": 1200 } } }, { "product": { "label": "エメラルドの荷車", "images": [], "quantity": 1, "price": { "currency": "JPY", "amount": 1600 } } } ], "successUrl": "http://localhost:9000/success", "pendingUrl": "http://localhost:9000/pending", "cancelUrl": "http://localhost:9000/cancel", "customerInfo": { "emailAddress": "user@email.com" }, "description": "description", "reference": "reference" }' ``` 1. Tokenz Checkout 완료 Checkout Session 생성 API가 반환한 `url`을 여세요. - `Card`를 선택하세요. - 이메일 주소와 [테스트 카드](https://docs.tokenz.one/ko-KR/v1/checkout/testing#test-card-numbers) 중 하나의 정보를 입력하세요. - **테스트 승인 결과** 스위치를 **거절**로 변경하세요. 결제가 거절됩니다. - `Pay`를 클릭하세요. 결제가 거절되고 카드 입력 페이지로 돌아가 다시 결제할 수 있습니다. | | | | --- | --- | | ![](https://docs.tokenz.one/docs/card_filled_decline.png) | ![](https://docs.tokenz.one/docs/card_payment_decline.png) | ## 비동기 테스트 결제 완료 편의점 결제로 비동기 결제 흐름을 테스트할 수 있습니다. 이를 통해 지연된 결제 성공 알림을 처리하는 방법을 테스트할 수 있습니다. 1. Checkout Session 생성 [API](https://docs.tokenz.one/ko-KR/v1/api/main)로 Checkout Session을 생성하세요. - 테스트 API 키를 사용하여 테스트 모드로 생성하세요. ```bash curl --location 'https://api.tokenz.one/v1/checkoutsession' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --data '{ "amount": { "currency": "JPY", "amount": 5200 }, "itemDetails": [ { "product": { "label": "ひとにぎりのエメラルド", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ], "quantity": 3, "price": { "currency": "JPY", "amount": 1200 } } }, { "product": { "label": "エメラルドの荷車", "images": [], "quantity": 1, "price": { "currency": "JPY", "amount": 1600 } } } ], "successUrl": "http://localhost:9000/success", "pendingUrl": "http://localhost:9000/pending", "cancelUrl": "http://localhost:9000/cancel", "customerInfo": { "emailAddress": "user@email.com" }, "description": "description", "reference": "reference", "theme": "LIGHT" }' ``` 1. Tokenz Checkout 완료 Checkout Session 생성 API가 반환한 `url`을 여세요. - 오른쪽 상단 국가/지역에서 `Japan`을 선택하세요. - 결제 수단으로 `Konbini`를 선택하세요. - 임의의 이름, 이메일 주소, 전화번호를 입력하고 편의점을 선택하세요. - **테스트 승인 결과** 스위치를 **성공**으로 유지하세요. 주문이 성공적으로 결제됩니다. `Pay`를 클릭하여 결제를 시작하세요. - 결제 화면에 편의점 납부 안내가 표시됩니다. - 결제가 완료되면(테스트 결제에서는 10초 후) 성공 화면이 표시됩니다. 웹훅을 설정했다면 `order.succeeded` 웹훅도 수신합니다. - `ok`를 클릭하면 Checkout Session 생성 시 지정한 `successUrl`로 이동합니다. | | | | --- | --- | | ![](https://docs.tokenz.one/docs/payment_method_selection.png) | ![](https://docs.tokenz.one/docs/konbini_filled.png) | > 테스트 결제 대금을 편의점에서 실제로 납부하지 마세요. 테스트 Checkout은 테스트 전용이며 실제 결제가 처리되지 않으므로 대금을 납부할 필요도 없습니다. ## PayPay, Alipay 등 간편결제 테스트 실제 결제 시 고객은 해당 서비스에 로그인하고 결제를 승인해야 합니다. 계정 없이도 간편결제를 테스트할 수 있도록 테스트 Checkout에서는 해당 서비스의 결제 화면으로 이동하는 과정만 시뮬레이션합니다. 1. PayPay 결제용 Checkout Session 생성 [API](https://docs.tokenz.one/ko-KR/v1/api/main)로 Checkout Session을 생성하세요. - 테스트 API 키를 사용하여 테스트 모드로 생성하세요. - 허용 결제 수단으로 `PAYPAY`를 지정하세요. ```bash curl --location 'https://api.tokenz.one/v1/checkoutsession' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \ --data '{ "amount": { "currency": "JPY", "amount": 5200 }, "itemDetails": [ { "product": { "label": "ひとにぎりのエメラルド", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ], "quantity": 3, "price": { "currency": "JPY", "amount": 1200 } } }, { "product": { "label": "エメラルドの荷車", "images": [], "quantity": 1, "price": { "currency": "JPY", "amount": 1600 } } } ], "successUrl": "http://localhost:9000/success", "pendingUrl": "http://localhost:9000/pending", "cancelUrl": "http://localhost:9000/cancel", "customerInfo": { "emailAddress": "user@email.com" }, "description": "description", "reference": "reference", "paymentMethodKinds": [ "PAYPAY" ], "theme": "LIGHT" }' ``` 1. Checkout 완료 Checkout Session 생성 API가 반환한 `url`을 여세요. - 이메일 주소를 입력하세요. - 원하는 결과에 따라 **테스트 승인 결과** 스위치를 **성공** 또는 **거절**로 설정하세요. - `Continue with PayPay`를 클릭하세요. 실제 결제에서는 PayPay로 이동하여 구매를 완료합니다. 테스트 결제에서는 안내 화면만 표시하므로 PayPay 계정이 필요하지 않습니다. - `Pay`를 클릭하세요. 테스트 결과 스위치 설정에 따라 결제가 성공하거나 거절됩니다. | | | | | --- | --- | --- | | ![](https://docs.tokenz.one/docs/paypay_filled_success.png) | ![](https://docs.tokenz.one/docs/paypay_redirect.png) | ![](https://docs.tokenz.one/docs/paypay_payment_success.png) |