연동 준비하기

토스페이먼츠가 처음이라면 연동 준비를 위한 아래 가이드를 순서대로 따라해보세요.

1. 준비하기: 토스페이먼츠 연동을 위한 API 키, 테스트 환경 이해, 방화벽 설정 등 연동 전에 꼭 참고해야 하는 정보를 알려드려요.
2. 첫 API 호출하기: 발급받은 API 키로 첫 번째 API를 호출하고 API 요청・응답에 대해 이해해요.
3. 결제 내역 확인하기: 호출한 API의 테스트 결제 내역을 개발자센터에서 확인해요.

개발자용 테스트상점과 문서에서 사용하는 키는 아래와 같아요. 테스트용 키는 앞에 test_가 붙어 있어요.

• 클라이언트 키: ck_로 시작하는 클라이언트 키는 SDK 연동에 사용합니다.

test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq

• 시크릿 키: sk_로 시작하는 시크릿 키는 토스페이먼츠 API를 호출할 때 인증에 사용합니다. 시크릿 키는 외부에 절대 노출되면 안 됩니다.

test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R

회원가입 후 로그인하면 개발자센터에서 내 API 키를 볼 수 있어요. PG 계약, 사업자번호 발급 상태와 상관 없이 이메일 주소만으로 토스페이먼츠에 회원가입을 할 수 있어요.

내 개발정보에 진입하면 왼쪽 메뉴 상단에 계정과 API 키에 대한 정보가 있어요.

왼쪽 메뉴 상단에 내 상점 이름과 MID가 보인다면, 내 테스트 키나 라이브 키를 볼 수 있어요. 내 테스트 키나 라이브 키로 설정하면 내가 계약한 결제수단만 연동할 수 있어요. 예를 들어, 카드 결제만 계약했는데 가상계좌 결제를 시도하면 에러가 나요.

만약 위 이미지와 같이 왼쪽 메뉴 상단에 '개발자용 테스트상점'이 보이면 위에서 소개한 테스트 키와 같은 값이에요. '개발자용 테스트상점' 테스트 키로는 모든 결제수단을 연동해볼 수 있어요.

더 자세한 내용은 API 키 가이드에서 확인하세요.

내 API 키 아래에 API 버전을 확인하고 변경할 수 있는 기능이 있어요. 버전에 따라 요청 파라미터, 응답 내용이 변경될 수 있습니다. 릴리즈 노트에서 각 버전에서 변경된 필드 정보를 확인해 보고, 필요한 버전을 선택해 사용하세요.

API 문서 상단 왼쪽에서 API 버전을 선택할 수 있어요. 문서에서 보여주는 모든 응답 예시는 가장 최신 버전을 기준으로 작성되어 있습니다. 더 자세한 내용은 API 버전 정책을 참고하세요.

테스트 키로 연동할 때 실제 결제 정보(카드 번호, 휴대폰 번호 등)를 사용해도 결제 승인은 가상으로 이루어져요. 따라서 테스트 환경에서는 결제 승인에 성공해도 내 결제수단에서 빠져나가는 금액은 없어요.

테스트 환경이 라이브 환경과 달라서 주의해야 할 점이에요.

테스트 환경에서 에러를 재현하고 싶다면 토스페이먼츠 API 테스트 헤더를 사용하세요.

TossPayments-Test-Code: {TEST_CODE}

• {TEST_CODE} 자리에 재현하고 싶은 에러 코드를 넣고 API를 실행하세요.
• test_ 로 시작하는 테스트 API 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.

예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION를 테스트 헤더에 추가하세요.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/key-in \
  --header 'Authorization: ' \
  --header 'Content-Type: application/json' \
  --header 'TossPayments-Test-Code: INVALID_CARD_EXPIRATION' \

토스페이먼츠는 고객의 결제 정보와 개인 정보를 보호하기 위해 HTTPS 통신과 TLS 버전 1.2 이상만 지원해요.

서버에서 아래 토스페이먼츠 IP 주소를 허용해주세요. 더 자세한 내용은 방화벽 가이드에서 확인하세요.

토스페이먼츠 SDK가 지원하는 브라우저 환경이에요.