요청·응답 본문
요청 본문
요청 본문은 클라이언트가 API를 요청할 때 보내는 데이터입니다. 토스페이먼츠 API에 요청할 때는 JSON 형식을 사용하세요.
URL 인코딩
전체 요청 본문을 인코딩할 필요는 없습니다. 특수 문자가 요청 본문이나 쿼리 파라미터 값에 포함되어 있다면 URL 인코딩을 해야 합니다. 데이터를 안전하게 전송하고, 서버에서 정확하게 해석되도록 하는 중요한 단계입니다.
URL 인코딩은 웹에서 안전하게 데이터를 전송하기 위해 특정 문자를 % 기호와 두 개의 16진수 숫자로 변환하는 과정입니다. 인코딩은 데이터가 전달되는 과정에서 오류나 변조 없이 완전하고 믿을 수 있는 상태로 유지해서 웹 서버가 요청을 정확하게 해석하도록 도와줍니다.
// 원본 데이터
name=John Doe&age=30
// 인코딩 후
name=John%20Doe&age=30
API 요청을 할 때 데이터 전송의 정확성과 안전성을 보장하려면 URL 인코딩을 하세요. 대부분의 프로그래밍 언어 및 플랫폼에서는 URL 인코딩을 위한 내장 함수나 라이브러리를 제공합니다. 사용하는 언어에 맞는 인코딩 방법을 참조하여 API 요청을 준비하세요.
응답 본문
응답 본문은 서버가 클라이언트에 보내는 데이터입니다. 토스페이먼츠 API의 성공 여부는 HTTP 상태 코드로 전달합니다. 돌아온 HTTP 상태 코드에 따라 요청이나 에러를 처리하는 로직을 구축하세요.
모든 API 응답, 요청 본문은 JSON 형식입니다. 따라서 응답 헤더에는 다음과 같이 Content-Type이 포함됩니다.
Content-Type: application/json
응답 HTTP 상태 코드
| HTTP 상태 코드 | 설명 |
|---|---|
200 - OK | 요청이 성공적으로 처리되었습니다. |
400 - Bad Request | 요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해주세요. |
403 - Forbidden | 시크릿 키 없이 요청했거나 사용한 시크릿 키가 잘못되었습니다. 개발자센터에서 내 상점의 키 값을 다시 한 번 확인하고, 시크릿 키 문서를 참고하세요. |
404 - Not Found | 요청한 리소스가 존재하지 않습니다. 요청한 API 주소를 다시 한 번 확인해보세요. |
429 - Too Many Requests | 비정상적으로 많은 요청을 보냈습니다. 잠시 후 다시 시도해주세요. |
500 - Server Error | 토스페이먼츠 서버에서 에러가 발생했습니다. |
에러 객체
요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다.
{
"code": "NOT_FOUND_PAYMENT",
"message": "존재하지 않는 결제 입니다."
}
code: 에러 타입을 보여주는 에러 코드입니다.message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.
API 별 에러 코드와 메시지는 에러 코드 페이지에서 살펴보세요.
유의사항
API 응답이나 웹훅 이벤트 본문에 새로운 필드가 추가와 같이 하위 호환을 지원하는 변경 사항은 버전 릴리즈 없이 기존 API에 반영됩니다. 클라이언트 코드는 이러한 변경에 유연하게 대응할 수 있도록 작성해 주세요. 추가된 새로운 필드를 무시하거나 기본값을 설정하는 방식으로 JSON 파싱 로직을 구성해 주세요.
예를 들어 Java에서는 ObjectMapper를 사용해서 JSON 응답을 처리할 때 .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false) 옵션을 설정하면 새로운 필드가 추가되어도 오류가 발생하지 않을 수 있습니다.