토스페이먼츠 API를 이용하면 웹 표준만으로 다양한 결제 수단의 결제 연동・승인・취소・조회・인증을 구현할 수 있습니다. 현금영수증, 정산 대행 API와 같은 부가 서비스도 제공합니다.
API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.
결제와 관련한 모든 API와 결제 API 요청에 대한 응답으로 돌아오는 Payment
객체를 살펴봅니다.
결제 정보를 담고 있는 객체입니다.
결제 승인 요청에 대한 응답은 Payment
객체로 항상 동일하고, 결제 수단에 따라 객체 내 구성이 조금씩 달라집니다.
- version stringv1.2
Payment 객체의 응답 버전입니다.
- paymentKey string
결제 건에 대한 고유한 키 값입니다.
- type stringv1.2
결제 타입 정보입니다.
NORMAL
(일반 결제),BILLING
(자동 결제),CONNECTPAY
(커넥트페이) 중 하나입니다. - orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
- orderName stringv1.3
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - mId string
가맹점 ID입니다.
- currency string
결제할 때 사용한 통화 단위입니다. 원화인
KRW
만 사용합니다. - method string
결제할 때 사용한 결제 수단입니다.
카드
,가상계좌
,휴대폰
,계좌이체
,상품권(문화상품권, 도서문화상품권, 게임문화상품권)
중 하나입니다. - totalAmount number
총 결제 금액입니다.
- balanceAmount number
취소할 수 있는 금액(잔고)입니다.
- status string
결제 처리 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.
READY
- 준비됨IN_PROGRESS
- 진행중WAITING_FOR_DEPOSIT
- 가상계좌 입금 대기 중DONE
- 결제 완료됨CANCELED
- 결제가 취소됨PARTIAL_CANCELED
- 결제가 부분 취소됨ABORTED
- 카드 자동 결제 혹은 키인 결제를 할 때 결제 승인에 실패함EXPIRED
- 유효 시간(30분)이 지나 거래가 취소됨 - requestedAt string
결제 요청이 일어난 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss.SSS±hh:mm
으로 돌아옵니다.(e.g.
2022-01-01T00:00:00+09:00
) - approvedAt string
결제 승인이 일어난 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss.SSS±hh:mm
으로 돌아옵니다.(e.g.
2022-01-01T00:00:00+09:00
) - useEscrow boolean
에스크로 사용 여부입니다.
- transactionKey stringv1.3
거래 건에 대한 고유한 키 값입니다. 결제 한 건에 대한 승인 거래와 취소 거래를 구분하는데 사용됩니다.
- suppliedAmount numberv1.3
공급가액입니다.
- vat numberv1.3
부가세입니다. (결제 금액
amount
- 면세 금액taxFreeAmount
) / 11 후 소수점 첫째 자리에서 반올림해서 계산합니다.(e.g. 결제 금액이 10,000원이고, 면세 금액이 3,000원이라면 부가세는
(10000-3000)/11 = 636.3636..
을 반올림한 값 636원입니다.)더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- cultureExpense booleanv1.3
문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓, 박물관·미술관 입장권 등)
- taxFreeAmount numberv1.3
전체 결제 금액 중 면세 금액입니다. 값이
0
으로 돌아왔다면 전체 결제 금액이 과세 대상입니다.*일반 상점일 때는 모든 결제 금액이 과세에 해당하기 때문에
0
이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요. - cancels nullable · array
결제 취소 이력이 담기는 배열입니다.
- cancelAmount number
결제를 취소한 금액입니다.
- cancelReason string
결제를 취소한 이유입니다.
- taxFreeAmount number
취소된 금액 중 면세 금액입니다.
- taxAmount nullable · number
과세 처리된 금액입니다.
- refundableAmount number
결제 취소 후 환불 가능한 잔액입니다.
- canceledAt string
결제 취소가 일어난 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss±hh:mm
입니다.(e.g. 2022-01-01T00:00:00+09:00)
- cancelAmount number
- isPartialCancelable boolean
부분 취소 가능 여부입니다. 이 값이
false
이면 전액 취소만 가능합니다. - card nullable · object
카드로 결제하면 제공되는 카드 관련 정보입니다.
- company string
카드사 코드입니다.
- number string
카드번호입니다. 번호의 일부는 마스킹 되어 있습니다.
- installmentPlanMonths integer
할부 개월 수입니다. 일시불인 경우
0
입니다. - approveNo string
카드사 승인 번호입니다.
- useCardPoint boolean
카드사 포인트를 사용했는지 여부입니다.
- cardType string
카드 종류입니다.
신용
,체크
,기프트
중 하나입니다. - ownerType string
카드의 소유자 타입입니다.
개인
,법인
중 하나입니다. - receiptUrl string
카드 매출 전표를 확인할 수 있는 주소입니다.
- acquireStatus string
카드 결제의 매입 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.
READY
- 매입 대기REQUESTED
- 매입 요청됨COMPLETED
- 매입 완료CANCEL_REQUESTED
- 매입 취소 요청됨CANCELED
- 매입 취소 완료 - isInterestFree boolean
무이자 할부의 적용 여부입니다.
- interestPayer string
무이자 할부가 적용된 결제일 때 할부 수수료를 부담하는 주체에 대한 정보입니다.
BUYER
,CARD_COMPANY
,MERCHANT
중 하나입니다.BUYER
- 상품을 구매한 고객CARD_COMPANY
- 카드사MERCHANT
- 상점
- company string
- virtualAccount nullable · object
가상계좌로 결제하면 제공되는 가상계좌 관련 정보입니다.
- accountType string
가상계좌 타입을 나타냅니다.
일반
,고정
중 하나입니다. - accountNumber string
발급된 계좌번호입니다.
- bank string
가상계좌를 발급한 은행입니다.
- customerName string
가상계좌를 발급한 고객 이름입니다.
- dueDate string
입금 기한입니다.
- refundStatus string
환불처리 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.
NONE
- 해당 없음FAILED
- 환불 실패PENDING
- 환불 처리중PARTIAL_FAILED
- 부분환불 실패COMPLETED
- 환불 완료 - expired boolean
가상계좌가 만료되었는지 여부입니다.
- settlementStatus string
정산 상태입니다. 정산이 아직 되지 않았다면
INCOMPLETE
, 정산이 완료됐다면COMPLETE
값이 들어옵니다.
- accountType string
- secret nullable · string
가상계좌 웹훅 요청이 정상적인 요청인지 검증하기 위한 값입니다. 이 값이 가상계좌 웹훅 이벤트 본문으로 돌아온
secret
과 같으면 정상적인 요청입니다. - mobilePhone nullable · object
휴대폰으로 결제하면 제공되는 휴대폰 결제 관련 정보입니다.
- carrier string
휴대폰 통신사 정보입니다.
- customerMobilePhone string
결제에 사용한 휴대폰 번호입니다.
- settlementStatus string
정산 상태입니다. 정산이 아직 되지 않았다면
INCOMPLETE
, 정산이 완료됐다면COMPLETE
값이 들어옵니다. - receiptUrl string
휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다.
- carrier string
- giftCertificate nullable · object
상품권으로 결제하면 제공되는 상품권 결제 관련 정보입니다.
- approveNo string
결제 승인번호입니다.
- settlementStatus string
정산 상태입니다. 정산이 아직 되지 않았다면
INCOMPLETE
, 정산이 완료됐다면COMPLETE
값이 들어옵니다.
- approveNo string
- transfer nullable · objectv1.1
계좌이체로 결제했을 때 이체 정보가 담기는 객체입니다.
- bank string
이체할 은행입니다. 은행 코드를 참고하세요.
- settlementStatus string
정산 상태입니다. 정산이 아직 되지 않았다면
INCOMPLETE
, 정산이 완료됐다면COMPLETE
값이 들어옵니다.
- bank string
- easyPay nullable · stringv1.2
간편결제로 결제한 경우 간편결제 타입 정보입니다.
토스결제
,삼성페이
,카카오페이
,페이코
같은 형태입니다. - country stringv1.4
결제한 국가 정보입니다. ISO-3166의 두 자리 국가 코드 형식입니다.
- failure nullable · objectv1.4
결제 실패 정보입니다.
- code string
오류 타입을 보여주는 에러 코드입니다.
- message string
에러 메시지입니다. 에러 발생 이유를 알려줍니다.
- code string
- cashReceipt nullable · object
현금영수증 정보입니다.
- type string
현금영수증의 종류입니다.
소득공제
,지출증빙
중 하나의 값입니다. - amount number
현금영수증 처리된 금액입니다.
- taxFreeAmount number
면세 처리된 금액입니다.
- issueNumber string
현금영수증 발급번호입니다.
- receiptUrl string
발행된 현금영수증을 확인할 수 있는 주소입니다.
- type string
- discount nullable · object
카드사의 즉시 할인 프로모션 정보입니다. 즉시 할인 프로모션이 적용됐을 때만 생성됩니다.
- amount integer
카드사의 즉시 할인 프로모션을 적용한 금액입니다.
- amount integer
/v1/payments/{paymentKey}
paymentKey
에 해당하는 결제를 검증하고 승인합니다.
- paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.
- orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - amount 필수 · number
결제할 금액입니다.
결제 승인 요청에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제 수단 필드에 값이 제대로 들어왔는지 확인하세요.
결제 승인 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
결제 승인 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"orderId":"a4CWyWY5m89PNh7xJwhk1","amount":15000}'
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
/v1/payments/{paymentKey}
승인된 결제를 paymentKey
로 조회합니다.
- paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.
결제 조회 요청에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제 수단 필드에 값이 제대로 들어왔는지 확인하세요.
결제 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
/v1/payments/orders/{orderId}
승인된 결제를 orderId
로 조회합니다.
- orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
결제 조회 요청에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제 수단 필드에 값이 제대로 들어왔는지 확인하세요.
결제 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request GET \
--url https://api.tosspayments.com/v1/payments/orders/a4CWyWY5m89PNh7xJwhk1 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
/v1/payments/{paymentKey}/cancel
승인된 결제를 paymentKey
로 취소합니다.
- paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.
- cancelReason 필수 · string
결제를 취소하는 이유입니다.
- cancelAmount number
취소할 금액입니다. 값이 없으면 전액 취소됩니다.
- refundReceiveAccount object
결제 취소 후 금액이 환불될 계좌의 정보입니다. 가상계좌 결제에 대해서만 필수입니다. 다른 결제 수단으로 이루어진 결제를 취소할 때는 사용하지 않습니다.
- bank 필수 · string
취소 금액을 환불받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
취소 금액을 환불받을 계좌의 계좌번호 입니다.
-
없이 숫자만 넣어야 합니다. - holderName 필수 · string
취소 금액을 환불받을 계좌의 예금주 이름입니다.
- bank 필수 · string
- taxFreeAmount number
취소할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- refundableAmount number
현재 환불 가능한 금액입니다. 취소 요청을 안전하게 처리하기 위해서 사용합니다.
환불 가능한 잔액 정보가
refundableAmount
의 값과 다른 경우 해당 요청을 처리하지 않고 에러를 내보냅니다. 더 자세한 내용은 결제 취소 API 페이지에서 살펴보세요.
결제 취소 요청에 성공했다면 Payment 객체의 cancels
필드에 취소 객체가 배열로 돌아옵니다.
결제 취소 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
결제 취소 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"cancelReason":"고객 변심"}'
{
"mId": "tosspayments",
"version": "1.4",
"transactionKey": "B7103F204998813B889C77C043D09502",
"paymentKey": "2WkABYDxNyJQbgMGZzorzYWwKBG9kVl5E1em4dKva7XL9njP",
"orderId": "O-1644460169123",
"orderName": "토스 티셔츠 외 2건",
"method": "카드",
"status": "CANCELED",
"requestedAt": "2022-01-01T11:31:29+09:00",
"approvedAt": "2022-01-01T11:31:51+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "우리",
"number": "100212*****12",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://dashboard.tosspayments.com/sales-slip?transactionId=bGqvzDSq5OoimabqhwIGRNk5Ks4A%2B2pzVwKxOP0WsjnZ6FZiUqVa4RbnVeqVlxsd&ref=PX"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": [
{
"cancelReason": "고객 변심",
"canceledAt": "2022-01-01T11:32:04+09:00",
"cancelAmount": 1000,
"taxFreeAmount": 0,
"taxAmount": null,
"refundableAmount": 0
}
],
"secret": null,
"type": "NORMAL",
"easyPay": "토스결제",
"country": "KR",
"failure": null,
"currency": "KRW",
"totalAmount": 1000,
"balanceAmount": 0,
"suppliedAmount": 0,
"vat": 0,
"taxFreeAmount": 0
}
/v1/payments/key-in
결제할 카드 정보와 orderId
로 결제를 요청합니다.
- amount 필수 · integer
결제할 금액입니다.
- orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - cardNumber 필수 · string
카드 번호입니다.
- cardExpirationYear 필수 · string
카드 유효연도입니다.
- cardExpirationMonth 필수 · string
카드 유효 월입니다.
- orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - cardPassword string
카드 비밀번호 앞 두자리입니다.
- customerIdentityNumber 필수 · string
카드 소유자 정보입니다. 생년월일 6자리(
YYMMDD
) 혹은 사업자등록번호 10자리가 들어갑니다. - cardInstallmentPlan integer
할부 개월 수입니다. 할부 개월을 직접 설정하기 위해 사용합니다. 값은
2
부터12
까지 사용할 수 있습니다.0
이 들어가는 경우 할부가 아닌 일시불로 결제됩니다. - useFreeInstallmentPlan boolean
카드사 무이자 할부 적용 여부입니다. 기본값은
false
입니다.값이
true
이면 카드 정보와cardInstallmentPlan
에 지정한 할부 개월로 무이자 할부가 적용됩니다.*이 파라미터를 통해 적용된 무이자 할부 비용은 상점이 부담합니다.
- taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- customerEmail string
고객의 이메일 주소입니다. 결제결과를 알려줄 때 사용합니다.
- vbv object
해외 카드로 결제하는 경우 3DS 인증 적용을 위해 사용합니다. 3DS 인증 결과를 전송해야 하는 경우에만 필수입니다.
- cavv string
3D Secure 인증 세션에 대한 인증 값입니다.
- xid string
트랜잭션 ID 입니다.
- eci string
3DS 인증 결과에 대한 코드 값입니다.
- cavv string
카드 정보 결제 요청에 성공했다면 Payment 객체가 돌아옵니다.
카드 정보 결제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
카드 정보 결제 API에서 발생할 수 있는 에러를 살펴보세요.
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"}'
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
/v1/virtual-accounts
구매자가 원하는 은행의 가상계좌 발급을 요청합니다.
API 직접 실행해보기- amount 필수 · integer
결제할 금액입니다.
- orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - customerName 필수 · string
입금할 고객 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.
- bank 필수 · string
가상계좌를 발급할 은행입니다. 가상계좌 발급이 가능한 은행 코드를 참고하세요.
- accountType string
가상계좌 타입을 나타냅니다.
일반
,고정
중 하나입니다. 값이 없으면 일반 가상계좌로 발급됩니다.일반
- 임시적으로 발급되어 고객이 입금한 뒤에는 더 이상 사용할 수 없는 일반적인 가상계좌 타입입니다.고정
- 같은 가상계좌를 여러 번 사용해야 하는 특수한 경우를 위해 지원되는 가상계좌 타입입니다. 고정 가상계좌를 사용하는 상점으로 계약되어 있어야 사용할 수 있습니다.accountKey
파라미터와 함께 요청을 보내면 같은 계좌를 다시 발급할 수 있습니다. - accountKey string
고정 가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키값으로, 특정 고객에게 같은 가상계좌를 발급할 때 사용됩니다.
같은 가상계좌를 다시 발급하려면
accountType
을고정
으로 설정한 뒤 처음 고정 가상계좌를 발급할 때 사용했던accountKey
를 함께 넘겨주어야 합니다. - validHours integer
가상계좌가 유효한 시간을 의미합니다. 설정할 수 있는 최대값은
168
시간(7일)이고, 값을 넣지 않으면 최대값으로 설정됩니다.validHours
와dueDate
중 하나만 사용할 수 있습니다. - dueDate string
입금 기한입니다. 현재 시간을 기준으로
168
시간(7일) 이내의 특정 시점으로 입금 기한을 직접 설정하고 싶을 때 사용합니다. 그 이후 시점으로 기한을 설정하면 에러가 발생합니다.ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss
를 사용합니다.validHours
와dueDate
중 하나만 사용할 수 있습니다. - virtualAccountCallbackUrl string
가상계좌 웹훅 URL 주소입니다.
- customerEmail string
고객의 이메일 주소입니다.
- customerMobilePhone string
고객의 휴대폰 번호입니다.
- taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- useEscrow boolean
에스크로 사용 여부입니다. 값을 넣지 않으면 기본값인
false
로 설정되고 사용자가 에스크로 결제 여부를 선택합니다. - cashReceipt object
현금영수증 발급 정보를 담는 객체입니다.
- type string
현금영수증 발급 용도입니다.
소득공제
,지출증빙
,미발행
중 하나입니다.소득공제
,지출증빙
중 하나의 값을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다.미발행
을 넣으면 결제창에서 현금영수증 발급 용도를 선택할 수 없습니다. - registrationNumber string
현금영수증 신청 번호입니다.
- businessNumber string
현금영수증을 발급할 새로운 사업자등록번호입니다.
- type string
- escrowProducts array
각 상품에 대한 상세 정보를 담는 배열입니다. 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
- id 필수 · string
상품의 ID입니다. 이 값은 유니크해야 합니다.
- name 필수 · string
상품 이름입니다.
- code 필수 · string
가맹점에서 사용하는 상품 관리 코드입니다.
- unitPrice 필수 · integer
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity 필수 · integer
상품 구매 수량입니다.
- id 필수 · string
- currency string
결제할 때 사용할 통화 단위입니다. 값을 넣지 않으면 기본값은
KRW
입니다. 원화인KRW
만 사용합니다.
가상계좌 발급 요청에 성공했다면 virtualAccount
필드에 값이 있는 Payment 객체가 돌아옵니다.
가상계좌 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
가상계좌 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/virtual-accounts \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"우리"}'
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "가상계좌",
"status": "WAITING_FOR_DEPOSIT",
"requestedAt": "2021-01-20T20:12:46+09:00",
"approvedAt": "2021-01-20T20:12:47+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": {
"accountNumber": "X6505636518308",
"accountType": "일반",
"bank": "우리",
"customerName": "박토스",
"dueDate": "2021-02-05T21:05:09+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE"
},
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0
}
자동 결제 API로 고객의 결제 수단 정보를 인증하고 등록해서 가맹점이 원하는 시점에 결제할 수 있습니다.
자동 결제에 사용할 결제 수단이 인증되어 등록되었을 때 돌아오는 객체입니다.
등록된 카드 정보와 발급된 billingKey
가 포함되어 있습니다. billingKey
로 자동 결제 요청 API를 호출할 수 있습니다.
- mId string
가맹점 ID입니다.
- customerKey string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 고객에게 할당됩니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
,.
,@
로 최소 2자 이상 최대 255자 이하여야 합니다. - authenticatedAt string
자동 결제 수단이 인증된 시점의 날짜와 시간 정보입니다.
- method string
결제할 때 사용한 결제 수단으로 현재 지원하는 자동 결제 결제 수단은 카드이기 때문에
카드
로 값이 고정되어 돌아옵니다. - billingKey string
카드 정보를 대신해서 자동 결제를 요청할 때 사용되는 값입니다. 고객의 고유 ID인
customerKey
와 매칭됩니다. - card object
발급된 빌링키와 연결된 카드 정보입니다.
- company string
카드사 코드입니다.
- number string
카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다.
- cardType string
카드 종류입니다.
신용
,체크
,기프트
중 하나입니다. - ownerType string
카드의 소유자 타입입니다.
개인
,법인
중 하나입니다.
- company string
/v1/billing/authorizations/card
고객을 특정하는 customerKey
와 연결할 빌링키 발급을 요청합니다.
- customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 고객에게 할당됩니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
,.
,@
로 최소 2자 이상 최대 255자 이하여야 합니다. - cardNumber 필수 · string
카드 번호입니다.
- cardExpirationYear 필수 · string
카드 유효연도입니다.
- cardExpirationMonth 필수 · string
카드 유효 월입니다.
- cardPassword string
카드 비밀번호 앞 두자리입니다.
- customerIdentityNumber 필수 · string
카드 소유자 정보입니다. 생년월일 6자리(
YYMMDD
) 혹은 사업자등록번호 10자리가 들어갑니다. - customerName string
고객 이름입니다.
- customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다.
- vbv object
해외 카드로 결제하는 경우 3DS 인증 적용을 위해 사용합니다. 3DS 인증 결과를 전송해야 하는 경우에만 필수입니다.
- cavv string
3D Secure 인증 세션에 대한 인증 값입니다.
- xid string
트랜잭션 ID 입니다.
- eci string
3DS 인증 결과에 대한 코드 값입니다.
- cavv string
customerKey
로 카드 자동 결제 요청에 성공했다면 Billing 객체가 돌아옵니다.
customerKey
로 카드 자동 결제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request POST \
--url https://api.tosspayments.com/v1/billing/authorizations/card \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerIdentityNumber":"881212"}'
{
"mId": "tosspayments",
"customerKey": "aENcQAtPdYbTjGhtQnNVj",
"authenticatedAt": "2021-01-01T10:01:30+09:00",
"method": "카드",
"billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
"card": {
"company": "현대",
"number": "433012******1234",
"cardType": "신용",
"ownerType": "개인"
}
}
/v1/billing/authorizations/{authKey}
requestBillingAuth 호출 후 쿼리 파라미터로 돌아오는 authKey
로 빌링키 발급을 요청합니다.
- authKey 필수 · string
자동 결제 등록창 호출이 성공하면 리다이렉트 URL에 쿼리 파라미터(Query Parameter)로 포함되어 돌아오는 인증 키 값입니다.
- customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 사용자에 할당 됩니다.
authKey
로 카드 자동 결제 빌링키 발급 요청에 성공했다면 Billing 객체가 돌아옵니다.
authKey
로 카드 자동 결제 빌링키 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request POST \
--url https://api.tosspayments.com/v1/billing/authorizations/e_826EDB0730790E96F116FFF3799A65DE \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj"}'
{
"mId": "tosspayments",
"customerKey": "aENcQAtPdYbTjGhtQnNVj",
"authenticatedAt": "2020-09-25T14:38:41+09:00",
"method": "카드",
"billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
"card": {
"company": "현대",
"number": "433012******1234",
"cardType": "신용",
"ownerType": "개인"
}
}
/v1/billing/{billingKey}
발급받은 billingKey
로 카드 자동 결제 승인을 요청합니다.
- billingKey 필수 · string
발급된 빌링키 정보입니다. 고객의 결제 정보로 사용됩니다.
- amount 필수 · integer
결제할 금액입니다.
- customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 사용자에 할당 됩니다.
- orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다.
- customerName string
고객 이름입니다.
- customerMobilePhone string
고객의 휴대폰 번호입니다.
- taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- cardInstallmentPlan integer
할부 개월 수입니다. 값은
2
부터12
까지 사용할 수 있습니다.0
이 들어가는 경우 할부가 아닌 일시불로 결제됩니다. 값을 넣지 않으면 일시불입니다.
카드 자동 결제 승인 요청에 성공했다면 card
필드에 값이 있는 Payment 객체가 돌아옵니다.
카드 자동 결제 승인 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
카드 자동 결제 승인 요청 API에서 발생 가능한 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/billing/Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0= \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj","amount":4900,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 프라임 구독","customerEmail":"customer@email.com","customerName":"박토스","taxFreeAmount":0}'
{
"mId": "tosspayments",
"version": "1.4",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 프라임 구독",
"currency": "KRW",
"method": "카드",
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "BILLING",
"easyPay": null,
"country": "KR",
"failure": null,
"totalAmount": 4900,
"balanceAmount": 4900,
"suppliedAmount": 4455,
"vat": 455,
"taxFreeAmount": 0
}
거래 조회 API로 원하는 기간 동안의 거래 기록을 조회하고 대조 확인하는 작업을 할 수 있습니다.
거래 정보를 담고 있는 객체입니다.
하나의 결제(Payment
) 건에 대해 여러 번의 거래가 일어날 수 있습니다. 결제 승인, 취소, 부분 취소가 이루어질 때마다 각각의 거래 정보를 담은 Transaction
객체가 만들어지고 개별 transactionKey
를 가지게 됩니다.
거래 조회 API를 호출하면 지정한 기간 동안 생긴 모든 Transaction
객체들이 배열로 돌아옵니다.
- mId string
가맹점 ID입니다.
- transactionKey string
거래 건에 대한 고유한 키 값입니다. 결제 한 건에 대한 승인 거래와 취소 거래를 구분하는데 사용됩니다.
- paymentKey string
결제 건에 대한 고유한 키 값입니다.
- orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
- currency string
결제할 때 사용한 통화 단위입니다. 원화인
KRW
만 사용합니다. - customerKey string
가맹점에서 사용하는 고객의 고유 ID입니다.
- method string
결제할 때 사용한 결제 수단입니다.
카드
,가상계좌
,휴대폰
,계좌이체
,상품권(문화상품권, 도서문화상품권, 게임문화상품권)
중 하나입니다. - useEscrow boolean
에스크로 사용 여부입니다.
- amount number
결제한 금액입니다.
- status string
결제 처리 상태입니다.
READY
- 준비됨IN_PROGRESS
- 진행중WAITING_FOR_DEPOSIT
- 입금 대기 중DONE
- 완료됨CANCELED
- 결제가 취소됨PARTIAL_CANCELED
- 결제가 부분 취소됨ABORTED
- 카드 자동 결제 혹은 키인 결제를 할 때 결제 승인에 실패함EXPIRED
- 유효 시간(30분)이 지나 거래가 취소됨 - transactionAt string
거래가 처리된 시점의 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss±hh:mm
으로 돌아옵니다.(e.g.
2022-01-01T00:00:00+09:00
)
/v1/transactions
지정한 날짜 정보로 거래 기록을 조회합니다.
API 직접 실행해보기- startDate 필수 · string
조회를 시작하고 싶은 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'hh:mm:ss.SSS
를 사용합니다.날짜 정보만 입력하면 시간은 자동으로
00:00:00.000
으로 설정됩니다.(e.g.
2022-01-01T00:00:00.000
) - endDate 필수 · string
조회를 마치고 싶은 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'hh:mm:ss.SSS
를 사용합니다.날짜 정보만 입력하면 시간은 자동으로
00:00:00.000
으로 설정됩니다.(e.g.
2022-01-02T23:59:59.999
) - startingAfter string
특정 결제 건 이후의 기록을 조회할 때 사용합니다.
transactionKey
값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다. - limit integer
한 번에 응답받을 기록의 개수입니다. 기본값은
100
이고 설정할 수 있는 최대값은10000
입니다.
거래 조회 요청에 성공했다면 Transaction 객체가 돌아옵니다.
거래 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
거래 조회 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request GET \
--url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00.000&endDate=2022-01-10T23:59:59.999' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
[
{
"mId": "tosspayments",
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8mlwo4YQYPryQxzvNPGenpDAlBdbM",
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"currency": "KRW",
"method": "카드",
"customerKey": "cG_EdskNV1JgX7Y16S6vo",
"useEscrow": false,
"amount": 15000,
"status": "DONE",
"transactionAt": "2021-07-27T01:23:56+09:00"
},
{
"mId": "tosspayments",
"transactionKey": "2270CDE5C5F26336CE8201ED43F06FF2",
"paymentKey": "R9o5gEq4k6YZ1aOwX7K8mlwo4YQYPryQxzvNPGenpDAlBdbM",
"orderId": "eUsSmcqRzTUAnQpdXqaSu",
"currency": "KRW",
"method": "카드",
"customerKey": "cG_EdskNV1JgX7Y16S6vo",
"useEscrow": false,
"amount": 15000,
"status": "CANCELED",
"transactionAt": "2021-07-27T01:23:58+09:00"
}
]
정산 조회 API로 원하는 기간 동안의 정산 기록을 조회하고 대조 확인하는 작업을 할 수 있습니다.
정산 정보를 담고 있는 객체입니다.
- mId string
가맹점 ID입니다.
- paymentKey string
결제 건에 대한 고유한 키 값입니다.
- transactionKey string
거래 건에 대한 고유한 키 값입니다. 결제 한 건에 대한 승인 거래와 취소 거래를 구분하는데 사용됩니다.
- orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
- currency string
결제할 때 사용한 통화 단위입니다. 원화인
KRW
만 사용합니다. - method string
결제할 때 사용한 결제 수단입니다.
카드
,가상계좌
,휴대폰
,계좌이체
,상품권(문화상품권, 도서문화상품권, 게임문화상품권)
중 하나입니다. - amount number
결제한 금액입니다.
- interestFee number
할부 수수료 금액입니다.
- fees array
결제 수수료의 상세 정보입니다. 수수료 상세 정보가 담긴 객체가 배열로 들어옵니다.
- type string
수수료의 세부 타입입니다.
BASE
: 기본 수수료INSTALLMENT_DISCOUNT
: 카드사 혹은 토스페이먼츠가 부담하는 무이자 할부 수수료INSTALLMENT
: 가맹점이 부담하는 무이자 할부 수수료POINT_SAVING
: 카드사 포인트 적립에 대한 수수료ETC
: 기타 수수료 - fee number
수수료 금액입니다.
- type string
- supplyAmount number
결제 수수료의 공급가액입니다.
- vat number
결제 수수료 부가세입니다.
- payOutAmount number
지급 금액입니다. 결제 금액
amount
에서 수수료인fee
를 제외한 금액입니다. - approvedAt string
거래가 승인된 시점의 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss±hh:mm
입니다.(e.g.
2022-01-01T00:00:00+09:00
) - soldDate string
지급 금액 정산 기준일로, 결제가 일어난 날짜입니다.
yyyy-MM-dd
형식입니다.(e.g.
2022-01-01
) - paidOutDate string
정산 지급 날짜 정보입니다.
yyyy-MM-dd
형식입니다.(e.g.
2022-01-01
)
/v1/settlements
지정한 날짜 정보로 정산 기록을 조회합니다.
- startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인
yyyy-MM-dd
를 사용합니다.(e.g.
2022-01-01
) - endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. ISO 8601 형식인
yyyy-MM-dd
를 사용합니다.(e.g.
2022-01-01
) - page integer
조회할 페이지 값입니다. 최소값은
1
입니다. - size integer
한 페이지에서 응답으로 보여줄 정산 기록 개수를 의미합니다. 기본값은
100
이고 설정할 수 있는 최대값은10000
입니다.
정산 조회 요청에 성공했다면 Settlement 객체가 돌아옵니다.
정산 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
정산 조회 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request GET \
--url 'https://api.tosspayments.com/v1/settlements?startDate=2022-01-01&endDate=2022-01-10' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
[
{
"mId": "tosspayments",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"transactionKey": "8B4F646A829571D870A3011A4E13D640",
"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"
}
]
/v1/settlements
정산하고 싶은 결제 건을 paymentKey
로 특정해서 카드사에 정산을 요청합니다.
- paymentKey 필수 · string
수동 정산을 요청할 결제 건을 특정하는 키 값 입니다.
수동 정산 요청에 성공했다면 result
값이 true
로 돌아옵니다.
정산 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
수동 정산 조회 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/settlements \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"}'
{
"result": true
}
현금영수증 발급 및 취소를 위한 API입니다.
현금영수증 발급 정보를 담고 있는 객체입니다.
- orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
- orderName string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - type string
현금영수증의 종류입니다.
소득공제
,지출증빙
중 하나의 값입니다. - receiptKey string
현금영수증 발급 키입니다. 취소할 때 사용됩니다.
- approvalNumber string
현금영수증 승인번호입니다.
- approvedAt string
현금영수증이 발급된 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss±hh:mm
으로 돌아옵니다.(e.g.
2022-01-01T00:00:00.000+09:00
) - canceledAt string
현금영수증을 취소한 경우 취소 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss±hh:mm
으로 돌아옵니다.(e.g.
2022-01-01T00:00:00.000+09:00
) - receiptUrl string
발행된 현금영수증을 확인할 수 있는 주소입니다.
/v1/cash-receipts
주문 건에 대한 현금영수증 발급을 요청합니다.
API 직접 실행해보기- amount 필수 · integer
현금영수증을 발급할 금액입니다.
- orderId 필수 · string
주문 건에 대한 ID입니다. 영문 대소문자, 숫자, 특수문자
-
,_
,=
로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. - orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다. - registrationNumber 필수 · string
현금영수증 발급을 위한 개인 식별 번호입니다.
현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.
- type 필수 · string
현금영수증의 종류입니다.
소득공제
,지출증빙
중 하나의 값입니다. - taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
- businessNumber string
현금영수증을 발급할 새로운 사업자등록번호입니다.
현금영수증 발급 요청에 성공했다면 CashReceipt 객체가 돌아옵니다.
현금영수증 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
현금영수증 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/cash-receipts \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","amount":15000,"type":"소득공제","registrationNumber":"01012341234"}'
{
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"type": "소득공제",
"receiptKey": "qKl56WYb7w4vZnjEJeQVxbAdOll6d8PmOoBN0k12dzgRG9px",
"approvalNumber": "159048057",
"approvedAt": "2021-01-01T10:01:30+09:00",
"canceledAt": null,
"receiptUrl" : "https://merchants.tosspayments.com/web/serve/merchant/{{clientKey}}/cash-receipt/order/test-20100111160"
}
/v1/cash-receipts/{receiptKey}/cancel
receiptKey
를 이용해서 현금영수증 발급을 취소합니다.
요청할 때 amount
값을 따로 보내지 않으면 전액 취소됩니다.
- receiptKey 필수 · string
현금영수증의 키 값입니다.
- amount integer
현금영수증 발급을 취소할 금액입니다. 값이 따로 없으면 전액 취소됩니다.
현금영수증 취소 요청에 성공했다면 CashReceipt 객체가 돌아옵니다.
현금영수증 취소 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
현금영수증 취소 요청 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/cash-receipts/qKl56WYb7w4vZnjEJeQVxbAdOll6d8PmOoBN0k12dzgRG9px/cancel \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"orderId": "a4CWyWY5m89PNh7xJwhk1",
"orderName": "토스 티셔츠 외 2건",
"type": "소득공제",
"receiptKey": "qKl56WYb7w4vZnjEJeQVxbAdOll6d8PmOoBN0k12dzgRG9px",
"approvalNumber": "159048057",
"approvedAt": "2021-01-01T19:04:26+09:00",
"canceledAt": "2021-01-01T19:34:26+09:00",
"receiptUrl" : "https://merchants.tosspayments.com/web/serve/merchant/{{clientKey}}/cash-receipt/order/test-20100111160"
}
지급대행 API를 사용해 가맹점 하위의 서브몰 정보를 관리하고 정산된 금액을 서브몰에 지급할 수 있습니다.
지급받을 서브몰 정보를 가지고 있는 객체입니다.
정산 지급을 위해 필요한 서브몰의 계좌 정보를 포함하고 있습니다.
- subMallId string
서브몰의 ID입니다.
- type string
서브몰의 타입입니다.
CORPORATE
(법인),INDIVIDUAL
(개인) 중 하나입니다. - companyName string
서브몰의 상호명입니다.
- representativeName string
서브몰의 대표자명입니다.
- businessNumber string
서브몰의 사업자등록번호 입니다.
- account object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bank string
지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber string
계좌번호입니다.
- bank string
- metadata object
서브몰과 관련된 추가 정보를 담고 있는 객체입니다. key-value 쌍으로 이루어져 있습니다.
/v1/payouts/sub-malls
가맹점 하위에 새로운 서브몰을 등록합니다.
API 직접 실행해보기- subMallId 필수 · string
서브몰의 ID입니다.
- type 필수 · string
서브몰의 타입입니다.
CORPORATE
(법인),INDIVIDUAL
(개인) 중 하나의 값을 넣어주세요. - companyName string
서브몰의 상호명입니다.
type
이CORPORATE
일 때 필수로 보내야 하는 파라미터입니다. - representativeName string
서브몰의 대표자명입니다.
type
이CORPORATE
일 때 필수로 보내야 하는 파라미터입니다. - businessNumber string
서브몰의 사업자등록번호 입니다.
type
이CORPORATE
일 때 필수로 보내야 하는 파라미터입니다. - account 필수 · object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
계좌 번호입니다.
- bank 필수 · string
- metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 객체 안에 key-value 쌍은 여러 개 포함해서 요청할 수 있습니다. key와 value 모두 문자열 형식이어야 합니다.
서브몰 등록 요청에 성공했다면 생성된 Submall 객체가 돌아옵니다.
서브몰 등록 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
서브몰 등록 요청 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"subMallId":"testmall100","companyName":"테스트몰100","representativeName":"김토페","businessNumber":"1200220000","account":{"bank":"기업","accountNumber":"34000000000011"}}'
{
"subMallId": "testmall100",
"type": "CORPORATE",
"companyName": "테스트몰100",
"representativeName": "김토페",
"businessNumber": "1200220000",
"account": {
"bank": "기업",
"accountNumber": "00123412341234"
}
}
/v1/payouts/sub-malls
가맹점 하위에 등록되어 있는 서브몰을 조회합니다.
서브몰 조회 요청에 성공했다면 Submall 객체가 담긴 배열이 돌아옵니다.
서브몰 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payouts/sub-malls \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
[
{
"subMallId": "testmall100",
"type": "CORPORATE",
"companyName": "테스트몰100",
"representativeName": "김토페",
"businessNumber": "1200220000",
"account": {
"bank": "기업",
"accountNumber": "00123412341234"
}
},
{
"subMallId": "testmall300",
"type": "CORPORATE",
"companyName": "테스트몰300",
"representativeName": "박토스",
"businessNumber": "1200330000",
"account": {
"bank": "우리",
"accountNumber": "00123456785678"
}
}
]
/v1/payouts/sub-malls/{subMallId}
submallId
에 해당하는 서브몰의 정보를 Request Body 파라미터 값으로 수정합니다.
- subMallId 필수 · string
서브몰의 ID입니다.
- companyName string
서브몰의 상호명입니다.
- representativeName string
서브몰의 대표자명입니다.
- businessNumber string
서브몰의 사업자등록번호 입니다.
- account 필수 · object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
계좌 번호입니다.
- bank 필수 · string
- metadata object
서브몰과 관련된 추가 정보를 담고 있는 객체입니다. key-value 쌍으로 이루어져 있습니다.
서브몰 수정 요청에 성공했다면 수정된 Submall 객체가 돌아옵니다.
서브몰 수정 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"companyName":"테스트몰200","representativeName":"김토페","businessNumber":"1200220000","account":{"bank":"기업","accountNumber":"34000000000011"}}'
{
"subMallId": "testmall100",
"type": "CORPORATE",
"companyName": "테스트몰200",
"representativeName": "김토페",
"businessNumber": "1200220000",
"account": {
"bank": "기업",
"accountNumber": "00123412341234"
}
}
/v1/payouts/sub-malls/{subMallId}/delete
submallId
에 해당하는 서브몰 정보를 삭제합니다.
- subMallId 필수 · string
서브몰의 ID입니다.
서브몰 삭제 요청에 성공했다면 삭제된 서브몰 아이디가 문자열로 돌아옵니다.
서브몰 삭제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100/delete \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
testmall100
지급대행 정보를 담고 있는 객체입니다.
- payoutKey string
하나의 지급대행 건에 대한 고유한 키 값입니다.
- subMallId string
서브몰의 ID입니다.
- payoutDate string
금액이 지급될 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd
입니다. (e.g.2022-01-01
) - payoutAmount number
지급할 금액입니다.
- requestedAt string
지급대행을 요청한 날짜와 시간 정보입니다. ISO 8601 형식인
yyyy-MM-dd'T'HH:mm:ss.SSS±hh:mm
으로 돌아옵니다. (e.g.2022-01-01T00:00:00+09:00
) - status string
지급대행 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.
REQUESTED
- 지급 요청됨IN_PROGRESS
- 처리 중COMPLETED
- 지급 완료FAILED
- 지급 실패 - transferSummary string
지급대행으로 입금된 금액에 대한 세부 내용(적요)으로 서브몰 통장에 표기되는 정보입니다.
- metadata object
지급대행과 관련된 추가 정보를 담고 있는 객체입니다. key-value 쌍으로 이루어져 있습니다.
/v1/payouts/sub-malls/settlements/balance
서브몰에 정산하기 전에 가맹점에서 현재 지급할 수 있는 잔액을 먼저 조회합니다.
API 직접 실행해보기지급 가능한 잔액 조회 요청에 성공했다면 balance
필드에 잔액 정보가 담긴 객체가 돌아옵니다.
지급 가능한 잔액 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/balance \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"balance": 2000000
}
/v1/payouts/sub-malls/settlements
여러 서브몰의 지급 정보를 배열로 보내서 지급대행을 요청합니다.
API 직접 실행해보기- subMallId 필수 · string
서브몰의 ID입니다.
- payoutDate string
정산한 금액을 지급할 날짜 정보입니다. ISO 8601 형식인
yyyy-MM-dd
입니다. (e.g.2022-01-01
) - payoutAmount integer
정산할 금액입니다.
- transferSummary string
지급대행으로 정산할 금액에 대한 세부 내용(적요)으로 서브몰 통장에 표기될 정보입니다.
- metadata object
지급대행과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 객체 안에 key-value 쌍을 여러 개 포함해서 요청할 수 있습니다. key와 value 모두 문자열 형식이어야 합니다.
지급대행 요청에 성공했다면 Payout 객체가 배열에 담겨 돌아옵니다.
지급대행 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
지급대행 요청 API에서 발생할 수 있는 에러를 살펴보세요.
curl --request POST \
--url https://api.tosspayments.com/v1/payouts/sub-malls/settlements \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '[{"subMallId":"testmall100","payoutAmount":100,"payoutDate":"2022-01-03"},{"subMallId":"testmall200","payoutAmount":200,"payoutDate":"2022-01-03"}]'
[
{
"payoutKey": "FPA1000000001",
"subMallId": "testmall100",
"payoutAmount": 100,
"payoutDate": "2022-01-03",
"requestedAt": "2021-01-01T10:01:30+09:00",
"status": "REQUESTED",
"transferSummary": null,
"metadata": null
},
{
"payoutKey": "FPA1000000002",
"subMallId": "testmall200",
"payoutAmount": 200,
"payoutDate": "2022-01-03",
"requestedAt": "2021-01-01T10:01:30+09:00",
"status": "REQUESTED",
"transferSummary": null,
"metadata": null
}
]
/v1/payouts/sub-malls/settlements/{payoutKey}
payoutKey
를 Path 파라미터에 추가해서 조회하고 싶은 한 건의 지급 정보를 조회합니다.
- payoutKey 필수 · string
하나의 지급대행 건에 대한 고유한 키입니다.
지급대행 단건 조회에 성공했다면 payoutKey
에 해당하는 Payout 객체가 돌아옵니다.
지급대행 단건 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request GET \
--url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/FPA1000000001 \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"payoutKey": "FPA1000000001",
"subMallId": "testmall100",
"payoutAmount": 100,
"payoutDate": "2022-01-03",
"requestedAt": "2021-01-01T10:01:30+09:00",
"status": "REQUESTED",
"transferSummary": null,
"metadata": null
}
/v1/payouts/sub-malls/settlements
지급대행 요청에서 사용한 payoutDate
를 기준으로, 지정한 날짜 사이에 지급되었거나 지급될 예정인 지급대행 건을 조회합니다.
- startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인
yyyy-MM-dd
를 사용합니다. (e.g.2022-01-01
) - endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. ISO 8601 형식인
yyyy-MM-dd
를 사용합니다. (e.g.2022-01-01
)
지급대행 조회에 성공했다면 각 지급대행 정보를 가지고 있는 Payout 객체의 배열이 돌아옵니다.
지급대행 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request GET \
--url 'https://api.tosspayments.com/v1/payouts/sub-malls/settlements?startDate=2022-01-01&endDate=2022-01-03' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
[
{
"payoutKey": "FPA1000000001",
"subMallId": "testmall100",
"payoutAmount": 100,
"payoutDate": "2022-01-03",
"requestedAt": "2021-01-01T10:01:30+09:00",
"status": "REQUESTED",
"transferSummary": null,
"metadata": null
},
{
"payoutKey": "FPA1000000002",
"subMallId": "testmall200",
"payoutAmount": 200,
"payoutDate": "2022-01-03",
"requestedAt": "2021-01-01T10:01:30+09:00",
"status": "REQUESTED",
"transferSummary": null,
"metadata": null
}
]
카드 혜택 API로 카드사별 할인 프로모션과 할부 혜택을 조회해서 고객에게 제공할 수 있습니다.
할인 프로모션 정보와 할부 혜택 정보를 담고 있는 객체입니다.
- discountCards array
즉시 할인 이벤트 정보입니다.
- cardCompany string
카드사 코드입니다.
- minimumPaymentAmount number
할인을 적용받기 위해 결제해야 하는 최소 금액입니다.
- maximumPaymentAmount number
할인을 적용받기 위해 결제할 수 있는 최대 결제 금액입니다.
- discountCode string
즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다.
- discountAmount number
할인 예정 금액입니다.
- balance number
남은 즉시 할인 프로모션 예산 금액입니다. 값이 0이면 즉시할인 노출 및 적용하지 않아야 합니다.
- dueDate string
할인 종료 날짜 입니다.
yyyy-MM-dd
형식입니다. 해당 날짜의23:59:59
까지 행사가 유효합니다.
- cardCompany string
- interestFreeCards array
카드사별 무이자 할부 정보입니다.
- cardCompany string
카드사 코드입니다.
- dueDate string
무이자 할부 행사 종료 날짜 입니다.
yyyy-MM-dd
형식입니다. 해당 날짜의23:59:59
까지 행사가 유효합니다. - installmentFreeMonths array
무이자 할부가 가능한 개월 수가 배열로 표시됩니다.
- minimumPaymentAmount number
해당 무이자 할부가 적용될 수 있는 최소 결제 금액 입니다.
- cardCompany string
/v1/promotions/card
카드사별 할인 프로모션, 할부 혜택 정보를 조회합니다.
API 직접 실행해보기- payType string
결제 타입 입니다.
NORMAL
(일반 결제),CONNECTPAY
(커넥트페이) 중 하나입니다. 일반 결제 연동에서는CONNECTPAY
를 사용하지 않습니다. 값이 없으면 기본 값은NORMAL
입니다.
카드 혜택 조회 요청에 성공했다면 CardPromotion 객체가 돌아옵니다.
카드 혜택 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.
curl --request GET \
--url https://api.tosspayments.com/v1/promotions/card \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
{
"discountCards": [
{
"cardCompany": "현대",
"discountAmount": 1000,
"balance": 100000,
"discountCode": "001",
"dueDate": "2021-12-31",
"maximumPaymentAmount": 50000,
"minimumPaymentAmount": 10000
},
{
"cardCompany": "롯데",
"discountAmount": 1000,
"balance": 100000,
"discountCode": "002",
"dueDate": "2021-12-31",
"maximumPaymentAmount": 50000,
"minimumPaymentAmount": 10000
}
],
"interestFreeCards": [
{
"cardCompany": "국민",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "BC",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "우리",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "전북",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "씨티",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "신한",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "광주",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "롯데",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4],
"minimumPaymentAmount": 50000
},
{
"cardCompany": "농협",
"dueDate": "2021-12-31",
"installmentFreeMonths": [2, 3, 4, 5, 6],
"minimumPaymentAmount": 50000
}
]
}