1. 토스 API 결제: 일단 실행하기!

0. 시작하기 전에

AI를 활용한 온라인 배달 플랫폼 개인 프로젝트를 진행하던 중, 서비스의 완성도를 높이고 실무에 가까운 경험을 쌓기 위해 결제 서비스 기능을 추가 구현하게 되었습니다.

사실, 결제 API를 직접 구현해보는 것은 이번이 처음이었고, 결제 도메인에 대한 지식도 거의 없는 상태에서 도전을 시작했습니다. 그렇기에 시행착오도 많았고, 이해해야 할 개념도 많았지만 그 과정을 통해 많은 것을 배우고 정리할 수 있었습니다.

이 글은 결제 API 구현에 처음 도전하는 분들을 위한 실질적인 가이드를 담고 있습니다. 저처럼 처음 시작하는 입장에서 마주칠 수 있는 고민과 흐름, 그리고 실제 적용 사례를 기반으로 구성했기 때문에, 처음 결제 기능을 구현하려는 분들에게 분명 큰 도움이 될 것이라 확신합니다.

1. 먼저! 코드 샘플 다운로드

샘플 코드 다운로드하기

토스페이먼츠 개발자센터 홈페이지로 이동합니다.

• https://docs.tosspayments.com/guides/v2/payment-widget/integration?frontend=javascript&backend=java

결제위젯으로 결제수단을 선택할 수 있지만 모든 결제수단을 볼 수 있도록 전부 체크합니다. 그리고 샌드박스로 시작하기와 코드 샘플로 다운로드하기 두 개의 버튼이 있습니다. 개인 프로젝트에 결제 API를 구현하는 것이 목적이므로 Client는 JavaScript로 Server는 Java로 선택하고 코드 샘플 다운로드하기를 클릭합니다.

2. 샘플 코드 실행하기

다운로드 받은 샘플코드를 열고, DemoApplication 혹은 Shift + F10으로 스프링 부트 프로젝트를 실행합니다.
제가 샘플코드를 2025-06-16에 다운로드 받을 당시에는 다음과 같은 환경이라는 점을 참고해주세요.

• port: 4242
• java: 17
• spring boot: 3.2.0
• Maven
• dependencies: tyhmeleaf, spring web, devtools, lombok, json-slmple 1.1.1

스프링 부트 애플리케이션이 4242 포트로 정상적으로 실행된 것을 콘솔에서 확인했습니다.
이제 웹 브라우저를 통해 localhost:4242으로 이동합니다.

결제수단 선택 페이지가 성공적으로 보이는 것을 확인할 수 있습니다! 그리고 테스트 환경 - 실제로 결제되지 않습니다. 문구처럼 어떠한 결제를 진행하더라도, 실제로 결제되지 않기 때문에 걱정하지 않아도 됩니다. 필자는 카카오페이로 결제를 진행했습니다.

결제를 성공하면 다음과 같은 결제 완료 화면으로 이동합니다. 해당 화면에서 알 수 있는 정보들은 다음과 같습니다.

3. 응답 확인하기

URL

http://localhost:4242/success?paymentType=NORMAL&orderId=MC45NjI0ODU0ODYwMjMy&paymentKey=tgen_20250616191900K4LO0&amount=50000

Response Data

{
    "country": "KR",
    "metadata": null,
    "orderId": "MC45NjI0ODU0ODYwMjMy",
    "cashReceipts": null,
    "isPartialCancelable": true,
    "lastTransactionKey": "txrd_a01jxw40c17900wyq648wmv4f34",
    "discount": null,
    "taxExemptionAmount": 0,
    "suppliedAmount": 45455,
    "secret": "ps_QbgMGZzorzKK1OpM1BPN8l5E1em4",
    "type": "NORMAL",
    "cultureExpense": false,
    "taxFreeAmount": 0,
    "requestedAt": "2025-06-16T19:19:00+09:00",
    "currency": "KRW",
    "paymentKey": "tgen_20250616191900K4LO0",
    "virtualAccount": null,
    "checkout": {
        "url": "https://api.tosspayments.com/v1/payments/tgen_20250616191900K4LO0/checkout"
    },
    "orderName": "토스 티셔츠 외 2건",
    "method": "간편결제",
    "useEscrow": false,
    "vat": 4545,
    "mId": "tgen_docs",
    "approvedAt": "2025-06-16T19:19:21+09:00",
    "balanceAmount": 50000,
    "version": "2022-11-16",
    "easyPay": {
        "amount": 50000,
        "provider": "카카오페이",
        "discountAmount": 0
    },
    "totalAmount": 50000,
    "cancels": null,
    "transfer": null,
    "mobilePhone": null,
    "failure": null,
    "receipt": {
        "url": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tgen_20250616191900K4LO0&ref=PX"
    },
    "giftCertificate": null,
    "cashReceipt": null,
    "card": null,
    "status": "DONE"
}

토스페이먼츠에서 제공한 샘플 코드를 실행해 결제 수단을 선택하고, 정상적으로 결제가 처리되는지 직접 확인해보았습니다. 현재 결제 도메인에 대한 이해는 부족한 상태지만, 실습을 통해 토스페이먼츠의 결제 API가 어떻게 동작하는지 경험해볼 수 있었습니다.

이제 다음 단계로, 공식 문서를 참고하여 결제 흐름과 개념을 정리하고, 샘플 코드를 분석하며 학습한 내용을 체계적으로 정리하겠습니다.