토스페이먼츠 API 응답은 어떻게 확인하나요? 상태 코드부터 오류 해결까지

REST API를 호출하면 HTTP 응답을 받아요. 그렇다면 응답에서 어떤 정보를 확인해야 할까요? API 요청이 성공했는지 확인하는 것뿐 아니라, 실패했다면 원인이 무엇인지 파악하고 그에 맞게 처리해야 해요. HTTP 응답은 크게 상태 줄, 응답 헤더, 응답 본문으로 구성돼요. 토스페이먼츠 결제 승인 API를 예시로 각 항목의 의미와 확인 방법을 알아볼게요.

REST API와 HTTP는 어떤 관계인가요?

REST API는 소프트웨어 아키텍처 스타일이고, HTTP는 클라이언트와 서버가 데이터를 주고받을 때 사용하는 통신 프로토콜이에요.

HTTP는 웹 브라우저와 웹 서버가 정해진 규칙에 따라 요청과 응답을 주고받을 수 있도록 만들어졌어요. 클라이언트가 특정 형식으로 요청을 보내면 서버는 그에 대한 응답을 반환하고, 응답을 통해 요청의 성공 여부와 결과를 확인할 수 있어요.

반면 REST는 소프트웨어를 설계하는 방식이에요. 일관된 인터페이스와 무상태성(Stateless) 등이 주요 특징이며, 일반적으로 HTTP를 통신 프로토콜로 사용해요. 토스페이먼츠 API도 HTTP 기반으로 요청과 응답을 주고받아요. 따라서 API 응답을 이해하려면 HTTP 응답이 어떤 구조로 이루어져 있는지 알아두는 것이 좋아요.

REST API와 HTTP의 관계를 설명하는 이미지

1. HTTP 응답의 상태 코드는 어떻게 확인하나요?

상태 줄(Status Line)에서 HTTP 버전과 상태 코드를 확인할 수 있어요. 상태 코드는 요청이 성공했는지, 클라이언트나 서버에서 오류가 발생했는지 파악하는 데 도움이 돼요.

토스페이먼츠 결제 승인 API를 curl 명령어로 호출할 때 -v 옵션을 추가하면 요청과 응답에 대한 상세 정보를 확인할 수 있어요.

curl -v --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic {인증 정보}' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"{결제 키}","orderId":"{주문 ID}","amount":15000}'

위 명령어는 결제 승인 API 호출을 보여주는 예시예요. 실제 테스트에서는 유효한 인증 정보와 결제 요청 정보를 사용해야 해요.

응답은 다음과 같은 형태로 표시될 수 있어요.

< HTTP/2 404

여기서 HTTP/2는 HTTP 프로토콜 버전을, 404는 응답 상태 코드를 의미해요.

HTTP 상태 코드 404는 무슨 뜻인가요?

404 Not Found는 요청한 리소스를 찾을 수 없다는 의미예요. 다만 상태 코드만으로는 구체적인 오류 원인을 모두 알 수 없으므로 응답 본문도 함께 확인해야 해요.

HTTP 상태 코드는 첫 번째 숫자를 기준으로 다음과 같이 구분할 수 있어요.

  • 1xx: 요청을 처리 중이라는 정보 응답
  • 2xx: 요청이 성공적으로 처리됨
  • 3xx: 추가 동작이나 리다이렉션이 필요함
  • 4xx: 클라이언트 요청과 관련된 오류
  • 5xx: 서버에서 요청을 처리하는 중 발생한 오류

각 상태 코드의 구체적인 의미는 아래 문서에서 확인할 수 있어요.

HTTP 상태 코드의 유형을 정리한 이미지

API 요청이 성공했는지는 상태 코드만 확인하면 되나요?

상태 코드는 요청의 처리 결과를 빠르게 파악하는 데 유용하지만, 구체적인 결과와 오류 원인을 확인하려면 응답 본문도 살펴봐야 해요.

예를 들어 2xx 상태 코드는 요청이 성공적으로 처리됐음을 나타내지만, 실제 결제 처리 결과에 필요한 정보는 응답 본문에 담겨 있어요. 반대로 오류 상태 코드를 받았다면 응답 본문에 포함된 오류 코드와 메시지를 확인해 원인을 파악해야 해요.

2. HTTP 응답 헤더에서는 무엇을 확인해야 하나요?

응답 헤더는 서버가 반환한 데이터의 형식이나 보안 관련 정책 등 추가 정보를 제공해요. 결제 연동 과정에서 모든 헤더를 직접 처리할 필요는 없지만, 주요 항목의 의미를 알아두면 통신 문제를 분석할 때 도움이 돼요.

HTTP 응답 헤더는 일반적으로 이름: 값 형태로 표시돼요.

< content-type: application/json
< content-length: 85
< referrer-policy: no-referrer-when-downgrade
< x-content-type-options: nosniff
< strict-transport-security: max-age=31536000

응답 헤더 중 콘텐츠와 보안에 관련된 주요 항목을 살펴볼게요.

응답 본문은 어떤 형식으로 반환되나요?

Content-Type 헤더에서 응답 본문의 형식을 확인할 수 있어요.

  • Content-Type: application/json

    응답 본문이 JSON 형식이라는 의미예요. JSON 파서를 사용해 데이터를 읽고 필요한 값을 추출할 수 있어요.

  • Content-Length

    응답 본문의 길이를 바이트 단위로 나타내요. 예를 들어 Content-Length: 85라면 본문 길이가 85바이트라는 의미예요.

HTTP 응답 헤더는 보안과 어떤 관련이 있나요?

응답 헤더에는 브라우저가 콘텐츠를 처리하는 방식이나 HTTPS 연결에 관한 정책 등 보안 관련 정보도 포함될 수 있어요.

  • Referrer-Policy

    다른 페이지로 이동하거나 리소스를 요청할 때 이전 페이지의 URL 정보를 어느 범위까지 전달할지 제어해요. 구체적인 동작은 설정된 정책에 따라 달라져요.

  • X-Content-Type-Options: nosniff

    브라우저가 선언된 콘텐츠 유형을 임의로 추측하지 않도록 해 콘텐츠 유형 혼동으로 인한 일부 보안 위험을 줄여요.

  • Strict-Transport-Security

    브라우저가 해당 사이트에 HTTPS로 접속하도록 유도하는 보안 정책을 지정해요. 예를 들어 max-age=31536000은 정책을 31,536,000초 동안 적용한다는 의미예요.

이런 헤더는 API 응답을 분석할 때 참고할 수 있지만, 일반적인 결제 연동에서는 상태 코드와 응답 본문을 먼저 확인하는 것이 좋아요.

3. API 응답 본문에서 오류 원인을 어떻게 찾나요?

API 요청이 실패했다면 응답 본문에 담긴 오류 코드와 메시지를 확인하세요. HTTP 상태 코드만으로는 구체적인 실패 원인을 알기 어려울 수 있기 때문이에요.

토스페이먼츠 API의 오류 응답은 다음과 같은 JSON 형태로 반환될 수 있어요.

{
  "code": "NOT_FOUND_PAYMENT",
  "message": "존재하지 않는 결제 정보 입니다."
}

이 응답에서는 두 가지 정보를 확인할 수 있어요.

  • code: 오류를 구분하는 코드예요.
  • message: 오류 내용을 설명하는 메시지예요.

예시의 NOT_FOUND_PAYMENT는 요청한 결제 정보를 찾을 수 없다는 의미예요. 결제 승인 API를 호출할 때 전달한 paymentKey나 orderId가 올바른지, 해당 결제 정보가 존재하는지 등을 확인해 볼 수 있어요.

오류가 발생했다면 메시지만 읽고 끝내기보다 전달한 요청 값과 결제 상태를 함께 점검하는 것이 좋아요.

👉 토스페이먼츠 API 오류 코드 확인하기

API 오류 응답의 code와 message를 설명하는 이미지

4. 결제 승인 API가 성공하면 어떤 응답을 받나요?

결제 승인 API가 정상적으로 처리되면 성공 상태 코드와 함께 결제 정보를 담은 Payment 객체가 반환돼요. 이 객체에는 결제 키, 주문 정보, 결제 상태, 결제 금액, 결제수단 등의 정보가 포함될 수 있어요.

올바른 결제 정보로 승인 API를 호출하면 다음과 같은 형태의 응답을 받을 수 있어요.

{
  "mId": "tosspayments",
  "paymentKey": "GRZsY5vcKZmThoeJMcKwv",
  "status": "DONE",
  "orderId": "TBtoNKlSpgNhr2T8ZkNau",
  "orderName": "토스 티셔츠 외 2건",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "currency": "KRW",
  "method": "카드"
}

위 JSON은 응답 구조를 간단히 보여주는 예시예요. 실제 응답에는 결제수단과 거래 상태 등에 따라 더 많은 필드가 포함될 수 있어요.

Payment 객체에서 어떤 값을 확인해야 하나요?

결제 승인 응답을 받았다면 서비스 운영에 필요한 주요 필드를 확인하고 저장해야 해요.

  • paymentKey

    결제 정보를 조회하거나 결제를 취소할 때 사용하는 결제 키예요.

  • status

    결제 상태를 나타내요. 결제 상태에 따라 주문을 처리하도록 구현할 수 있어요.

  • orderId

    쇼핑몰에서 관리하는 주문 ID예요. 내부 주문 정보와 연결할 때 사용해요.

  • method

    카드, 가상계좌 등 결제에 사용한 수단을 나타내요.

  • totalAmount

    총 결제 금액을 나타내요.

  • card 또는 virtualAccount

    결제수단에 따라 관련 정보가 포함돼요. 카드결제라면 card에 카드 관련 정보가 담길 수 있고, 가상계좌 결제라면 virtualAccount에 관련 정보가 담길 수 있어요.

  • receipt

    영수증을 확인할 수 있는 URL이 포함될 수 있어요. 제공 여부와 세부 동작은 결제 환경에 따라 확인해야 해요.

응답 본문에서 필요한 값을 추출한 다음에는 주문 정보와 결제 정보를 올바르게 연결해 데이터베이스에 저장하세요. 결제 승인 결과를 확인하고 주문 상태를 처리하는 로직도 함께 구현해야 해요.

API 응답을 받은 뒤에는 무엇을 해야 하나요?

응답을 파싱하고, 성공과 실패를 구분한 뒤, 결과에 맞게 후속 처리를 해야 해요.

결제 승인 API를 연동할 때는 다음 순서로 확인하면 좋아요.

  1. HTTP 상태 코드를 확인해요.
  2. 응답 본문에서 성공 데이터 또는 오류 코드와 메시지를 확인해요.
  3. 성공 응답이라면 결제 상태와 금액, 주문 ID 등 필요한 값을 검증해요.
  4. 검증한 결제 정보를 데이터베이스에 저장해요.
  5. 실패 응답이라면 오류 원인을 파악하고 적절한 예외 처리를 진행해요.

특히 결제 완료 여부를 브라우저 화면이나 클라이언트의 응답만으로 판단하지 말고, 서버에서 결제 승인 결과를 검증한 뒤 주문 상태를 변경하도록 구현하는 것이 중요해요.

토스페이먼츠 API 응답을 이해하고 안정적으로 연동하세요

API 응답을 확인할 때는 상태 코드, 응답 헤더, 응답 본문을 구분해서 살펴보면 돼요.

  • 상태 코드로 요청이 성공했는지 확인해요.
  • 응답 헤더로 데이터 형식과 통신 관련 정보를 살펴봐요.
  • 응답 본문에서 결제 결과와 오류 원인을 확인해요.

이 세 가지를 이해하면 결제 연동 중 문제가 발생했을 때 원인을 더 빠르게 파악하고, 성공과 실패에 맞는 처리를 구현하는 데 도움이 돼요.

토스페이먼츠의 모든 콘텐츠는 사업자에게 도움이 될 만한 일반적인 정보를 참고 목적으로 제공하고 있어요. 구체적인 사안에 관한 자문을 대신하지 않으며, 콘텐츠에서 취득한 정보로 인해 발생한 손해에 대해 법적 책임을 부담하지 않아요.

ⓒ 토스페이먼츠. 무단 전재 및 배포 금지.

    의견 남기기
    ChatGPT가 우리 상품을 추천하게 만드는 법무료 웨비나에서 확인하기
    웨비나 l 2026 GEO 그로스 살롱 글로벌
    이어서 읽어보세요.

    해외 고객의 ChatGPT에 우리 상품을 추천하는 방법

    바로 읽기
    이어서 읽어보세요.

    해외 고객의 ChatGPT에 우리 상품을 추천하는 방법

    바로 읽기