첫 번째 API 호출하기

회원가입을 마치고 API 키를 발급받았다면, 첫 번째 API를 호출할 차례예요.

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

고객이 결제금액을 바로 입금할 수 있는 가상계좌를 발급하는 API를 예제로 호출해볼게요.

• 로그인했다면, 문서의 키 값도 내 테스트 키로 바뀌어요.
• 로그인하지 않고 문서에 있는 테스트 키도 결제 연동에 사용할 수 있지만, 결제 내역을 확인할 수 없어요.

1. 토스페이먼츠 API 테스트로 이동하세요.

2. 필수 파라미터 값을 채우고 '요청하기' 버튼을 눌러주세요.

3. API 호출 결과로 돌아온 HTTP 응답을 확인하세요.

   • 요청이 성공했다면 200 코드와 Payment 객체가 돌아옵니다.
   • 요청이 실패했다면 4xx 또는 5xx 코드와 에러 객체가 돌아옵니다.

cURL, Postman, Insomnia 등 원하는 HTTP 클라이언트 도구를 사용해서 API를 호출할 수도 있어요.

1. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩하세요. 콜론을 빠트리지 않도록 주의하세요. 인코딩된 값을 API 요청의 Basic 인증 헤더에 넣으세요.

   base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')
           ─────────────────┬───────────────── ┬
                       secretKey              :
                     발급받은 시크릿 키           콜론
   

   아래 커맨드로 시크릿 키를 base64로 인코딩할 수 있어요.

   echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:' | base64
   

   인증 헤더를 사용하는 방법을 더 자세히 확인해보세요.

2. Content-Type 헤더를 application/json로 설정하세요.

3. 필수 파라미터를 데이터로 입력하고 API를 호출하세요.

   • 요청이 성공했다면 200 코드와 Payment 객체가 돌아옵니다.
   • 요청이 실패했다면 4xx 또는 5xx 코드와 에러 객체가 돌아옵니다.
   요청

   curl --request POST \
     --url https://api.tosspayments.com/v1/virtual-accounts \
     --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
     --header 'Content-Type: application/json' \
     --data '{"amount":15000,"orderId":"RG7TlsNkx54d38bOsoueZ","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20","cashReceipt":{"type":"소득공제","registrationNumber":"01011111111"}}'

   cURL

   cURLJavaNode.jsC#PHPPythonRubyKotlin

API 요청에 추가할 수 있는 선택 헤더 목록입니다.

모든 필드와 오류 메시지는 기본적으로 한글로 제공됩니다. 영어로 응답을 받고 싶다면 요청 헤더에 Accept-Language를 포함하세요.

Accept-Language: en-US

결제 과정에서 팝업 차단 에러가 나는 것을 방지하기 위해 아래와 같이 HTTP 헤더를 설정해주세요. COOP(Cross-Origin-Opener-Policy)은 웹 사이트에서 팝업 창이나 새 탭을 열 수 있는지 정하는 보안 정책입니다.

Cross-Origin-Opener-Policy: same-origin-allow-popups

멱등키를 사용하면 민감한 API 요청이 반복적으로 일어나는 문제를 막을 수 있고, 네트워크 이슈나 타임아웃 문제로 응답을 받지 못했을 때도 안전하게 같은 요청을 다시 보낼 수 있습니다.

요청 헤더에 Idempotency-Key를 추가하면 멱등한 요청을 보낼 수 있습니다.

Idempotency-Key: {IDEMPOTENCY_KEY}

아래와 같이 API 요청에 멱등키 헤더를 사용하면 같은 요청이 두 번 일어나도 실제로 요청이 이루어지지 않고 첫 번째 요청 응답과 같은 응답을 보내줍니다.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/key-in
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: SAAABPQbcqjEXiDL' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"박토스","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerIdentityNumber":"881212"}'

더 자세한 내용은 멱등키를 참고하세요.

토스페이먼츠의 모든 API 응답에는 HTTP 상태 코드와 본문이 있습니다. 응답 본문은 JSON 포맷입니다.