토스페이먼츠 결제 내역 API 사용 방법 완벽 가이드

작성자:

토스페이먼츠를 서비스에 연동한 개발자라면 결제 내역을 자동으로 조회해야 하는 상황이 생겨요. 대시보드에서 수동으로 조회하는 것도 방법이지만, 자체 시스템과 연동해 자동으로 결제 정보를 가져오려면 API를 활용해야 해요.

이 글에서는 토스페이먼츠 결제 내역 API의 주요 엔드포인트, 인증 방법, 요청 파라미터, 응답 데이터 구조까지 실무에서 바로 활용할 수 있게 안내해 드릴게요. 토스페이먼츠 API를 처음 다루는 분들도 이 글을 참고하면 빠르게 시작할 수 있을 거예요.

토스페이먼츠 API 기본 구조와 인증

토스페이먼츠 API를 사용하기 전에 인증 방식과 기본 구조를 이해해야 해요.

API 키 발급 및 종류

토스페이먼츠 API를 사용하려면 파트너센터에서 API 키를 발급받아야 해요. 키는 두 종류예요.

  • 클라이언트 키: 프론트엔드(브라우저, 앱)에서 결제 UI를 초기화할 때 사용해요. 공개 키이므로 외부 노출이 상대적으로 허용돼요.
  • 시크릿 키: 서버 사이드에서만 사용해야 하는 비공개 키예요. 결제 내역 조회, 결제 승인, 환불 API 등 중요한 작업에 사용해요. 절대 클라이언트에 노출하면 안 돼요.

파트너센터 → API 키 메뉴에서 테스트용 키와 운영용 키를 각각 확인할 수 있어요. 개발 중에는 반드시 테스트 키를 사용하고, 실제 서비스 배포 시에만 운영 키로 전환해요.

HTTP Basic Auth 인증 방식

토스페이먼츠 API는 HTTP Basic Auth 방식으로 인증해요. 시크릿 키 뒤에 콜론(:)을 붙이고 Base64로 인코딩한 값을 Authorization 헤더에 포함시켜요.

  • 시크릿 키 예시: test_sk_xxxxxxxxxxxx
  • 콜론 추가: test_sk_xxxxxxxxxxxx:
  • Base64 인코딩 후 헤더에 포함: Authorization: Basic dGVzdF9za194eHh4eHh4eHh4eHg6

대부분의 HTTP 라이브러리는 Basic Auth를 자동으로 처리해주기 때문에, 시크릿 키를 username 필드에, password 필드는 비워서 입력하면 자동으로 인코딩해줘요.

API 기본 URL

토스페이먼츠 API의 기본 URL은 다음과 같아요.

  • 운영 환경: https://api.tosspayments.com/v1/
  • 테스트 환경: 별도 URL 없이 테스트 키를 사용하면 테스트 환경에서 동작해요.

결제 내역 조회 API 엔드포인트

결제 내역을 조회하는 방법은 크게 두 가지예요. 특정 결제 건을 조회하는 방법과 기간별 전체 내역을 조회하는 방법이에요.

결제 키로 단건 조회

특정 결제 건을 조회할 때는 결제 키(paymentKey)를 사용해요.

  • 엔드포인트: GET /v1/payments/{paymentKey}
  • 예시 요청: GET https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6

이 API는 결제 승인, 취소 등의 이벤트 발생 후 최신 상태를 확인하거나, 고객 문의 대응 시 특정 결제를 찾을 때 유용해요.

주문 번호로 조회

주문 번호(orderId)를 알고 있다면 이를 기준으로 결제를 조회할 수도 있어요.

  • 엔드포인트: GET /v1/payments/orders/{orderId}
  • 예시 요청: GET https://api.tosspayments.com/v1/payments/orders/a4CWyWY5m89PNh7xJwhk1

가맹점에서 자체 관리하는 주문 번호와 토스페이먼츠 결제를 매핑할 때 편리한 방법이에요.

기간별 결제 내역 조회

특정 기간 내의 모든 결제를 조회하는 API도 있어요.

  • 엔드포인트: GET /v1/payments
  • 필수 파라미터: startDate(시작일), endDate(종료일)
  • 선택 파라미터: cursor(페이지 커서), limit(최대 조회 건수, 기본 10, 최대 10)

날짜 형식은 ISO 8601 형식(예: 2026-05-01T00:00:00)을 사용해요. 최대 조회 기간은 API 버전과 정책에 따라 다를 수 있으니 공식 문서를 확인하세요.

응답 데이터 구조 이해하기

API 호출 후 반환되는 응답 데이터를 이해해야 결제 정보를 올바르게 처리할 수 있어요.

주요 응답 필드

결제 단건 조회 시 반환되는 주요 필드를 살펴볼게요.

  • paymentKey: 토스페이먼츠 결제 고유 키
  • orderId: 가맹점 주문 번호
  • orderName: 주문명(상품명)
  • status: 결제 상태(READY, IN_PROGRESS, WAITING_FOR_DEPOSIT, DONE, CANCELED, PARTIAL_CANCELED, ABORTED, EXPIRED)
  • requestedAt: 결제 요청 시각
  • approvedAt: 결제 승인 시각
  • totalAmount: 결제 총금액
  • balanceAmount: 잔액(취소 후 남은 금액)
  • method: 결제 수단(카드, 가상계좌, 계좌이체, 휴대폰, 간편결제 등)

결제 수단별 추가 필드

결제 수단에 따라 추가 필드가 포함돼요. 카드 결제의 경우 ‘card’ 객체 안에 카드사 코드, 카드 번호 앞 6자리, 할부 개월, 카드 유형 등이 포함돼요. 가상계좌의 경우 ‘virtualAccount’ 객체 안에 은행 코드, 계좌 번호, 입금 만료 시각 등이 담겨요.

취소 내역 확인

결제에 취소 이력이 있으면 응답에 ‘cancels’ 배열이 포함돼요. 각 취소 항목에는 취소 금액, 취소 사유, 취소 시각 등의 정보가 담겨요. 부분 취소가 여러 번 이루어진 경우 배열에 여러 항목이 포함돼요.

에러 처리와 예외 상황 대응

API를 사용하다 보면 에러가 발생할 수 있어요. 에러 유형을 이해하고 적절히 처리하는 것이 중요해요.

일반적인 에러 코드

토스페이먼츠 API는 에러 발생 시 HTTP 상태 코드와 함께 에러 코드와 메시지를 반환해요.

  • 400 Bad Request: 요청 파라미터가 잘못됐어요. 날짜 형식, 필수 파라미터 누락 등을 확인하세요.
  • 401 Unauthorized: 인증 실패예요. API 키가 맞는지 확인하고, 시크릿 키 뒤에 콜론이 붙었는지 확인하세요.
  • 404 Not Found: 해당 결제 키 또는 주문 번호가 존재하지 않아요.
  • 429 Too Many Requests: API 호출 한도를 초과했어요. 잠시 후 다시 시도하거나 호출 빈도를 줄여야 해요.
  • 500 Internal Server Error: 토스페이먼츠 서버 오류예요. 잠시 후 재시도하세요.

에러 응답 구조

에러 발생 시 응답 본문에는 ‘code’와 ‘message’ 필드가 포함돼요. 예를 들어 인증 실패의 경우 code: “UNAUTHORIZED_KEY”, message: “인증되지 않은 시크릿 키 혹은 클라이언트 키 입니다”와 같은 형태로 반환돼요. 에러 코드를 기반으로 자체 시스템에서 적절한 처리를 해야 해요.

재시도 로직 구현

네트워크 일시 오류나 서버 과부하로 인한 5xx 에러는 재시도로 해결되는 경우가 많아요. 지수 백오프(Exponential Backoff) 방식으로 재시도 간격을 점진적으로 늘리는 로직을 구현하는 것이 좋아요. 최대 재시도 횟수를 설정해 무한 루프에 빠지지 않도록 해야 해요.

웹훅(Webhook)을 활용한 실시간 결제 알림

결제 내역을 주기적으로 API로 가져오는 방식 외에, 웹훅을 활용하면 결제 이벤트가 발생할 때마다 실시간으로 알림을 받을 수 있어요.

웹훅 설정 방법

파트너센터 → 웹훅 메뉴에서 웹훅 URL을 등록해요. 결제 완료, 가상계좌 입금 등의 이벤트가 발생하면 토스페이먼츠가 등록한 URL로 HTTP POST 요청을 보내줘요. 웹훅 URL은 HTTPS를 지원하는 공개 엔드포인트여야 해요.

웹훅 이벤트 유형

주요 웹훅 이벤트는 다음과 같아요.

  • PAYMENT_STATUS_CHANGED: 결제 상태 변경 시 발생
  • VIRTUAL_ACCOUNT_STATUS_CHANGED: 가상계좌 입금 확인 시 발생

웹훅을 수신한 후에는 해당 결제 키로 API를 조회해 최신 상태를 확인하는 것을 권장해요. 웹훅 데이터만 신뢰하지 말고 반드시 서버 측 조회로 검증하세요.

마무리: API 활용으로 결제 관리 자동화

토스페이먼츠 결제 내역 API를 잘 활용하면 대시보드 수동 조회 없이도 결제 정보를 자동으로 가져와 자체 시스템에서 관리할 수 있어요. 결제 키 기반 단건 조회부터 기간별 전체 조회, 웹훅을 통한 실시간 알림까지 다양한 방식을 조합해서 사용하면 효율적인 결제 관리 시스템을 구축할 수 있어요.

API 연동 시 가장 중요한 것은 시크릿 키를 절대 클라이언트에 노출하지 않는 것이에요. 모든 API 호출은 서버 사이드에서 처리하고, 테스트 키와 운영 키를 명확히 구분해서 사용하세요. 공식 토스페이먼츠 개발자 문서도 함께 참고하면 더욱 정확한 정보를 얻을 수 있어요.

© 2026 Marketer • Built with GeneratePress
Privacy Policy Terms Contact