SION.LAB
자료실
자료실
커머스·소통APIofficial

토스페이먼츠 API

국내 카드·간편결제·정기결제를 구현하는 토스페이먼츠 공식 API

자료 등록 2026년 3월 15일

한눈에 보기

공식 검증 2026년 8월 29일

프로토콜
REST · JSON
인증
상점 시크릿 키 · 기능별 인증
비용
계약·결제수단별 수수료
제공 상태
정식 제공 · 일부 기능 계약 필요
공식 빠른 시작공식 빠른 시작 · https://docs.tosspayments.com/reference

Use cases

이럴 때 이렇게 연결합니다

먼저 어떤 어려움을 해결하는지 읽고, 그림에서 입력과 전달값, 사람 확인 지점을 따라가 보세요. 결과 패널은 해당 흐름이 끝났을 때 남는 값을 보여 줍니다. 아래 내용은 공식 기능을 바탕으로 만든 예시 설계이며, SION.LAB의 실제 운영 사례를 뜻하지 않습니다.

추천 구성 · Situation 01

결제 승인·취소·정기결제 상태를 주문 데이터와 맞추지 못해 고객 문의 대응이 늦어지는 업무

어떤 어려움인가
국내 결제 화면을 운영하는 제품팀이 자주 마주치는 문제입니다. 구체적으로는 '결제 승인·취소·정기결제 상태를 주문 데이터와 맞추지 못해 고객 문의 대응이 늦어지는 업무' 상황입니다.
이렇게 해결합니다
토스페이먼츠 API 단계에서는 요청과 응답 필드를 작은 범위로 맞춥니다. 입력 범위는 '주문번호, 결제키, 금액, 고객 동의 범위'입니다. 필요한 필드만 골라 '주문과 승인·취소 상태가 대조된 결제 기록' 형태로 정리합니다.
왜 연결하는가
처음에는 토스페이먼츠 API 하나만 사용합니다. 입력·처리·검토 경계를 확인한 뒤에만 다른 시스템과 연결하면 실패 원인을 찾기 쉽습니다.
마지막 확인
검토 대상은 '주문과 승인·취소 상태가 대조된 결제 기록'입니다. 원문 근거, 제외 조건, 누락 항목이 구분되는지 확인합니다. 결과를 바로 반영하지 않고 담당자가 확인한 뒤 다음 단계로 넘깁니다.
Sequence입력부터 검토 결과까지
  1. 01 · 입력작은 입력 범위주문번호, 결제키, 금액, 고객 동의 범위
    업무 조건
  2. 02 · 현재 자료토스페이먼츠 APIAPI 요청: 입력 범위는 '주문번호, 결제키, 금액, 고객 동의 범위'입니다. 필요한 필드만 골라 '주문과 승인·취소 상태가 대조된 결제 기록' 형태로 정리합니다.
    처리 결과
  3. 03 · 사람 확인담당자 검토검토 대상은 '주문과 승인·취소 상태가 대조된 결제 기록'입니다. 원문 근거, 제외 조건, 누락 항목이 구분되는지 확인합니다.
    확인 완료
  4. 04 · 결과검토용 결과주문과 승인·취소 상태가 대조된 결제 기록

Result

이 흐름으로 남는 값

첫 요청

curl -u YOUR_TOSS_SECRET_KEY: https://api.tosspayments.com/v1/payments/YOUR_PAYMENT_KEY

무엇이고 왜 필요한가

토스페이먼츠 API는 국내 카드·계좌이체·가상계좌·간편결제의 승인·취소·정산 흐름을 서버에서 구현하는 공식 결제 API입니다. 결제창 연동뿐 아니라 결제 금액 검증과 웹훅·실패 복구를 함께 설계해야 합니다.

할 수 있는 일

  • 결제를 승인·조회·취소하고 상태를 관리합니다.
  • 빌링키와 지급·브랜드페이 등 계약 기능을 연동합니다.

시작 전 확인

  • 개발자센터 테스트 키로 시작하고 계약 기능·상점 설정을 확인합니다.
  • 인증·비용 조건은 상점 시크릿 키 · 기능별 인증, 계약·결제수단별 수수료이며 제공 상태는 정식 제공 · 일부 기능 계약 필요입니다.
  • 첫 요청은 공식 샘플과 테스트 자격으로 실행해 정상 응답·오류·호출 제한을 함께 확인합니다.

잘 맞는 경우

  • 국내 이커머스와 구독 서비스에 결제를 붙이는 팀.

주의점

  • 시크릿 키는 서버에만 두고 금액 위변조·중복 승인·웹훅 검증을 방어합니다.
  • API 키는 브라우저 코드나 공개 예제에 넣지 않고 서버 비밀값으로 보관하며, 호출 실패·재시도·사용량을 기록합니다.

댓글 0

아직 댓글이 없습니다. 첫 댓글을 남겨보세요.

문의하기