API 목록 | 토스페이먼츠 결제 연동 문서

토스페이먼츠 API를 이용하면 웹 표준만으로 다양한 결제수단의 결제 연동・승인・취소・조회・인증을 구현할 수 있습니다. 현금영수증, 정산대행 API와 같은 부가서비스도 제공합니다. API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요.

결제

결제와 관련한 모든 API와 결제 API 요청에 대한 응답으로 돌아오는 Payment 객체를 살펴봅니다.

Payment 객체

결제정보를 담고있는 객체입니다.

결제승인 요청에 대한 응답은 Payment 객체로 항상 동일하고, 결제수단에 따라 객체 내 구성이 조금씩 달라집니다.

객체 상세

version string
Payment 객체의 응답 버전입니다.
paymentKey string
결제 건에 대한 고유한 키 값입니다.
type string
결제 타입 정보입니다. NORMAL(일반결제), BILLING(자동결제), CONNECTPAY(커넥트페이) 중 하나입니다.
easyPay string
간편결제로 결제한 경우 간편결제 타입 정보입니다. 토스결제, 페이코, 삼성페이 같은 형태입니다.
orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
orderName string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
mId string
가맹점 ID입니다.
currency string
결제할 때 사용한 통화 단위입니다. 원화인 KRW만 사용합니다.
method string
결제할 때 사용한 결제수단입니다. 카드, 가상계좌, 휴대폰, 계좌이체, 상품권(문화상품권, 도서문화상품권, 게임문화상품권) 중 하나입니다.
totalAmount integer
총 결제금액입니다.
balanceAmount integer
취소할 수 있는 금액(잔고)입니다.
status string
결제 처리 상태입니다. 아래와 같은 상태값을 가질 수 있습니다.
READY - 준비됨
IN_PROGRESS - 진행중
WAITING_FOR_DEPOSIT - 가상계좌 입금 대기 중
DONE - 결제 완료됨
CANCELED - 결제가 취소됨
PARTIAL_CANCELED - 결제가 부분 취소됨
ABORTED - 카드 자동결제 혹은 키인 결제를 할 때 결제승인에 실패함
EXPIRED - 유효 시간(30분)이 지나 거래가 취소됨
requestedAt string
결제요청이 일어난 날짜와 시간정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00 으로 돌아옵니다.
(e.g. 2021-01-01T00:00:00+09:00)
approvedAt nullable · string
결제승인이 일어난 날짜와 시간정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00 으로 돌아옵니다.
(e.g. 2021-01-01T00:00:00+09:00)
discount nullable · object
카드사의 즉시 할인 프로모션 정보입니다. 즉시 할인 프로모션이 적용됐을 때(useDiscount가 true인 경우)만 생성됩니다.
- amount integer
  카드사의 즉시 할인 프로모션을 적용한 금액입니다.
useEscrow boolean
에스크로 사용 여부입니다.
cancels array
결제취소 이력이 담기는 배열입니다.
- cancelAmount integer
  결제를 취소한 금액입니다.
- cancelReason string
  결제를 취소한 이유입니다.
- taxFreeAmount integer
  면세 처리된 금액입니다.
- taxAmount nullable · integer
  과세 처리된 금액입니다.
- refundableAmount integer
  결제취소 후 환불 가능한 잔액입니다.
- canceledAt string
  결제취소가 일어난 날짜와 시간정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00입니다.
  (e.g. 2021-01-01T00:00:00+09:00)
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
  무이자 할부의 적용 여부입니다.
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 값이 들어옵니다.
secret nullable · string
가상계좌로 결제할 때 전달되는 입금 콜백을 검증하기 위한 값입니다.
mobilePhone nullable · object
휴대폰으로 결제하면 제공되는 휴대폰 결제 관련 정보입니다.
- carrier string
  휴대폰 통신사 정보입니다.
- customerMobilePhone string
  결제에 사용한 휴대폰 번호입니다.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETE, 정산이 완료됐다면 COMPLETE 값이 들어옵니다.
giftCertificate nullable · object
상품권으로 결제하면 제공되는 상품권 결제 관련 정보입니다.
- approveNo string
  결제 승인번호입니다.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETE, 정산이 완료됐다면 COMPLETE 값이 들어옵니다.
transfer nullable · object
계좌이체로 결제했을 때 이체 정보가 담기는 객체입니다.
- bank string
  이체할 은행입니다. 은행 코드를 참고하세요.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETE, 정산이 완료됐다면 COMPLETE 값이 들어옵니다.
cashReceipt nullable · object
현금영수증 정보입니다.
- type string
  현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나의 값입니다.
- amount integer
  현금영수증 처리된 금액입니다.
- taxFreeAmount integer
  면세 처리된 금액입니다.
- issueNumber string
  현금영수증 발급번호입니다.
- receiptUrl string
  현금영수증 조회 페이지 주소입니다.
transactionKey string
거래 건에 대한 고유한 키 값입니다.
suppliedAmount integer
공급가액입니다.
vat integer
부가세입니다.
cultureExpense boolean
문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓 박물관/미술관 입장권 등)

결제승인

POST /v1/payments/{paymentKey}

paymentKey에 해당하는 결제를 검증하고 승인합니다.

API 직접 실행해보기

Path 파라미터

paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.

Request Body 파라미터

orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
amount 필수 · integer
결제할 금액입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6 \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"orderId":"a4CWyWY5m89PNh7xJwhk1","amount":15000}'

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "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,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null
}

paymentKey로 결제조회

GET /v1/payments/{paymentKey}

승인된 결제를 paymentKey로 조회합니다.

API 직접 실행해보기

Path 파라미터

paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.

요청

curl --request get \
  --url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6 \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "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,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null
}

orderId로 결제조회

GET /v1/payments/orders/{orderId}

승인된 결제를 orderId로 조회합니다.

API 직접 실행해보기

Path 파라미터

orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

요청

curl --request get \
  --url https://api.tosspayments.com/v1/payments/orders/a4CWyWY5m89PNh7xJwhk1 \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "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,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null
}

결제취소

POST /v1/payments/{paymentKey}/cancel

승인된 결제를 paymentKey로 취소할 수 있습니다.

API 직접 실행해보기

Path 파라미터

paymentKey 필수 · string
결제 건에 대한 고유한 키값입니다.

Request Body 파라미터

cancelReason 필수 · string
결제를 취소하는 이유입니다.
cancelAmount integer
취소할 금액입니다. 값이 없으면 전액취소됩니다.
refundReceiveAccount object
결제취소 이후 금액이 환불될 계좌의 정보입니다. 가상계좌 결제에 대해서만 필수입니다. 다른 결제수단으로 이루어진 결제를 취소할 때는 사용하지 않습니다.
- bank 필수 · string
  취소 금액을 환불받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
  취소 금액을 환불받을 계좌의 계좌번호 입니다. - 없이 숫자만 넣어야 합니다.
- holderName 필수 · string
  취소 금액을 환불받을 계좌의 예금주 이름입니다.
taxAmount integer
과세금액입니다. 값이 없으면 전액 과세로 판단합니다.
taxFreeAmount integer
면세금액입니다.
refundableAmount integer
현재 환불 가능한 금액입니다. 취소 요청을 안전하게 처리하기 위해서 사용합니다.
환불 가능한 잔액 정보가 refundableAmount의 값과 다른 경우 해당 요청을 처리하지 않고 에러를 내보냅니다. 더 자세한 내용은 결제취소 API 페이지에서 살펴보세요.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/cancel \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"cancelReason":"고객 변심으로 취소","cancelAmount":5000}'

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "transactionKey": "3BF97231E8C97D6CB8942ABA48D90D95",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 10000,
  "suppliedAmount": 9091,
  "vat": 909,
  "status": "PARTIAL_CANCELED",
  "requestedAt": "2021-01-01T10:41:35+09:00",
  "approvedAt": "2021-01-01T10:44:40+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": [
    {
      "cancelAmount": 5000,
      "cancelReason": "고객 변심",
      "taxFreeAmount": 0,
      "refundableAmount": 10000,
      "canceledAt": "2021-01-01T11:50:00+09:00"
    }
  ],
  "secret": null,
  "type": "NORMAL",
  "easyPay": null
}

카드정보 결제

POST /v1/payments/key-in

결제할 카드정보와 orderId로 결제를 요청합니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
cardNumber 필수 · string
카드 번호입니다.
cardExpirationYear 필수 · string
카드 유효연도입니다.
cardExpirationMonth 필수 · string
카드 유효 월입니다.
orderName string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
cardPassword string
카드 비밀번호 앞 두자리입니다.
customerBirthday string
카드 소유자의 생년월일 6자리(YYMMDD)입니다. 사업자인 경우 사업자등록번호 10자리가 들어갑니다.
cardInstallmentPlan integer
할부 개월 수입니다. 값이 있으면 할부 개월 수가 고정된 상태로 결제창이 열립니다. 값은 2부터 12까지 사용할 수 있습니다.
0 이 들어가는 경우 할부가 아닌 일시불로 결제됩니다. 값을 따로 넣지 않으면 결제창에서 전체 할부 개월 수를 선택할 수 있습니다.
taxFreeAmount integer
면세금액입니다.
customerEmail string
고객의 이메일주소입니다. 결제결과를 알려줄 때 사용합니다.
vbv object
해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용합니다. 3DS 인증 결과를 전송해야 하는 경우에만 필수입니다.
- cavv 필수 · string
  3D Secure 인증 세션에 대한 인증 값입니다.
- xid 필수 · string
  트랜잭션 ID 입니다.
- eci 필수 · string
  3DS 인증 결과에 대한 코드 값입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payments/key-in \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerBirthday":"881212"}'

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "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,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null
}

가상계좌 발급 요청

POST /v1/virtual-accounts

가상계좌 발급 API로 원하는 은행의 가상계좌를 발급받을 수 있습니다.

고정 가상계좌를 발급하려면 가상계좌 발급 API에 원하는 은행 코드명과 주문정보와 함께 accountType과 accountKey를 추가합니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
customerName 필수 · string
입금할 고객 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.
bank 필수 · string
가상계좌를 발급할 은행입니다. 가상계좌 발급이 가능한 은행 코드를 참고하세요.
accountType string
가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.
accountKey string
고정 가상계좌 발급을 위해 필요한 고유한 키값입니다.
validHours integer
가상계좌가 유효한 시간을 의미합니다. 기본값은 72(3일)입니다. 72 이상의 값이 들어가는 경우 에러가 발생합니다.
validHours와 dueDate 중 하나만 사용해야 합니다.
virtualAccountCallbackUrl string
입금완료 콜백 URL 주소입니다.
customerEmail string
고객의 이메일주소입니다.
customerMobilePhone string
고객의 휴대폰 번호입니다.
taxFreeAmount integer
면세금액입니다. 없을 경우 0으로 지정됩니다.
useEscrow boolean
에스크로 사용 여부입니다. 값을 주지 않으면 사용자가 에스크로 결제 여부를 선택합니다. 기본값은 false 입니다.
cashReceipt object
현금영수증 발급정보를 담는 객체입니다.
- type string
  현금영수증의 종류입니다. 미발급, 소득공제, 지출증빙 중 하나입니다. 값이 있으면 결제창에 현금영수증이 입력된 채 열립니다.
- registrationNumber string
  현금영수증 신청 번호입니다.
- registrationNumberType string
  현금영수증 신청 번호 종류입니다. 휴대폰번호, 사업자등록번호, 현금영수증카드 중 하나입니다.
- businessNumber string
  현금영수증을 발급할 새로운 사업자등록번호입니다.
escrowProducts array
각 상품에 대한 상세 정보를 담는 배열입니다. 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
- id 필수 · string
  상품의 ID입니다. 이 값은 유니크해야 합니다.
- name 필수 · string
  상품 이름입니다.
- code 필수 · string
  가맹점에서 사용하는 상품 관리 코드입니다.
- unitPrice 필수 · integer
  상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity 필수 · integer
  상품 구매 수량입니다.
currency string
결제할 때 사용할 통화 단위입니다. 값이 없으면 기본 값은 KRW입니다. 원화인 KRW만 사용합니다.
dueDate string
입금 만료 시간입니다. 현재시간을 기준으로 3일 미만으로 만료시간을 직접 설정하고 싶은 경우 사용합니다. 3일 이상의 시간을 지정하는 경우 에러가 발생합니다.
ISO 8601 형식인 YYYY-MM-DDThh:mm:ss를 사용합니다.
validHours와 dueDate 중 하나만 사용해야 합니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/virtual-accounts \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"우리"}'

응답

{
    "mId": "tosspayments",
    "version": "1.3",
    "paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
    "orderId": "a4CWyWY5m89PNh7xJwhk1",
    "orderName": "토스 티셔츠 외 2건",
    "currency": "KRW",
    "method": "가상계좌",
    "totalAmount": 15000,
    "balanceAmount": 15000,
    "suppliedAmount": 13636,
    "vat": 1364,
    "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,
    "cashReceipt": null,
    "discount": null,
    "cancels": null,
    "secret": null,
    "useDiscount": false,
    "type": "NORMAL",
    "easyPay": null
}

customerKey로 카드 자동결제 빌링키 발급 요청

POST /v1/billing/authorizations/card

customerKey를 이용해서 빌링키를 발급 받을 수 있습니다.

API 직접 실행해보기

Request Body 파라미터

customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 고객에게 할당됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 최소 2자 이상 최대 255자 이하여야 합니다.
cardNumber 필수 · string
카드 번호입니다.
cardExpirationYear 필수 · string
카드 유효연도입니다.
cardExpirationMonth 필수 · string
카드 유효 월입니다.
cardPassword string
카드 비밀번호 앞 두자리입니다.
customerBirthday 필수 · string
카드 소유자의 생년월일 6자리(YYMMDD)입니다. 사업자인 경우 사업자등록번호 10자리가 들어갑니다.
customerName string
고객 이름입니다.
customerEmail string
고객의 이메일주소입니다. 결제 결과를 알려줄 때 사용합니다.
vbv object
해외카드로 결제하는 경우 3DS 인증 적용을 위해 사용합니다. 3DS 인증 결과를 전송해야 하는 경우에만 필수입니다.
- cavv 필수 · string
  3D Secure 인증 세션에 대한 인증 값입니다.
- xid 필수 · string
  트랜잭션 ID 입니다.
- eci 필수 · string
  3DS 인증 결과에 대한 코드 값입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/billing/authorizations/card \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerBirthday":"881212"}'

응답

{
  "mId": "tosspayments",
  "customerKey": "aENcQAtPdYbTjGhtQnNVj",
  "authenticatedAt": "2021-01-01T10:01:30+09:00",
  "method": "카드",
  "billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
  "cardCompany": "현대",
  "cardNumber": "433012******1234"
}

authKey로 카드 자동결제 빌링키 발급 요청

POST /v1/billing/authorizations/{authKey}

authKey를 이용해서 빌링키를 발급 받을 수 있는 API입니다.

자동결제 등록창 호출(requestBillingAuth) 결과로 얻은 authKey를 사용합니다.

API 직접 실행해보기

Path 파라미터

authKey 필수 · string
자동결제 등록창 호출이 성공하면 리다이렉트 URL에 쿼리 파라미터(Query Parameter)로 포함되어 돌아오는 인증 키 값입니다.

Request Body 파라미터

customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 사용자에 할당 됩니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/billing/authorizations/e_826EDB0730790E96F116FFF3799A65DE \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --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=",
  "cardCompany": "현대",
  "cardNumber": "433012******1234"
}

카드 자동결제 승인요청

POST /v1/billing/{billingKey}

발급받은 billingKey로 카드 자동결제 승인을 요청합니다.

API 직접 실행해보기

Path 파라미터

billingKey 필수 · string
발급된 빌링키 정보입니다. 고객의 결제정보로 사용됩니다.

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
customerKey 필수 · string
가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 사용자에 할당 됩니다.
orderId 필수 · string
가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
customerEmail string
고객의 이메일주소입니다. 결제 결과를 알려줄 때 사용합니다.
customerName string
고객 이름입니다.
customerMobilePhone string
고객의 휴대폰 번호입니다.
taxFreeAmount integer
면세금액입니다.
cardInstallmentPlan integer
할부 개월 수입니다. 값은 2부터 12까지 사용할 수 있습니다. 0 이 들어가는 경우 할부가 아닌 일시불로 결제됩니다. 값을 따로 넣지 않으면 일시불입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/billing/Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0= \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj","amount":4900,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 프라임 구독","customerEmail":"customer@email.com","customerName":"박토스","taxFreeAmount":0}'

응답

{
  "mId": "tosspayments",
  "version": "1.3",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 프라임 구독",
  "currency": "KRW",
  "method": "카드",
  "totalAmount": 4900,
  "balanceAmount": 4900,
  "suppliedAmount": 4455,
  "vat": 455,
  "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,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BILLING",
  "easyPay": null
}

거래

거래조회 API로 원하는 기간 동안의 거래기록을 조회하고 대조 확인하는 작업을 할 수 있습니다.

Transaction 객체

거래정보를 담고있는 객체입니다.

하나의 결제(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 integer
결제한 금액입니다.
status string
결제 처리 상태입니다.
READY - 준비됨
IN_PROGRESS - 진행중
WAITING_FOR_DEPOSIT - 입금 대기 중
DONE - 완료됨
CANCELED - 결제가 취소됨
PARTIAL_CANCELED - 결제가 부분 취소됨
ABORTED - 카드 자동결제 혹은 키인 결제를 할 때 결제승인에 실패함
EXPIRED - 유효 시간(30분)이 지나 거래가 취소됨
transactionAt string
거래가 처리된 시점의 날짜와 시간 정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00 으로 돌아옵니다.
(e.g. 2021-01-01T00:00:00+09:00)

거래조회

GET /v1/transactions

특정 날짜에 일어난 거래기록을 조회합니다. 요청에 성공하면 거래 처리 정보를 담은 객체인 Transaction 객체가 담긴 배열이 응답으로 돌아옵니다.

API 직접 실행해보기

Query 파라미터

startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 YYYY-MM-DD를 사용합니다. 시간은 자동으로 00:00:00 으로 설정됩니다.
(e.g. 2021-01-01)
endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. ISO 8601 형식인 YYYY-MM-DD를 사용합니다. 시간은 자동으로 00:00:00 으로 설정됩니다.
(e.g. 2021-01-01)
startingAfter string
특정 결제 건 이후의 기록을 조회할 때 사용합니다. transactionKey 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다.
limit integer
한 번에 응답받을 기록의 개수입니다. 기본값은 100이고 설정할 수 있는 최대값은 10000입니다.

요청

curl --request get \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2021-08-16&endDate=2021-08-16' \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

[
  {
    "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로 원하는 기간 동안의 정산기록을 조회하고 대조 확인하는 작업을 할 수 있습니다.

Settlement 객체

정산 정보를 담고있는 객체입니다.

하나의 결제 건을 기준으로 정산 정보를 담고 있어 paymentKey로 결제 기록과 연결됩니다.

객체 상세

mId string
가맹점 ID입니다.
paymentKey string
결제 건에 대한 고유한 키 값입니다.
orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
currency string
결제할 때 사용한 통화 단위입니다. 원화인 KRW만 사용합니다.
method string
결제할 때 사용한 결제수단입니다. 카드, 가상계좌, 휴대폰, 계좌이체, 상품권(문화상품권, 도서문화상품권, 게임문화상품권) 중 하나입니다.
amount integer
결제한 금액입니다.
interestFee integer
할부 수수료 금액입니다.
fee integer
결제 수수료 금액입니다.
supplyAmount integer
결제 수수료의 공급가액입니다.
vat integer
결제 수수료 부가세입니다.
payOutAmount integer
지급 금액입니다. 결제금액 amount 에서 수수료인 fee를 제외한 금액입니다.
approvedAt string
거래가 승인된 시점의 날짜와 시간정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00입니다.
(e.g. 2021-01-01T00:00:00+09:00)
soldDate string
매출이 생긴 날짜 정보입니다. YYYY-MM-DD 형식입니다.
(e.g. 2021-01-01)
paidOutDate string
정산 지급 날짜 정보입니다. YYYY-MM-DD형식입니다.
(e.g. 2021-01-01)

정산조회

GET /v1/settlements

지정한 날짜 정보로 정산기록을 조회합니다. 요청이 성공하면 정산 정보를 담은 객체인 Settlement 의 배열이 응답으로 돌아옵니다.

Query 파라미터

startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 YYYY-MM-DD를 사용합니다. 시간은 자동으로 00:00:00 으로 설정됩니다.
(e.g. 2021-01-01)
endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. ISO 8601 형식인 YYYY-MM-DD를 사용합니다. 시간은 자동으로 00:00:00 으로 설정됩니다.
(e.g. 2021-01-01)
page integer
조회할 페이지 값입니다. 최소값은 1입니다.
size integer
한 페이지에서 응답으로 보여줄 정산기록 개수를 의미합니다. 기본값은 100이고 설정할 수 있는 최대값은 10000입니다.

요청

curl --request get \
  --url 'https://api.tosspayments.com/v1/settlements?startDate=2021-01-01&endDate=2021-01-10' \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

[
    {
        "mId": "tosspayments",
        "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
        "orderId": "a4CWyWY5m89PNh7xJwhk1",
        "currency": "KRW",
        "method": "카드",
        "amount": 34000,
        "interestFee": 0,
        "fee": 860,
        "supplyAmount": 782,
        "vat": 78,
        "payOutAmount": 33140,
        "approvedAt": "2021-01-02T12:30:09+09:00",
        "soldDate": "2021-01-02",
        "paidOutDate": "2021-01-04"
    }
]

수동 정산 요청

POST /v1/settlements

카드 결제 승인정보를 수동으로 카드사에 전송하는 방식으로 정산합니다. 요청에 성공하면 HTTP 200 OK 응답과 함께 빈 본문이 돌아옵니다.

API 직접 실행해보기

Request Body 파라미터

paymentKey 필수 · string
조회할 결제 건에 대한 키 값 입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/settlements \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"}'

응답

현금영수증

현금영수증 발급 및 취소를 위한 API입니다.

CashReceipt 객체

현금영수증 발급정보를 담고 있는 객체입니다.

객체 상세

orderId string
가맹점에서 주문건에 대해 발급한 고유 ID입니다.
orderName string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
type string
현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나의 값입니다.
receiptKey string
현금영수증 발급 키입니다. 취소할 때 사용됩니다.
approvalNumber string
현금영수증 승인번호입니다.
approvedAt string
현금영수증이 발급된 날짜와 시간 정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00으로 돌아옵니다.
(e.g. 2021-01-01T00:00:00+09:00)
canceledAt string
현금영수증을 취소한 경우 취소 날짜와 시간 정보입니다. ISO 8601 형식인 YYYY-MM-DDThh:mm:ss+00:00 으로 돌아옵니다.
(e.g. 2021-01-01T00:00:00+09:00)
receiptUrl string
발행된 현금영수증을 확인할 수 있는 URL 입니다.

현금영수증 발급

POST /v1/cash-receipts

현금영수증 발급을 요청합니다. receiptKey를 돌려 받습니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
현금영수증을 발급할 금액입니다.
orderId 필수 · string
주문 건에 대한 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.
registrationNumber 필수 · string
현금영수증 발급을 위한 개인 식별 번호입니다.
현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.
type 필수 · string
현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나의 값입니다.
taxFreeAmount integer
면세금액입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/cash-receipts \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --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"
}

현금영수증 취소

POST /v1/cash-receipts/{receiptKey}/cancel

receiptKey를 이용해서 현금영수증 발급을 취소합니다. canceledAt 필드에 취소한 날짜 정보가 추가되어 돌아옵니다.

요청할 때 amount 값을 따로 보내지 않으면 전액 취소됩니다.

API 직접 실행해보기

Path 파라미터

receiptKey 필수 · string
현금영수증의 키 값입니다.

Request Body 파라미터

amount integer
현금영수증 발급을 취소할 금액입니다. 값이 따로 없으면 전액취소됩니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/cash-receipts/qKl56WYb7w4vZnjEJeQVxbAdOll6d8PmOoBN0k12dzgRG9px/cancel \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

{
    "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로 가맹점 하위의 서브몰 정보를 관리하고 지급대행을 할 수 있습니다.

* 지급대행 API 테스트는 추후 업데이트 예정입니다.

Submall 객체

지급받을 서브몰 정보를 가지고 있는 객체입니다.

정산 지급을 위해 필요한 서브몰의 계좌 정보를 포함하고 있습니다.

객체 상세

subMallId string
서브몰의 ID입니다.
companyName string
서브몰의 상호명입니다.
representativeName string
서브몰의 대표자명입니다.
businessNumber string
서브몰의 사업자등록번호 입니다.
account object
서브몰에서 정산금액을 지급 받을 계좌정보를 담은 객체입니다.
- bank string
  지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber string
  계좌번호입니다.

서브몰 조회

GET /v1/payouts/sub-malls

가맹점 하위의 서브몰 목록을 배열이 돌아옵니다. 서브몰 정보와 지급 계좌 정보를 알 수 있습니다.

요청

curl --request get \
  --url https://api.tosspayments.com/v1/payouts/sub-malls \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

[
  {
    "subMallId": "testmall100",
    "companyName": "테스트몰100",
    "representativeName": "김토페",
    "businessNumber": "1200220000",
    "account": {
        "bank": "기업",
        "accountNumber": "00123412341234",
        "holderName": "김토페"
    }
  }
]

서브몰 등록

POST /v1/payouts/sub-malls

가맹점 하위에 새로운 서브몰을 등록합니다.

Request Body 파라미터

subMallId 필수 · string
서브몰 ID입니다.
companyName 필수 · string
서브몰의 상호명입니다.
representativeName 필수 · string
서브몰의 대표자명입니다.
businessNumber 필수 · string
서브몰의 사업자등록번호 입니다.
account 필수 · object
서브몰에서 정산금액을 지급 받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
  지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
  계좌 번호입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payouts/sub-malls \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"subMallId":"testmall100","companyName":"테스트몰100","representativeName":"김토페","businessNumber":"1200220000","account":{"bank":"기업","accountNumber":"34000000000011"}}'

응답

[
  {
    "subMallId": "testmall100",
    "companyName": "테스트몰100",
    "representativeName": "김토페",
    "businessNumber": "1200220000",
    "account": {
        "bank": "기업",
        "accountNumber": "00123412341234",
        "holderName": "김토페"
    }
  }
]

서브몰 수정

POST /v1/payouts/sub-malls/{subMallId}

서브몰 아이디를 사용해서 해당 서브몰의 정보를 수정할 수 있습니다. 요청이 성공하면 수정된 서브몰 정보가 응답으로 돌아옵니다.

Path 파라미터

subMallId 필수 · string
서브몰의 ID입니다.

Request Body 파라미터

companyName 필수 · string
서브몰의 상호명입니다.
representativeName 필수 · string
서브몰의 대표자명입니다.
businessNumber 필수 · string
서브몰의 사업자등록번호 입니다.
account 필수 · object
서브몰에서 정산금액을 지급 받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
  지급받을 계좌의 은행 코드입니다. 은행 코드를 참고하세요.
- accountNumber 필수 · string
  계좌 번호입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100 \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"companyName":"테스트몰200","representativeName":"김토페","businessNumber":"1200220000","account":{"bank":"기업","accountNumber":"34000000000011"}}'

응답

{
    "subMallId": "testmall100",
    "companyName": "테스트몰200",
    "representativeName": "김토페",
    "businessNumber": "1200220000",
    "account": {
        "bank": "기업",
        "accountNumber": "00123412341234",
        "holderName": "김토페"
    }
}

서브몰 삭제

POST /v1/payouts/sub-malls/{subMallId}/delete

서브몰을 삭제합니다. 요청이 성공하면 삭제된 서브몰 아이디가 응답으로 돌아옵니다.

Path 파라미터

subMallId 필수 · string
서브몰의 ID입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100/delete \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

testmall100

지급가능한 잔액조회

GET /v1/payouts/sub-malls/settlements/balance

서브몰에 정산하기 전에 가맹점에서 현재 지급할 수 있는 잔액을 조회합니다.

요청

curl --request get \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/balance \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

{
  "balance": 2000000
}

지급대행 요청

POST /v1/payouts/sub-malls/settlements

서브몰에 지급할 액수와 날짜 정보로 지급을 요청합니다.

요청 본문은 정보를 담은 객체를 배열로 감싸서 보내야 합니다.

Request Body 파라미터

subMallId 필수 · string
서브몰의 상호명입니다.
payoutDate 필수 · string
정산한 금액을 지급할 날짜 정보입니다.
payoutAmount integer
정산할 금액입니다.

요청

curl --request post \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/settlements \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==' \
  --header 'Content-Type: application/json' \
  --data '{"subMallId":"testmall100","payoutAmount":100,"payoutDate":"2021-01-03"}'

응답

카드혜택

카드혜택 API로 카드사별 할인 프로모션과 할부 혜택을 조회해서 고객에게 제공할 수 있습니다.

CardPromotion 객체

할인 프로모션 정보와 할부 혜택 정보를 담고 있는 객체입니다.

객체 상세

discountCards array
즉시 할인 이벤트 정보입니다.
- cardCompany string
  카드사 코드입니다.
- minimumPaymentAmount integer
  할인을 적용받기 위해 결제해야 하는 최소 금액입니다.
- maximumPaymentAmount integer
  할인을 적용받기 위해 결제할 수 있는 최대 결제금액입니다.
- discountCode string
  즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다.
- discountAmount integer
  할인 예정 금액입니다.
- balance integer
  남은 즉시 할인 프로모션 예산 금액입니다. 값이 0이면 즉시할인 노출 및 적용하지 않아야 합니다.
- dueDate string
  할인 종료 날짜 입니다. YYYY-MM-DD 형식입니다. 해당 날짜의 23:59:59까지 행사가 유효합니다.
interestFreeCards array
카드사 별 무이자 할부 정보입니다.
- cardCompany string
  카드사 코드입니다.
- dueDate string
  무이자 할부 행사 종료 날짜 입니다. YYYY-MM-DD 형식입니다. 해당 날짜의 23:59:59까지 행사가 유효합니다.
- installmentFreeMonths array
  무이자 할부가 가능한 개월 수가 배열로 표시 됩니다.
- minimumPaymentAmount integer
  해당 무이자 할부가 적용될 수 있는 최소 결제금액 입니다.

카드혜택 조회

GET /v1/promotions/card

카드사별 할인 프로모션, 할부 혜택 정보를 담은 객체들이 각각 discountCards, interestFreeCards에 배열로 포함되어 돌아옵니다.

API 직접 실행해보기

Query 파라미터

payType string
결제 타입 입니다. NORMAL(일반결제), CONNECTPAY(커넥트페이) 중 하나입니다. 일반 결제 연동에서는 CONNECTPAY를 사용하지 않습니다. 값이 없으면 기본 값은 NORMAL입니다.

요청

curl --request get \
  --url https://api.tosspayments.com/v1/promotions/card \
  --header 'Authorization: Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og=='

응답

{
    "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
      }
    ]
  }