목차

릴리즈 노트

토스페이먼츠 제품의 새로운 기능과 변경 사항을 알아보세요.

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

API 버전 업데이트 소식
제품 업데이트 소식

API 버전 업데이트 소식

2022-11-16

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 필드를 사용하세요.

Payment 객체

  • transactionKey 필드가 제거되었습니다. lastTransactionKey 필드를 사용하세요.
  • cancels.taxAmount 필드가 제거되었습니다. cancels.taxFreeAmount 필드를 사용하세요.
  • card.receiptUrl 필드가 제거되었습니다. receipt.url 필드를 사용하세요.

브랜드페이 약관 API 및 SDK

가상계좌 API 및 SDK

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가 제거되었습니다. 간편결제 결제수단 정보는 객체로 변경된 easyPay의 provider로 대체됩니다.

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

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

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

간편결제 케이스 별 응답은 간편결제 응답 처리를 참고하세요.

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

간편결제사 코드 중 토스페이의 한글 ENUM이 토스결제 대신 토스페이로 변경됩니다.

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

ENUM - CONNECTPAY → BRANDPAY로 변경

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

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

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

즉, 같은 주문의 가상계좌 웹훅 상태가 DONE → WAITING_FOR_DEPOSIT 으로 변경되어 돌아올 때 다시 입금되어야 합니다.

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

v1.4

버전 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

}
JSON

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

카드 번호 결제와 빌링키 발급 요청에 사용되는 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 추가

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

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

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

예시
{

  "failure": {

    "code": "COMMON_ERROR",

    "message": "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요."

  }

}
JSON

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

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

Billing
{

  "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": "법인"

  }

}
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가 추가되었습니다.

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 이상으로 설정하세요.

제품 업데이트 소식

토스페이먼츠 제품의 새로운 기능과 변경 사항을 알아보세요.

2023. 3월

결제위젯

  • 결제 UI 설정이 추가됐어요.
    • PC에서도 결제위젯의 모바일 뷰를 적용할 수 있어요.
    • 결제위젯의 기본 패딩 값을 없앨 수 있어요.
  • 가상계좌 결제에 기능이 추가됐어요.
    • 상점관리자에서 가상계좌의 입금기한을 설정할 수 있어요.
    • 고객의 환불 계좌 정보를 입력받을 수 있어요. 입력된 환불계좌 정보는 API 응답으로 확인하세요.
  • 에스크로 지원이 추가됐어요.
    • 에스크로가 계약된 상점에서는 계좌이체·가상계좌 결제에 에스크로 체크박스가 자동으로 나타나요.

2023. 2월

결제위젯

  • 아래 에러 코드가 추가됐어요.
    • NEED_AGREEMENT_WITH_REQUIRED_TERMS,INVALID_SELECTOR, UNAUTHORIZED_KEY, NOT_REGISTERED_PAYMENT_WIDGET

브랜드페이

  • 여러 가지 사용성 이슈를 수정했어요.
    • 카드 정보를 입력하는 키패드 버그, 같은 플로우를 두 번 이상 진행하면 정상적으로 동작하지 않는 이슈가 수정됐어요.
  • 더 궁금한 내용이 있나요?
    자주 묻는 질문
  • 코드 샘플을 참고하세요
    TossPayments GitHub
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기