릴리즈 노트

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

버전 관리 및 릴리즈 정책은 API 버전 정책 페이지에서 소개합니다.

2022-07-27

2022-07-27 버전에서는 현금영수증 API에 변경이 있었습니다.

CashReceipt 객체

이전 버전까지는 현금영수증 발급과 취소를 하나의 현금영수증 객체로 처리했지만, 2022-07-27 버전부터는 발급 요청과 취소 요청에 대한 정보를 각각 받을 수 있습니다.

  • 취소 요청일 때 receiptKey는 앞서 발급했던 현금영수증의 receiptKey에 prefix로 c_가 추가된 값으로 돌아옵니다.
  • transactionType을 통해 현금영수증 발급 요청 정보인지 취소 요청 정보인지 구분할 수 있습니다.
  • amount에는 요청한 현금영수증 종류에 따라 발급한 금액 혹은 취소한 금액이 들어옵니다.

CashReceipt 객체 - approvedAt, canceledAt 필드 제거

현금영수증 발급이 승인된 시점을 나타내는 approvedAt, 현금영수증 발급을 취소한 시점을 나타내는 canceledAt이 제거되고 requestedAt으로 통일되었습니다. 현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보를 나타냅니다.

현금영수증 발급 API - 필수 파라미터로 customerIdentityNumber 필드 추가

현금영수증 발급에 사용되는 Request Body 파라미터에 개인 식별 번호로 넘겨야 하는 필수 파라미터 customerIdentityNumber가 추가되었습니다. 이전 버전인 2022-06-08까지는 registrationNumber를 사용해야 합니다.

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이 토스결제 대신 토스페이로 변경됩니다.

요청할 때는 기존 코드인 토스결제를 써도 오류가 나지 않지만 응답으로 돌아오는 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 정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.
  • virtualAccount.accountType 가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.

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

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