토스페이먼츠 제품의 새로운 기능과 변경 사항을 알아보세요.
버전 관리 및 릴리즈 정책은 API 버전 정책 페이지에서 소개합니다.
2022-11-16 버전에서는 아래 변경이 있었습니다.
한글·영문 기관 코드를 숫자 기관 코드로 대체합니다. 응답은 숫자 코드만 지원합니다. 요청은 숫자·한글·영문 코드를 지원하지만 숫자 코드 사용을 권장합니다.
카드사 필드가 발급사, 매입사 필드로 구분되었습니다. 발급사, 매입사 필드는 숫자 코드를 사용합니다.
은행 코드
- Payment 객체의
virtualAccount.bank
,transfer.bank
필드가 제거되었습니다.virtualAccount.bankCode
,transfer.bankCode
필드가 추가되었습니다. - Submall 객체, Payout 객체의
account.bank
필드가 제거되었습니다.account.bankCode
필드가 추가되었습니다. - BrandPayBankAccount 객체의
bank
필드가 제거되었습니다.bankCode
필드를 사용하세요.
카드사 코드
- Payment 객체, Billing 객체의
card.company
필드가 제거되었습니다. 카드 발급사를 가리키는card.issuerCode
필드가 추가되었습니다. 카드 매입사를 가리키는card.acquirerCode
필드가 추가되었습니다. - CardPromotion 객체의
discountCards.cardCompany
,interestFreeCards.cardCompany
필드가 제거되었습니다.discountCards.companyCode
,interestFreeCards.companyCode
필드를 사용하세요. - BrandPayCard 객체의
cardCompany
,companyCode
,issueCompany
필드가 제거되었습니다. 카드 발급사를 가리키는issuerCode
필드가 추가되었습니다. 카드 매입사를 가리키는acquirerCode
필드가 추가되었습니다. - BrandPayCardPromotion 객체의
discountCards.cardCompany
,interestFreeCards.cardCompany
,pointCards.cardCompany
필드가 제거되었습니다.discountCards.companyCode
,interestFreeCards.companyCode
,pointCards.companyCode
필드를 사용하세요.
transactionKey
필드가 제거되었습니다.lastTransactionKey
필드를 사용하세요.cancels.taxAmount
필드가 제거되었습니다.cancels.taxFreeAmount
필드를 사용하세요.card.receiptUrl
필드가 제거되었습니다.receipt.url
필드를 사용하세요.
- 브랜드페이 미동의 약관 조희 API, 약관 동의 API에
scope
필수 파라미터가 추가되었습니다. - 브랜드페이 SDK
requestAgreement()
메서드에회원가입
,카드
,계좌
파라미터가 추가되었습니다.
virtualAccountCallbackUrl
파라미터가 제거되었습니다. 가상계좌 SDK의requestPayment()
메서드, 가상계좌 발급 API에서 사용되었습니다.- 가상계좌 입금 알림은 웹훅을 사용하세요.
2022-07-27 버전에서는 현금영수증 API에 변경이 있었습니다.
이전 버전까지는 현금영수증 발급과 취소를 하나의 현금영수증 객체로 처리했지만, 2022-07-27 버전부터는 발급 요청과 취소 요청에 대한 정보를 각각 받을 수 있습니다.
- 취소 요청일 때
receiptKey
는 앞서 발급했던 현금영수증의receiptKey
에 prefix로c_
가 추가된 값으로 돌아옵니다. transactionType
으로 현금영수증 발급 요청 정보인지 취소 요청 정보인지 구분할 수 있습니다.amount
에는 요청한 현금영수증 종류에 따라 발급한 금액 혹은 취소한 금액이 들어옵니다.
현금영수증 발급이 승인된 시점을 나타내는 approvedAt
, 현금영수증 발급을 취소한 시점을 나타내는 canceledAt
이 제거되고 requestedAt
으로 통일되었습니다. 현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보를 나타냅니다.
현금영수증 발급에 사용되는 Request Body 파라미터에 소비자 인증수단으로 넘겨야 하는 필수 파라미터 customerIdentityNumber
가 추가되었습니다. 이전 버전인 2022-06-08
까지는 registrationNumber
를 사용해야 합니다.
휴대폰 결제 응답 결과로 돌아오는 mobile.carrier
가 제거되었습니다. 개인정보 보호 정책으로 인해 결제에 사용된 통신사 정보는 제공할 수 없습니다.
카드 객체에서 간편결제 결제수단 정보를 제공하던 card.provider
가 제거되었습니다. 간편결제 결제수단 정보는 객체로 변경된 easyPay
의 provider
로 대체됩니다.
간편결제를 사용해서 결제하면 Payment 객체의 method
가 간편결제(EASYPAY)
로 돌아옵니다.
easyPay
필드가 문자열에서 객체로 변경되어 아래 정보를 제공합니다.
amount
: 간편결제 서비스에 등록된 카드, 계좌 중 하나로 결제한 금액입니다.discountAmount
: 간편결제 서비스의 적립 포인트나 쿠폰 등을 사용해서 즉시 할인된 금액입니다.
간편결제 케이스 별 응답은 간편결제 응답 처리를 참고하세요.
간편결제사 코드 중 토스페이의 한글 ENUM이 토스결제
대신 토스페이
로 변경됩니다.
요청할 때는 기존 코드인 토스결제
를 써도 오류가 나지 않지만 응답으로 돌아오는 Payment.easyPay.provider
에서는 토스페이
만 돌려줍니다.
커넥트페이
제품의 이름이 브랜드페이
로 변경되어 결제 응답 객체의 Payment.type
에 CONNECTPAY
대신 BRANDPAY
가 돌아옵니다. 버전 1.4까지는 CONNECTPAY
가 돌아옵니다. 그 외 브랜드페이 마이그레이션 관련 내용은 마이그레이션 페이지를 참고하세요.
고객 계좌 송금 한도가 초과되었거나 네트워크 이슈 등으로 입금이 취소되어 발생하는 가상계좌 웹훅의 상태가 변경될 때 고객이 다시 입금해야 합니다. 이 상태를 나타내는 값이 CANCELED
에서 WAITING_FOR_DEPOSIT
으로 변경됐습니다.
즉, 같은 주문의 가상계좌 웹훅 상태가 DONE
→ WAITING_FOR_DEPOSIT
으로 변경되어 돌아올 때 다시 입금되어야 합니다.
자세한 내용은 웹훅 페이지에서 확인할 수 있습니다.
버전 1.4에서는 Payment 객체, Billing 객체, Settlement 객체에 새로운 필드가 추가되었습니다. API 필드와 결제창 SDK 파라미터의 타입 변경도 살펴보세요.
소수점이 포함되어 있는 해외 통화의 금액 정보를 지원하는 금액 정보의 타입이 정수형(integer
)에서 실수형(number
)으로 변경되었습니다.
이제 Payment 객체, Transaction 객체에서 *-amount
로 끝나는 필드, API 요청에 사용되는 금액 파라미터 모두 실수형으로 사용할 수 있습니다.
{
"mId": "tosspayments",
"version": "2022-07-27",
"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,
"taxExemptionAmount": 0.0
}
카드 번호 결제와 빌링키 발급 요청에 사용되는 Request Body 파라미터에서 카드 소유자 정보로 사용하는 customerBirthday
가 customerIdentityNumber
로 대체됩니다. 카드 소유자 정보로 생년월일과 사업자등록번호 두 가지 모두 사용할 수 있다는 것을 직관적으로 알 수 있도록 변경되었습니다.
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
가 추가되었습니다. ISO-3166의 두 자리 국가 코드를 지원합니다. 기본값은 KR
이고 requestPayment()
를 실행할 때 country
파라미터에 값을 추가하면 그 값이 반영됩니다.
Payment 객체에 결제 실패 정보를 알려주는 필드인 failure
가 추가되었습니다. 결제 승인에 실패하면 관련 에러 코드와 메시지를 아래와 같은 형태로 보여줍니다.
{
"failure": {
"code": "COMMON_ERROR",
"message": "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요."
}
}
Billing 객체에 card
필드가 추가되었습니다. 발급된 빌링키와 연결된 카드 정보가 포함되어 있습니다. cardCompany
와 cardNumber
는 사용을 권장하지 않습니다. card.company
, card.number
를 사용해주세요.
{
"mId": "tvivarepublica2",
"customerKey": "1638350476451",
"authenticatedAt": "2021-12-01T18:21:47+09:00",
"method": "카드",
"billingKey": "EyuSCFnjdiuoMhhLMvbskt_dQzt_xyrp-OZ9x0Axzxw=",
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "55317654****656*",
"cardType": "신용",
"ownerType": "법인"
}
}
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"
}
]
휴대폰 결제창에서 선택할 수 있는 통신사 종류를 제한할 때 사용하는 파라미터 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'],
})
버전 1.3에서는 Payment 객체에 세금 관련 필드 및 결제 정보를 거래 정보와 연결하는 transactionKey
가 추가되었습니다.
orderName
주문명입니다. 예를 들면생수 외 1건
같은 형식입니다.transactionKey
거래의 키 값입니다.suppliedAmount
공급가액입니다.vat
부가세입니다.cultureExpense
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.taxFreeAmount
면세 금액입니다.cancels.taxAmount
과세 처리된 금액입니다.
버전 1.2에서는 Payment 객체에 응답 버전 정보와 결제 타입, 간편결제로 결제하면 간편결제 타입을 명시하는 easyPay
필드가 추가되었습니다.
version
Payment 객체의 응답 버전입니다.type
결제 타입 정보입니다.NORMAL
(일반결제),BILLING
(자동결제),CONNECTPAY
(커넥트페이) 중 하나입니다.easyPay
간편결제 타입 정보입니다.토스페이
,페이코
,삼성페이
같은 형태입니다.
데이터가 중복되어 제거・대체된 필드들도 살펴보세요.
useDiscount
즉시 할인 여부 (discount
유무로 대체)discountAmount
즉시 할인 금액 정보 (discount.amount
로 대체)useCashReceipt
현금영수증 발급 여부 (cashReceipt
로 대체)
버전 1.1에서는 Payment 객체에 계좌이체 정보를 담은 필드 transfer
와 가상계좌 정보를 담은 객체 내부에 계좌 타입을 나타내는 accountType
이 추가되었습니다.
transfer
계좌이체로 결제했을 때 이체 정보가 담기는 객체입니다.bank
이체할 은행입니다. 은행 코드를 참고하세요.settlementStatus
정산 상태입니다. 정산이 아직 되지 않았다면INCOMPLETED
, 정산이 완료됐다면COMPLETED
값이 들어옵니다.
virtualAccount.accountType
가상계좌 타입을 나타냅니다.일반
,고정
중 하나입니다.
계좌이체를 결제수단으로 사용하거나, 가상계좌를 발급할 때 계좌 타입을 선택할 수 있는 상점에서는 응답 버전을 1.1 이상으로 설정하세요.
토스페이먼츠 제품의 새로운 기능과 변경 사항을 알아보세요.
- 결제 UI 설정이 추가됐어요.
- PC에서도 결제위젯의 모바일 뷰를 적용할 수 있어요.
- 결제위젯의 기본 패딩 값을 없앨 수 있어요.
- 가상계좌 결제에 기능이 추가됐어요.
- 상점관리자에서 가상계좌의 입금기한을 설정할 수 있어요.
- 고객의 환불 계좌 정보를 입력받을 수 있어요. 입력된 환불계좌 정보는 API 응답으로 확인하세요.
- 에스크로 지원이 추가됐어요.
- 에스크로가 계약된 상점에서는 계좌이체·가상계좌 결제에 에스크로 체크박스가 자동으로 나타나요.
- 아래 에러 코드가 추가됐어요.
NEED_AGREEMENT_WITH_REQUIRED_TERMS
,INVALID_SELECTOR
,UNAUTHORIZED_KEY
,NOT_REGISTERED_PAYMENT_WIDGET
- 여러 가지 사용성 이슈를 수정했어요.
- 카드 정보를 입력하는 키패드 버그, 같은 플로우를 두 번 이상 진행하면 정상적으로 동작하지 않는 이슈가 수정됐어요.