릴리즈 노트

토스페이먼츠 API와 SDK의 새로운 버전에서 사용할 수 있는 기능과 변경 사항을 알아보세요. 버전은 개발 정보 페이지에서 변경할 수 있습니다.

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 API - 결제한 국가 정보를 알려주는 필드 country 추가

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

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

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

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

Billing API - 카드 정보를 포함하는 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 API - 수수료 상세 정보를 알 수 있는 필드 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 이상으로 설정하세요.

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