API 버전

토스페이먼츠 API 버전에 따라 API에 전송할 수 있는 파라미터의 종류, 응답 필드 등이 변경될 수 있습니다.

새로운 버전을 릴리즈 하더라도 상점에서 사용하고 있는 API의 버전은 변경하지 않습니다. 현재 상점에서 운영 중인 코드에 대한 하위 호환을 지원하기 위함입니다.

릴리즈 노트를 참고해서 새로운 버전의 변경 사항을 파악하고 개발을 마친 뒤 상점의 개발자센터에서 버전을 변경하세요.

버전 관리 정책

토스페이먼츠 API는 2022년 6월 8일 부터 API 릴리즈 날짜를 YYYY-MM-DD로 표기하는 날짜 기반 버전 관리(Calender Versioning)를 사용합니다.

버전 1.4 까지는 유의적 버전 관리(Semantic Versioning) 방식으로 표기하되 Major.Minor까지만 사용합니다.

버전 릴리즈 정책

API에 생기는 변경 사항 중 이전 버전과 호환되지 않는 변경 사항을 배포하는 경우 새로운 버전을 릴리즈합니다. 이전 버전과 호환되는 변경 사항을 배포할 때는 버전을 새로 릴리즈하지 않습니다. 자세한 기준은 아래 내용을 참고해주세요.

하위 호환을 지원하는 변경 사항

토스페이먼츠에서는 다음과 같은 변경 사항에 대해 하위 호환을 지원하는 것으로 판단합니다. 따라서 새로운 버전 릴리즈 없이 기존 API에 반영합니다.

  • 새로운 API 엔드포인트 추가
  • API 요청에 새로운 선택 파라미터 추가
  • API 요청에서 사용하는 필수 파라미터를 선택 파라미터로 변경
  • API 응답에 새로운 필드 추가
  • 새로운 ENUM 추가
  • 에러 메시지 변경
  • 새로운 에러 코드 추가
  • 새로운 웹훅 이벤트 추가

새로운 버전을 릴리즈 하는 변경 사항

토스페이먼츠에서는 다음과 같은 변경 사항이 배포될 때 새로운 버전을 릴리즈합니다.

  • API 엔드포인트 제거
  • API 요청에 새로운 필수 파라미터 추가
  • API 요청의 선택 파라미터를 필수 파라미터로 변경
  • API 응답에 사용되던 필드 삭제
  • API 응답 필드 중 nullable 하지 않았던 필드를 nullable 하게 변경
  • 같은 의미를 나타내는 에러 코드의 변경
  • 같은 의미를 나타내는 ENUM 코드의 변경 (예: 토스결제 → 토스페이)

이 정책은 버전 2022-06-08부터 적용됩니다. 이전 버전은 각 버전 별 릴리즈 노트를 통해 변경사항을 확인해주세요.

내 상점의 API 버전 확인·변경하기

API 버전은 개발자센터에서 확인·변경할 수 있습니다.

가입 후 자동으로 생성되는 테스트 상점의 API 버전은 최신 버전입니다.

계약 후 상점아이디(MID)가 발급된 내 상점의 API 버전은 다를 수 있습니다. 내 상점의 테스트 환경 API 버전과 라이브 환경에서도 API 버전을 다르게 사용할 수 있습니다. 내 상점의 테스트 환경 API 버전은 계약 신청이 완료되었을 때, 라이브 API 버전은 계약 완료 시점에 API 키 발급과 함께 정해집니다.

릴리즈 노트

API 버전 별로 사용할 수 있는 기능과 변경 사항을 알아보세요.

2022-06-08

Payment 객체 - mobile.carrier 필드 제거

결제 건에 대한 통신사 코드 정보는 개인 정보 보호 정책으로 인해 제공할 수 없어 휴대폰 결제 응답 결과로 돌아오는 mobile.carrier 필드를 제거합니다.

Payment 객체 - card.provider 필드 제거

카드 객체에서 간편결제 결제 수단 정보를 제공하던 card.provider가 제거됩니다. 간편결제 결제 수단 정보는 객체로 변경된 easyPayprovider로 대체됩니다.

Payment 객체 - 간편결제 응답 업데이트

간편결제를 사용해서 결제한 경우 Payment 객체의 method간편결제(EASYPAY)로 돌아옵니다.

easyPay 필드가 문자열에서 객체로 변경되어 아래 정보를 제공합니다.

  • provider: 간편결제 결제 수단 정보입니다.

  • amount: 간편결제 결제 수단에 등록된 카드, 계좌 중 하나로 결제한 금액입니다.

  • discountAmount: 간편결제 결제 수단의 적립 포인트나 쿠폰 등을 사용해서 즉시 할인된 금액입니다.

  • 추가된 easyPay 필드 살펴보기

간편결제 케이스 별 응답에 대한 자세한 내용은 간편결제 처리하기를 참고하세요.

ENUM - 토스결제토스페이로 변경

간편결제 결제 수단 ENUM에서 한글 ENUM이 토스결제 대신 토스페이로 변경됩니다.

요청할 때는 기존 코드인 토스결제를 써도 오류가 나지 않지만 응답으로 돌아오는 Payment.easyPay.provider에서는 토스페이만 돌려줍니다.

ENUM - CONNECTPAYBRANDPAY로 변경

커넥트페이 제품의 이름이 브랜드페이로 변경되어 결제 응답 객체의 Payment.type에 CONNECTPAY 대신 BRANDPAY가 돌아옵니다. 버전 1.4까지는 CONNECTPAY가 돌아옵니다. 그 외 브랜드페이 마이그레이션 관련 내용은 마이그레이션 페이지를 참고하세요.

웹훅 - 가상계좌 웹훅 상태 값 변경

고객 계좌 송금 한도가 초과되었거나 네트워크 이슈 등으로 입금이 취소되어 발생하는 가상계좌 웹훅의 상태가 변경될 때 고객이 다시 입금해야 하는 경우가 있습니다. 이 상태를 나타내는 값이 CANCELED에서 WAITING_FOR_DEPOSIT으로 변경됐습니다.

즉, 같은 주문에 대한 가상계좌 웹훅 상태가 DONEWAITING_FOR_DEPOSIT 으로 변경되어 돌아올 때 다시 입금되어야 합니다.

자세한 내용은 웹훅 페이지에서 확인할 수 있습니다.

v1.4

버전 1.4에서는 Payment 객체, Billing 객체, Settlement 객체에 새로운 필드가 추가되었습니다. API 필드와 일반 결제 SDK 파라미터의 타입 변경도 살펴보세요.

공통 - 금액 정보 필드 타입 실수형으로 변경

소수점이 포함되어 있는 해외 통화의 금액 정보를 지원하기 위해 금액 정보의 타입이 정수형(integer)에서 실수형(number)으로 변경되었습니다.

이제 Payment 객체, Transaction 객체에서 *-amount로 끝나는 필드, API 요청에 사용되는 금액 파라미터 모두 실수형으로 사용할 수 있습니다.

예시
{
"mId": "tosspayments",
"version": "1.4",
"transactionKey": "01BDC3BE5C7EFB174EF4E551833E591C",
"paymentKey": "avNA96Bjgq7XZYkKL4MrjKZbZG7jE80zJwlEWR52xydGPnOQ",
"orderId": "vE6aTtIc_oPVx0eWQ6-B0",
"orderName": "토스 해외결제 외 1건",
"method": "해외간편결제",
"status": "ABORTED",
"requestedAt": "2021-11-15T15:19:37+09:00",
"approvedAt": null,
"useEscrow": null,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": {
"provider": "페이마야"
},
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": "페이마야",
"country": "PH",
"failure": {
"code": "COMMON_ERROR",
"message": "Failed - external billing failure"
},
"currency": "PHP",
"totalAmount": 1.25,
"balanceAmount": 1.25,
"suppliedAmount": 1.14,
"vat": 0.11,
"taxFreeAmount": 0.0
}
JSON

customerIdentityNumber로 카드 소유자 정보 필드 변경

카드 정보 결제빌링키 발급 요청에 사용되는 Request Body 파라미터에서 카드 소유자 정보로 사용하는 customerBirthdaycustomerIdentityNumber로 대체됩니다. 카드 소유자 정보로 생년월일과 사업자등록번호 두 가지 모두 사용할 수 있다는 것을 직관적으로 알 수 있도록 변경되었습니다.

customerBirthday는 사용이 권장되지 않습니다. customerIdentityNumber를 사용해주세요.

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

Payment 객체 - 결제한 국가 정보를 알려주는 필드 country 추가

Payment 객체에 결제한 국가 정보를 알려주는 필드인 country가 추가되었습니다. ISO-3166의 두 자리 국가 코드를 지원합니다. 기본값은 KR이고 requestPayment를 실행할 때 country 파라미터에 값을 추가하면 그 값이 반영됩니다.

Payment 객체 - 결제 실패 정보를 알려주는 필드 failure 추가

Payment 객체에 결제 실패 정보를 알려주는 필드인 failure가 추가되었습니다. 결제 승인에 실패하면 관련 에러 코드와 메시지를 아래와 같은 형태로 보여줍니다.

예시
{
"failure": {
"code": "COMMON_ERROR",
"message": "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요."
}
}
JSON

Billing 객체 - 카드 정보를 포함하는 card 필드 추가

Billing 객체card 필드가 추가되었습니다. 발급된 빌링키와 연결된 카드 정보가 포함되어 있습니다. cardCompanycardNumber는 사용이 권장되지 않습니다. card.company, card.number를 사용해주세요.

Billing
{
"mId": "tvivarepublica2",
"customerKey": "1638350476451",
"authenticatedAt": "2021-12-01T18:21:47+09:00",
"method": "카드",
"billingKey": "EyuSCFnjdiuoMhhLMvbskt_dQzt_xyrp-OZ9x0Axzxw=",
"card": {
"company": "삼성",
"number": "553176******6565",
"cardType": "신용",
"ownerType": "법인"
}
}
JSON

Settlement 객체 - 수수료 상세 정보를 알 수 있는 필드 fees 추가

Settlement 객체에 수수료 정보를 자세히 알 수 있는 필드가 추가되었습니다. 수수료의 세부 타입과 금액이 담긴 객체를 배열로 제공합니다.

Settlement
[
{
"mId": "tosspayments",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"currency": "KRW",
"method": "카드",
"amount": 34000,
"interestFee": 0,
"fees": [
{
"type": "BASE",
"fee": "800"
},
{
"type": "INSTALLMENT",
"fee": "60"
}
],
"supplyAmount": 782,
"vat": 78,
"payOutAmount": 33140,
"approvedAt": "2021-01-02T12:30:09+09:00",
"soldDate": "2021-01-02",
"paidOutDate": "2021-01-04"
}
]
JSON

일반 결제 SDK - 여러 개의 통신사 코드를 추가할 수 있도록 mobileCarrier 타입 변경

휴대폰 결제창에서 선택할 수 있는 통신사 종류를 제한할 때 사용하는 파라미터 mobileCarrier에 여러 개의 통신사 코드를 넣을 수 있도록 타입이 string에서 array로 변경되었습니다.

tossPayments.requestPayment('휴대폰', {
amount: 15000,
orderId: 'hRnY55x4Mf7FaRbwWgimH',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
mobileCarrier: ['KT', 'LGU', 'SKT'],
})
JavaScript

v1.3

버전 1.3에서는 Payment 객체에 세금 관련 필드 및 결제 정보를 거래 정보와 연결하는 transactionKey가 추가되었습니다.

  • orderName 결제에 대한 주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다.
  • transactionKey 거래 건에 대한 고유한 키 값입니다.
  • suppliedAmount 공급가액입니다.
  • vat 부가세입니다.
  • cultureExpense 문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓, 박물관·미술관 입장권 등)
  • taxFreeAmount 면세 금액입니다.
  • cancels.taxAmount 과세 처리된 금액입니다.

v1.2

버전 1.2에서는 Payment 객체에 응답 버전 정보와 결제 타입, 간편결제로 결제한 경우 간편결제 타입을 명시하는 easyPay 필드가 추가되었습니다.

  • version Payment 객체의 응답 버전입니다.
  • type 결제 타입 정보입니다. NORMAL(일반 결제), BILLING(자동 결제), CONNECTPAY(커넥트페이) 중 하나입니다.
  • easyPay 간편결제로 결제한 경우 간편결제 타입 정보입니다. 토스페이, 페이코, 삼성페이 같은 형태입니다.

데이터가 중복되어 제거・대체된 필드들도 살펴보세요.

  • useDiscount 즉시 할인 여부 (discount 유무로 대체)
  • discountAmount 즉시 할인 금액 정보 (discount.amount로 대체)
  • useCashReceipt 현금영수증 발급 여부 (cashReceipt로 대체)

v1.1

버전 1.1에서는 Payment 객체에 계좌이체 정보를 담은 필드 transfer와 가상계좌 정보를 담은 객체 내부에 계좌 타입을 나타내는 accountType이 추가되었습니다.

  • transfer 계좌이체로 결제했을 때 이체 정보가 담기는 객체입니다.

    • bank 이체할 은행입니다. 은행 코드를 참고하세요.
    • settlementStatus 정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETE, 정산이 완료됐다면 COMPLETE 값이 들어옵니다.
  • virtualAccount.accountType 가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.

계좌이체를 결제 수단으로 사용하거나, 가상계좌를 발급할 때 계좌 타입을 선택할 수 있는 상점에서는 응답 버전을 1.1 이상으로 설정하세요.

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기