코어 API

토스페이먼츠 API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요.

결제
자동결제
거래
- Transaction 객체
- 거래 조회
정산
현금영수증
지급대행
카드 혜택 조회
- CardPromotion 객체
- 카드 혜택 조회

API 키

인증

응답 본문

HTTP 프로토콜

결제

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

Payment 객체

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

결제가 승인됐을 때 응답은 Payment 객체로 항상 동일하지만, 결제수단에 따라 객체 상세 구성이 조금씩 달라집니다.

객체 상세

version string
Payment 객체의 응답 버전입니다. 버전 2022-06-08부터 날짜 기반 버저닝을 사용합니다.
paymentKey string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인, 결제 조회, 결제 취소 API에 사용합니다.
type string
결제 타입 정보입니다. NORMAL(일반결제), BILLING(자동결제), BRANDPAY(브랜드페이) 중 하나입니다.
orderId string
주문 ID입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
orderName string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
mId string
상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.
currency string
결제할 때 사용한 통화입니다.
method string
결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.
totalAmount number
총 결제 금액입니다.
balanceAmount number
취소할 수 있는 금액(잔고)입니다.
status string
결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 흐름도를 살펴보세요.
- READY: 결제를 생성하면 가지게 되는 초기 상태 입니다. 인증 전까지는 READY 상태를 유지합니다.
- IN_PROGRESS: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. 결제 승인 API를 호출하면 결제가 완료됩니다.
- WAITING_FOR_DEPOSIT: 가상계좌 결제 흐름에만 있는 상태로, 결제 고객이 발급된 가상계좌에 입금하는 것을 기다리고 있는 상태입니다.
- DONE: 인증된 결제수단 정보, 고객 정보로 요청한 결제가 승인된 상태입니다.
- CANCELED: 승인된 결제가 취소된 상태입니다.
- PARTIAL_CANCELED: 승인된 결제가 부분 취소된 상태입니다.
- ABORTED: 결제 승인이 실패한 상태입니다.
- EXPIRED: 결제 유효 시간 30분이 지나 거래가 취소된 상태입니다. IN_PROGRESS 상태에서 결제 승인 API를 호출하지 않으면 EXPIRED가 됩니다.
requestedAt string
결제가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
(e.g. 2022-01-01T00:00:00+09:00)
approvedAt string
결제 승인이 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
(e.g. 2022-01-01T00:00:00+09:00)
useEscrow boolean
에스크로 사용 여부입니다.
lastTransactionKey nullable · string
마지막 거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키 값이 할당됩니다. 최대 길이는 64자입니다.
transactionKey nullable · string
DEPRECATED

마지막 거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는데 사용됩니다. 예를 들어 결제 승인 후 부분 취소를 두 번 했다면 마지막 부분 취소 거래의 키 값이 할당됩니다. 최대 길이는 64자입니다.
suppliedAmount number
공급가액입니다.
vat number
부가세입니다. (결제 금액 amount - 면세 금액 taxFreeAmount) / 11 후 소수점 첫째 자리에서 반올림해서 계산합니다.
(e.g. 결제 금액이 10,000원이고, 면세 금액이 3,000원이라면 부가세는 (10000-3000)/11 = 636.3636..을 반올림한 값 636원입니다.)
더 자세한 내용은 세금 처리하기에서 살펴보세요.
cultureExpense boolean
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. 계좌이체, 가상계좌 결제에만 적용됩니다.
* 카드 결제는 항상 false로 돌아옵니다. 카드 결제 문화비는 카드사에 문화비 소득공제 전용 가맹점번호로 등록하면 자동으로 처리됩니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다.
* 일반 상점일 때는 면세 금액으로 0이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
taxExemptionAmount integer
과세를 제외한 결제 금액(컵 보증금 등)입니다.
* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
cancels nullable · array
결제 취소 이력이 담기는 배열입니다.
- cancelAmount number
  결제를 취소한 금액입니다.
- cancelReason string
  결제를 취소한 이유입니다. 최대 길이는 200자입니다.
- taxFreeAmount number
  취소된 금액 중 면세 금액입니다.
- taxExemptionAmount integer
  취소된 금액 중 과세 제외 금액(컵 보증금 등)입니다.
- refundableAmount number
  결제 취소 후 환불 가능한 잔액입니다.
- easyPayDiscountAmount number
  간편결제 서비스의 포인트, 쿠폰, 즉시할인과 같은 적립식 결제수단에서 취소된 금액입니다.
- canceledAt string
  결제 취소가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
  (e.g. 2022-01-01T00:00:00+09:00)
- transactionKey string
  취소 건의 키 값입니다. 여러 건의 취소 거래를 구분하는데 사용됩니다. 최대 길이는 64자입니다.
- receiptKey string
  취소 건의 현금영수증 키 값입니다. 최대 길이는 200자입니다.
isPartialCancelable boolean
부분 취소 가능 여부입니다. 이 값이 false이면 전액 취소만 가능합니다.
card nullable · object
카드로 결제하면 제공되는 카드 관련 정보입니다.
- amount number
  카드사에 결제 요청한 금액입니다. 즉시 할인 금액(discount.amount)이 포함됩니다.
  * 간편결제에 등록된 카드로 결제했다면 간편결제 응답 확인 가이드를 참고하세요.
- issuerCode string
  카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.
- acquirerCode nullable · string
  카드 매입사 숫자 코드입니다. 카드사 코드를 참고하세요.
- number string
  카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.
- installmentPlanMonths integer
  할부 개월 수입니다. 일시불이면 0입니다.
- approveNo string
  카드사 승인 번호입니다. 최대 길이는 8자입니다.
- useCardPoint boolean
  카드사 포인트 사용 여부입니다.
  * 일반 카드사 포인트가 아닌, 특수한 포인트나 바우처를 사용하면 할부 개월 수가 변경되어 응답이 돌아오니 유의해주세요.
- cardType string
  카드 종류입니다. 신용, 체크, 기프트, 미확인 중 하나입니다. 고객이 해외 카드로 결제했거나 간편결제의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.
- ownerType string
  카드의 소유자 타입입니다. 개인, 법인, 미확인 중 하나입니다. 고객이 해외 카드로 결제했거나 간편결제의 결제 수단을 조합해서 결제했을 때 미확인으로 표시됩니다.
- acquireStatus string
  카드 결제의 매입 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.
  - READY: 아직 매입 요청이 안 된 상태입니다.
  - REQUESTED: 매입이 요청된 상태입니다.
  - COMPLETED: 요청된 매입이 완료된 상태입니다.
  - CANCEL_REQUESTED: 매입 취소가 요청된 상태입니다.
  - CANCELED: 요청된 매입 취소가 완료된 상태입니다.
- isInterestFree boolean
  무이자 할부의 적용 여부입니다.
- interestPayer nullable · string
  할부가 적용된 결제에서 할부 수수료를 부담하는 주체입니다. BUYER, CARD_COMPANY, MERCHANT 중 하나입니다.
  - BUYER: 상품을 구매한 고객이 할부 수수료를 부담합니다. 일반적인 할부 결제입니다.
  - CARD_COMPANY: 카드사에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.
  - MERCHANT: 상점에서 할부 수수료를 부담합니다. 무이자 할부 결제입니다.
virtualAccount nullable · object
가상계좌로 결제하면 제공되는 가상계좌 관련 정보입니다.
- accountType string
  가상계좌 타입을 나타냅니다. 일반, 고정 중 하나입니다.
- accountNumber string
  발급된 계좌번호입니다. 최대 길이는 20자입니다.
- bankCode string
  가상계좌 은행 숫자 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- customerName string
  가상계좌를 발급한 고객 이름입니다. 최대 길이는 100자입니다.
- dueDate string
  입금 기한입니다. yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식을 사용합니다.
- refundStatus string
  환불 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.
  - NONE: 환불 요청이 없는 상태입니다.
  - PENDING: 환불을 처리 중인 상태입니다.
  - FAILED: 환불에 실패한 상태입니다.
  - PARTIAL_FAILED: 부분 환불에 실패한 상태입니다.
  - COMPLETED: 환불이 완료된 상태입니다.
- expired boolean
  가상계좌가 만료되었는지 여부입니다.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.
- refundReceiveAccount object
  환불계좌 정보입니다. 은행 코드(bankCode), 계좌번호(accountNumber), 예금주 정보(holderName)가 담긴 객체입니다.
  * 구매자의 환불계좌 정보는 결제창을 띄운 시점부터 30분 동안만 조회할 수 있습니다. 이후에는 값이 내려가지 않습니다.
secret nullable · string
가상계좌 웹훅이 정상적인 요청인지 검증하는 값입니다. 이 값이 가상계좌 웹훅 이벤트 본문으로 돌아온 secret과 같으면 정상적인 요청입니다. 최대 길이는 50자입니다.
mobilePhone nullable · object
휴대폰으로 결제하면 제공되는 휴대폰 결제 관련 정보입니다.
- customerMobilePhone string
  결제에 사용한 휴대폰 번호입니다.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.
- receiptUrl string
  휴대폰 결제 내역 영수증을 확인할 수 있는 주소입니다.
giftCertificate nullable · object
상품권으로 결제하면 제공되는 상품권 결제 관련 정보입니다.
- approveNo string
  결제 승인번호입니다. 최대 길이는 8자입니다.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.
transfer nullable · object
계좌이체로 결제했을 때 이체 정보가 담기는 객체입니다.
- bankCode string
  은행 숫자 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- settlementStatus string
  정산 상태입니다. 정산이 아직 되지 않았다면 INCOMPLETED, 정산이 완료됐다면 COMPLETED 값이 들어옵니다.
receipt nullable · object
발행된 영수증 정보입니다.
- url string
  각 결제수단별 영수증을 확인할 수 있는 주소입니다. 카드 결제는 매출전표, 가상계좌는 무통장 거래 명세서, 계좌이체・휴대폰・상품권 결제는 결제 거래 내역 확인서가 제공됩니다.
checkout nullable · object
결제창 정보입니다.
- url string
  결제창이 열리는 주소입니다.
easyPay nullable · object
간편결제 정보입니다. 고객이 선택한 결제수단에 따라 amount, discountAmount가 달라집니다. 간편결제 응답 확인 가이드를 참고하세요.
- provider string
  선택한 간편결제사 코드입니다.
- amount number
  간편결제 서비스에 등록된 계좌 혹은 현금성 포인트로 결제한 금액입니다.
- discountAmount number
  간편결제 서비스의 적립 포인트나 쿠폰 등으로 즉시 할인된 금액입니다.
easyPayAmount nullable · number
DEPRECATED

간편결제에 등록되어 있는 계좌로 결제한 금액입니다.
easyPayDiscountAmount nullable · number
DEPRECATED

간편결제 서비스의 포인트로 결제한 금액입니다.
country string
결제한 국가입니다. ISO-3166의 두 자리 국가 코드 형식입니다.
failure nullable · object
결제 승인에 실패하면 응답으로 받는 에러 객체입니다. 실패한 결제를 조회할 때 확인할 수 있습니다.
- code string
  오류 타입을 보여주는 에러 코드입니다.
- message string
  에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다.
cashReceipt nullable · object
현금영수증 정보입니다.
- type string
  현금영수증의 종류입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.
- receiptKey string
  현금영수증의 키 값입니다. 최대 길이는 200자입니다.
- issueNumber string
  현금영수증 발급 번호입니다. 최대 길이는 9자입니다.
- receiptUrl string
  발행된 현금영수증을 확인할 수 있는 주소입니다.
- amount number
  현금영수증 처리된 금액입니다.
- taxFreeAmount number
  면세 처리된 금액입니다.
cashReceipts nullable · array
현금영수증 발행 및 취소 이력이 담기는 배열로 순서가 보장되지 않습니다. 예를 들어 결제 후 부분 취소가 여러 번 일어나면 모든 결제 및 부분 취소 건에 대한 현금영수증을 담고 있습니다. 계좌이체는 결제 즉시 현금영수증 정보를 확인할 수 있습니다. 가상계좌는 고객이 입금을 완료하면 현금영수증 정보를 확인할 수 있습니다.
* 결제가 이미 승인된 후 현금영수증 발급 요청 API로 발급한 현금연수증은 먼저 처리된 결제 정보와 연결되지 않아 값이 null입니다. 현금영수증 조회 API로 조회해주세요. 자세한 내용은 현금영수증 발급 및 취소 가이드에서 확인해주세요.
- receiptKey string
  현금영수증의 키 값입니다. 최대 길이는 200자입니다.
- orderId string
  주문 ID입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
- orderName string
  주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
- type string
  현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.
- issueNumber string
  현금영수증 발급 번호입니다. 최대 길이는 9자입니다.
- receiptUrl string
  발행된 현금영수증을 확인할 수 있는 주소입니다.
- businessNumber string
  현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다.
- transactionType string
  현금영수증 발급 종류입니다. 현금영수증 발급(CONFIRM)·취소(CANCEL) 건을 구분합니다.
- amount integer
  현금영수증 처리된 금액입니다.
- taxFreeAmount integer
  면세 처리된 금액입니다.
- issueStatus string
  현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다. IN_PROGRESS, COMPLETED, FAILED 중 하나입니다. 각 상태의 자세한 설명은 CashReceipt 객체에서 확인할 수 있습니다.
- failure object
  결제 실패 객체입니다. 오류 타입을 보여주는 code와 에러 메시지를 보여주는 message 필드가 있습니다.
- customerIdentityNumber string
  현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.
- requestedAt string
  결제가 일어난 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)
discount nullable · object
카드사의 즉시 할인 프로모션 정보입니다. 즉시 할인 프로모션이 적용됐을 때만 생성됩니다.
- amount integer
  카드사의 즉시 할인 프로모션을 적용한 금액입니다.

결제 승인

POST /v1/payments/confirm

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

* 결제 승인 엔드포인트가 /v1/payments/{paymentKey}에서 /v1/payments/confirm으로 변경되었습니다. 이전 엔드포인트는 사용을 권장하지 않습니다.

API 직접 실행해보기

Request Body 파라미터

paymentKey 필수 · string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.
orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
amount 필수 · number
결제할 금액입니다.

Response

성공

결제 승인에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 승인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 승인 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: a6a498c4-6f61-4183-a2ff-80176e69a067' \
  --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6","orderId":"a4CWyWY5m89PNh7xJwhk1","amount":15000}'

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "lastTransactionKey": "B7103F204998813B889C77C043D09502",
  "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": {
    "amount": 15000,
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12341234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

`paymentKey`로 결제 조회

GET /v1/payments/{paymentKey}

승인된 결제를 paymentKey로 조회합니다. paymentKey는 SDK를 통해 결제를 진행한 결과로 돌아온 Payment 객체에 담겨있습니다.

자세한 내용은 결제 기록 조회하기에서 확인해보세요.

API 직접 실행해보기

Path 파라미터

paymentKey 필수 · string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

Response

성공

결제 조회에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

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

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "lastTransactionKey": "B7103F204998813B889C77C043D09502",
  "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": {
    "amount": 15000,
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12341234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

`orderId`로 결제 조회

GET /v1/payments/orders/{orderId}

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

API 직접 실행해보기

Path 파라미터

orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.

Response

성공

결제 조회에 성공했다면 Payment 객체가 돌아옵니다. 사용한 결제수단 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

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

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "lastTransactionKey": "B7103F204998813B889C77C043D09502",
  "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": {
    "amount": 15000,
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12341234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

결제 취소

POST /v1/payments/{paymentKey}/cancel

승인된 결제를 paymentKey로 취소합니다.

* 멱등키를 요청 헤더에 추가하면 중복 취소 없이 안전하게 처리됩니다.

API 직접 실행해보기

Path 파라미터

paymentKey 필수 · string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다.

Request Body 파라미터

cancelReason 필수 · string
결제를 취소하는 이유입니다. 최대 길이는 200자입니다.
cancelAmount number
취소할 금액입니다. 값이 없으면 전액 취소됩니다.
refundReceiveAccount object
결제 취소 후 금액이 환불될 계좌의 정보입니다. 가상계좌 결제에만 필수입니다. 다른 결제수단으로 이루어진 결제를 취소할 때는 사용하지 않습니다. 보낸 계좌 정보는 유효성 검사가 이뤄집니다. 유효한 계좌로 결제 취소 요청이 되었다면 환불은 취소 요청 후 2일 후에 진행됩니다.
- bank 필수 · string
  취소 금액을 환불받을 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber 필수 · string
  취소 금액을 환불받을 계좌의 계좌번호 입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.
- holderName 필수 · string
  취소 금액을 환불받을 계좌의 예금주입니다. 최대 길이는 60자입니다.
taxFreeAmount number
취소할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
currency string
취소 통화입니다. PayPal 해외간편결제 부분 취소에는 필수 값입니다. PayPal에서 사용할 수 있는 통화는 USD 입니다.
refundableAmount number
DEPRECATED

현재 환불 가능한 금액입니다. 결제 취소를 안전하게 처리합니다.
환불 가능한 잔액 정보가 refundableAmount의 값과 다르면 취소를 처리하지 않고 에러를 내보냅니다.
* 이 파라미터는 더 이상 사용을 권장하지 않습니다. 안전하게 취소하려면 멱등키를 대신 사용해주세요.

Response

성공

결제 취소에 성공했다면 Payment 객체의 cancels 필드에 취소 객체가 배열로 돌아옵니다.

실패

결제 취소에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

결제 취소 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/2WkABYDxNyJQbgMGZzorzYWwKBG9kVl5E1em4dKva7XL9njP/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: e9b779ed-3541-4b6e-aa95-88f710689a68' \
  --data '{"cancelReason":"고객 변심"}'

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "2WkABYDxNyJQbgMGZzorzYWwKBG9kVl5E1em4dKva7XL9njP",
  "lastTransactionKey": "66630503F0C4BA6F33FF33EAC15249C2",
  "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,
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/2WkABYDxNyJQbgMGZzorzYWwKBG9kVl5E1em4dKva7XL9njP/checkout"
  },
  "card": {
    "amount": "1000",
    "issuerCode": "33",
    "acquirerCode": "31",
    "number": "12341234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=bGqvzDSq5OoimabqhwIGRNk5Ks4A%2B2pzVwKxOP0WsjnZ6FZiUqVa4RbnVeqVlxsd&ref=PX"
  },
  "discount": null,
  "cancels": [
    {
      "cancelReason": "고객 변심",
      "canceledAt": "2022-01-01T11:32:04+09:00",
      "cancelAmount": 1000,
      "taxFreeAmount": 0,
      "taxExemptionAmount": 0,
      "refundableAmount": 0,
      "easyPayDiscountAmount": 0,
      "transactionKey": "66630503F0C4BA6F33FF33EAC15249C2",
      "receiptKey": "Ik43Gc0hQldGN0l8iPRIbA0YMNdMRnPcZGIQnpLkzU6mhvE0"
    }
  ],
  "secret": null,
  "type": "NORMAL",
  "easyPay": "토스결제",
  "country": "KR",
  "failure": null,
  "currency": "KRW",
  "totalAmount": 1000,
  "balanceAmount": 0,
  "suppliedAmount": 0,
  "vat": 0,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

카드 번호 결제

* 카드 번호 결제 API는 추가 계약 후 사용할 수 있습니다.

POST /v1/payments/key-in

결제할 카드 번호 및 기타 카드 정보로 결제를 요청합니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
cardNumber 필수 · string
카드 번호입니다. 최대 길이는 20자입니다.
cardExpirationYear 필수 · string
카드 유효연도입니다.
cardExpirationMonth 필수 · string
카드 유효 월입니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
customerIdentityNumber 필수 · string
카드 소유자 정보입니다. 생년월일 6자리(YYMMDD) 혹은 사업자등록번호 10자리가 들어갑니다.
cardPassword string
카드 비밀번호 앞 두자리입니다.
cardInstallmentPlan integer
신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다. 결제 금액이 5만원 이상일 때만 할부가 적용됩니다.
useFreeInstallmentPlan boolean
카드사 무이자 할부 적용 여부입니다. 기본값은 false 입니다.
값이 true이면 cardInstallmentPlan에 지정한 할부 개월로 무이자 할부가 적용됩니다.
* 이 파라미터로 적용된 무이자 할부 비용은 상점이 부담합니다.
taxFreeAmount integer
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
customerName string
고객 이름입니다. 최대 길이는 100자입니다.
vbv object
해외 카드 결제의 3DS 인증에 사용합니다. 3DS 인증 결과를 전송해야 되면 필수입니다.
- cavv string
  3D Secure 인증 세션의 인증 값입니다.
- xid string
  트랜잭션 ID 입니다.
- eci string
  3DS 인증 결과의 코드 값입니다.

Response

성공

카드 번호 결제에 성공했다면 Payment 객체가 돌아옵니다.

실패

카드 번호 결제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 번호 결제 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/key-in \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 145b3cc3-1cc2-4a1b-abe6-6e64c6ab660e' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","orderName":"토스 티셔츠 외 2건","customerIdentityNumber":"881212","customerName":"박토스","cardPassword":"12"}'

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "lastTransactionKey": "B7103F204998813B889C77C043D09502",
  "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": {
    "amount": 15000,
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "12341234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

가상계좌 발급 요청

POST /v1/virtual-accounts

구매자가 원하는 은행의 가상계좌 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다. 최소 1글자 이상 100글자 이하여야 합니다.
customerName 필수 · string
입금할 고객 이름입니다. 최대 길이는 100자입니다.
bank 필수 · string
가상계좌를 발급할 은행입니다. 가상계좌 발급이 가능한 은행을 참고하세요.
accountKey string
고정 가상계좌를 사용하는 고객과 매칭시킨 계좌의 고유한 키 값입니다. 특정 고객에게 같은 가상계좌를 다시 발급하려면 처음 고정 가상계좌를 발급할 때 사용했던 accountKey를 넘겨주세요. 최대 길이는 13자입니다.
* 고객이 같은 계좌로 여러 번 입금할 수 있는 고정 가상계좌는 추가 계약이 필요합니다.
validHours integer
가상계좌가 발급 시점으로부터의 유효한 시간 범위입니다. 설정한 validHours 안에 구매자가 입금을 하지 않으면 주문은 취소됩니다. 가상계좌 발급 후 일정 시간 뒤에 반납됩니다. 예를 들어 가상계좌 발급 후 24시간 내에 입금해야 한다면 24로 설정합니다. 값을 넣지 않으면 기본값 168시간(7일)으로 설정됩니다. 설정할 수 있는 최대값은 720시간(30일)입니다.
validHours와 dueDate 중 하나만 사용할 수 있습니다.
dueDate string
가상계좌 입금 기한을 날짜로 특정합니다. 지정한 시점에 가상계좌가 반납됩니다. 예를 들어 입금 시간을 '주문 후 3일 뒤 자정'과 같이 특정 시점으로 설정하고 싶을 때 2023-10-10T00:00:00과 같이 사용하세요. 티켓 예매등 주문 시간과 상관없이 정해진 시점까지 입금을 받아야 할 때도 사용하실 수 있습니다. 현재 시간을 기준으로 720시간(30일) 이내의 특정 시점으로 입금 기한을 직접 설정하고 싶을 때 사용합니다. 720시간 이후로 기한을 설정하면 에러가 발생합니다.
yyyy-MM-dd'T'HH:mm:ss ISO 8601 형식입니다.
validHours와 dueDate 중 하나만 사용할 수 있습니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
customerMobilePhone string
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다.
taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
useEscrow boolean
에스크로 사용 여부입니다. 값을 넣지 않으면 기본값인 false로 설정되고 사용자가 에스크로 결제 여부를 선택합니다.
cashReceipt object
현금영수증 발급 정보를 담는 객체입니다.
- type string
  현금영수증 발급 용도입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.
- registrationNumber string
  현금영수증 발급에 필요한 개인 식별 번호입니다. 최대 길이는 30자입니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 카드 번호 등을 입력할 수 있습니다.
escrowProducts array
각 상품의 상세 정보를 담는 배열입니다. 예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
- id 필수 · string
  상품의 ID입니다. 이 값은 유니크해야 합니다.
- name 필수 · string
  상품 이름입니다.
- code 필수 · string
  상점에서 사용하는 상품 관리 코드입니다.
- unitPrice 필수 · integer
  상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity 필수 · integer
  상품 구매 수량입니다.

Response

성공

가상계좌 발급 요청에 성공했다면 virtualAccount 필드에 값이 있는 Payment 객체가 돌아옵니다.

실패

가상계좌 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

가상계좌 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/virtual-accounts \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 9ed6f44e-3f45-4b25-90b8-20978f8ceeb0' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"박토스","bank":"20"}'

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM",
  "lastTransactionKey": "92ZGCCURB4HS732TO625FFGQD2SWOEN0",
  "orderId": "a4CWyWY5m89PNh7xJwhk1",
  "orderName": "토스 티셔츠 외 2건",
  "currency": "KRW",
  "method": "가상계좌",
  "status": "WAITING_FOR_DEPOSIT",
  "requestedAt": "2021-01-20T20:12:46+09:00",
  "approvedAt": null,
  "useEscrow": false,
  "cultureExpense": false,
  "card": null,
  "virtualAccount": {
    "accountNumber": "X6505636518308",
    "accountType": "일반",
    "bankCode": "20",
    "customerName": "박토스",
    "dueDate": "2021-02-05T21:05:09+09:00",
    "expired": false,
    "settlementStatus": "INCOMPLETED",
    "refundStatus": "NONE",
    "refundReceiveAccount": null
  },
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/R9o5gEq4k6YZ1aOwX7K8m1g0QjYOP8yQxzvNPGenpDAlBdbM/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 15000,
  "balanceAmount": 15000,
  "suppliedAmount": 13636,
  "vat": 1364,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

자동결제

자동결제 API로 고객의 결제수단 정보를 인증·등록한 뒤 상점에서 원하는 시점에 자동으로 결제할 수 있습니다.

* 자동결제 API는 추가 계약 후 사용할 수 있습니다. 추가 계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

Billing 객체

자동결제에 사용할 결제수단이 인증되어 등록되었을 때 돌아오는 객체입니다.

등록된 카드 정보와 발급된 billingKey가 포함되어 있습니다. billingKey로 자동결제 요청 API를 호출할 수 있습니다.

객체 상세

mId string
상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.
customerKey string
고객 ID입니다. 빌링키와 연결됩니다. 최소 길이는 2자, 최대 길이는 300자입니다. 가맹점에서 직접 생성하고 관리하는 값입니다. * customerKey는 클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.
authenticatedAt string
결제수단이 인증된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)
method string
결제수단입니다. 현재 자동결제는 카드만 지원하기 때문에 카드로 값이 고정되어 돌아옵니다.
billingKey string
자동결제에서 카드 정보 대신 사용되는 값입니다. customerKey와 연결됩니다. 최대 길이는 200자입니다.
card object
발급된 빌링키와 연결된 카드 정보입니다.
- issuerCode string
  카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.
- acquirerCode string
  카드 매입사 숫자 코드입니다. 카드사 코드를 참고하세요.
- number string
  카드 번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.
- cardType string
  카드 종류입니다. 신용, 체크, 기프트 중 하나입니다.
- ownerType string
  카드의 소유자 타입입니다. 개인, 법인 중 하나입니다.

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

* 자동결제 API는 추가 계약 후 사용할 수 있습니다.

POST /v1/billing/authorizations/card

고객을 특정하는 customerKey와 연결할 빌링키 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

customerKey 필수 · string
고객 ID입니다. 빌링키와 연결됩니다. 가맹점에서 직접 생성하고 관리하는 값입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. * customerKey는 클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.
cardNumber 필수 · string
카드 번호입니다. 최대 길이는 20자입니다.
cardExpirationYear 필수 · string
카드 유효연도입니다.
cardExpirationMonth 필수 · string
카드 유효 월입니다.
customerIdentityNumber 필수 · string
카드 소유자 정보입니다. 생년월일 6자리(YYMMDD) 혹은 사업자등록번호 10자리가 들어갑니다.
cardPassword string
카드 비밀번호 앞 두자리입니다.
customerName string
고객 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
vbv object
해외 카드 결제의 3DS 인증에 사용합니다. 3DS 인증 결과를 전송해야 되면 필수입니다.
- cavv string
  3D Secure 인증 세션의 인증 값입니다.
- xid string
  트랜잭션 ID 입니다.
- eci string
  3DS 인증 결과의 코드 값입니다.

Response

성공

customerKey로 카드 자동결제 요청에 성공했다면 Billing 객체가 돌아옵니다.

실패

customerKey로 카드 자동결제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/billing/authorizations/card \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: b0d582d8-d884-4e02-b2f0-6fbdb03e6da2' \
  --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": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "cardType": "신용",
    "ownerType": "개인"
  }
}

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

* 자동결제 API는 추가 계약 후 사용할 수 있습니다.

POST /v1/billing/authorizations/issue

requestBillingAuth 호출 후 쿼리 파라미터로 돌아오는 authKey, 고객 ID인 customerKey로 빌링키 발급을 요청합니다.

* 자동결제 빌링키 발급 요청 엔드포인트가 /v1/billing/authorizations/{authKey}에서 /v1/billing/authorizations/issue로 변경되었습니다. 이전 엔드포인트는 사용을 권장하지 않습니다.

API 직접 실행해보기

Request Body 파라미터

authKey 필수 · string
자동결제 등록창 호출이 성공하면 리다이렉트 URL에 쿼리 파라미터(Query Parameter)로 돌아오는 일회성 인증 키입니다. 최대 길이는 300자입니다.
customerKey 필수 · string
고객 ID입니다. 빌링키와 연결됩니다. 가맹점에서 직접 생성하고 관리하는 값입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다. * customerKey는 클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.

Response

성공

카드 자동결제 빌링키 발급 요청에 성공했다면 Billing 객체가 돌아옵니다.

실패

카드 자동결제 빌링키 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 자동결제 빌링키 발급 요청 API에서 발생 가능한 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/billing/authorizations/issue \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 2e64b175-6436-4fd9-9189-900b4f6c4dd3' \
  --data '{"authKey":"e_826EDB0730790E96F116FFF3799A65DE","customerKey":"aENcQAtPdYbTjGhtQnNVj"}'

응답

{
  "mId": "tosspayments",
  "customerKey": "aENcQAtPdYbTjGhtQnNVj",
  "authenticatedAt": "2020-09-25T14:38:41+09:00",
  "method": "카드",
  "billingKey": "Z_t5vOvQxrj4499PeiJcjen28-V2RyqgYTwN44Rdzk0=",
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "cardType": "신용",
    "ownerType": "개인"
  }
}

카드 자동결제 승인

* 자동결제 API는 추가 계약 후 사용할 수 있습니다.

POST /v1/billing/{billingKey}

발급받은 billingKey로 카드 자동결제를 승인합니다. 카드 자동결제 승인은 최대 30초가 소요됩니다. 타임아웃 값을 최소 30초로 설정하세요.

API 직접 실행해보기

Path 파라미터

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

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
customerKey 필수 · string
고객 ID입니다. 빌링키와 연결됩니다. 가맹점에서 직접 생성하고 관리하는 값입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.
orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
customerName string
고객 이름입니다. 최대 길이는 100자입니다.
taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
cardInstallmentPlan integer
신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 2부터 12사이의 값을 사용할 수 있고, 0이 들어가거나 값을 넣지 않으면 할부가 아닌 일시불로 결제됩니다.

Response

성공

카드 자동결제 승인에 성공했다면 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' \
  --header 'Idempotency-Key: 5728e401-57d2-4126-bd71-6d7004f3e9b5' \
  --data '{"customerKey":"aENcQAtPdYbTjGhtQnNVj","amount":4900,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 프라임 구독","customerEmail":"customer@email.com","customerName":"박토스","taxFreeAmount":0,"taxExemptionAmount":0}'

응답

{
  "mId": "tosspayments",
  "version": "2022-07-27",
  "paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
  "lastTransactionKey": "OPAZDL2XENJBEQGLNVLRKBF97231EWV1M9",
  "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": {
    "amount": "4900",
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "receipt": {
    "url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6/checkout"
  },
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BILLING",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 4900,
  "balanceAmount": 4900,
  "suppliedAmount": 4455,
  "vat": 455,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0
}

거래

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

Transaction 객체

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

하나의 결제 건에 여러 번의 거래가 일어날 수 있습니다. 결제 승인, 취소, 부분 취소가 이루어질 때마다 각각의 거래 정보를 담은 Transaction 객체가 만들어지고 개별 transactionKey를 가지게 됩니다.

거래 조회 API를 호출하면 지정한 기간 동안 생긴 모든 Transaction 객체들이 배열로 돌아옵니다.

객체 상세

mId string
상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.
transactionKey string
거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는데 사용됩니다. 최대 길이는 64자입니다.
paymentKey string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
orderId string
주문 ID입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용합니다. 결제 상태가 변해도 값이 유지됩니다.
method string
결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.
customerKey string
고객 ID입니다. 빌링키와 연결됩니다. 가맹점에서 직접 생성하고 관리하는 값입니다. 최소 길이는 2자, 최대 길이는 300자입니다. * customerKey는 클라이언트 키와 다릅니다. 클라이언트 키는 연동을 위한 기본 키로 브라우저에서 SDK를 연동할 때 '클라이언트'를 식별하며, 토스페이먼츠에서 제공합니다.
useEscrow boolean
에스크로 사용 여부입니다.
receiptUrl string
거래 영수증을 확인할 수 있는 주소입니다.
status string
결제 처리 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다. 상태 변화 흐름이 궁금하다면 흐름도를 살펴보세요.
- READY: 결제를 생성하면 가지게 되는 초기 상태 입니다. 인증 전까지는 READY 상태를 유지합니다.
- IN_PROGRESS: 결제수단 정보와 해당 결제수단의 소유자가 맞는지 인증을 마친 상태입니다. 결제 승인 API를 호출하면 결제가 완료됩니다.
- WAITING_FOR_DEPOSIT: 가상계좌 결제 흐름에만 있는 상태로, 결제 고객이 발급된 가상계좌에 입금하는 것을 기다리고 있는 상태입니다.
- DONE: 인증된 결제수단 정보, 고객 정보로 요청한 결제가 승인된 상태입니다.
- CANCELED: 승인된 결제가 취소된 상태입니다.
- PARTIAL_CANCELED: 승인된 결제가 부분 취소된 상태입니다.
- ABORTED: 결제 승인에 실패한 상태입니다.
- EXPIRED: 요청된 결제의 유효 시간 30분이 지나 거래가 취소된 상태입니다. IN_PROGRESS 상태에서 결제 승인 API를 호출하지 않으면 EXPIRED가 됩니다.
transactionAt string
거래가 처리된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
currency string
결제할 때 사용한 통화입니다.
amount number
결제한 금액입니다.

거래 조회

GET /v1/transactions

지정한 날짜 정보로 거래 기록을 조회합니다. 거래 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

자세한 내용은 거래 기록 조회하기에서 확인해보세요.

API 직접 실행해보기

Query 파라미터

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

Response

성공

거래 조회에 성공했다면 Transaction 객체가 담긴 배열이 돌아옵니다.

실패

거래 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

거래 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request GET \
  --url 'https://api.tosspayments.com/v1/transactions?startDate=2022-01-01T00:00:00&endDate=2022-01-10T23:59:59' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

응답

[
  {
    "mId": "tosspayments",
    "transactionKey": "AC45CD421C4E49D7B878522128B8D9C6",
    "paymentKey": "lOR1ZwdkQD5GePWvyJnrKXP6nDMRb8gLzN97EoqYA60XKx4a",
    "orderId": "fMgvolnZP6_ZdEYAaWF_1",
    "method": "카드",
    "customerKey": "cG_EdskNV1JgX7Y16S6vo",
    "useEscrow": false,
    "receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments01202301021537455ezz1&ref=PX",
    "status": "DONE",
    "transactionAt": "2023-01-02T15:37:45+09:00",
    "currency": "KRW",
    "amount": 1500
  },
  {
    "mId": "tosspayments",
    "transactionKey": "E41141562F42C887DB9F45D0FA4101D1",
    "paymentKey": "XJxNkgDKzOEP59LybZ8BJkX7ky5Y9B86GYo7pRe10BMQwla2",
    "orderId": "CwNjZgeiXkvmqnzjip78m",
    "method": "간편결제",
    "customerKey": null,
    "useEscrow": false,
    "receiptUrl": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tosspayments20230522104630vJoC6&ref=PX",
    "status": "DONE",
    "transactionAt": "2023-01-02T15:37:45+09:00",
    "currency": "KRW",
    "amount": 15000
  }
]

정산

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

Settlement 객체

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

객체 상세

mId string
상점아이디(MID)입니다. 토스페이먼츠에서 발급합니다. 최대 길이는 14자입니다.
paymentKey string
결제의 키 값입니다. 최대 길이는 200자입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
transactionKey string
거래의 키 값입니다. 한 결제 건의 승인 거래와 취소 거래를 구분하는데 사용됩니다. 최대 길이는 64자입니다.
orderId string
주문 ID입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용합니다. 결제 상태가 변해도 값이 유지됩니다.
currency string
결제할 때 사용한 통화입니다.
method string
결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권 중 하나입니다.
amount number
결제한 금액입니다.
interestFee number
할부 수수료 금액입니다.
fees array
결제 수수료의 상세 정보입니다. 수수료 상세 정보가 담긴 객체가 배열로 들어옵니다.
- type string
  수수료의 세부 타입입니다.
  BASE: 기본 수수료
  INSTALLMENT_DISCOUNT: 카드사 혹은 토스페이먼츠가 부담하는 무이자 할부 수수료
  INSTALLMENT: 상점이 부담하는 무이자 할부 수수료
  POINT_SAVING: 카드사 포인트 적립 수수료
  ETC: 기타 수수료
- fee number
  수수료 금액입니다.
supplyAmount number
결제 수수료의 공급가액입니다.
vat number
결제 수수료 부가세입니다.
payOutAmount number
지급 금액입니다. 결제 금액 amount에서 수수료인 fee를 제외한 금액입니다.
approvedAt string
거래가 승인된 시점의 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
(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)
* 정산 기록 조회하기에서 정산 지급일을 더 자세히 설명합니다.

정산 조회

GET /v1/settlements

지정한 날짜 정보로 정산 기록을 조회합니다. 정산 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Query 파라미터

startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다.
(e.g. 2022-01-01)
endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다.
(e.g. 2022-01-01)
dateType string
조회 기준이 되는 날짜 타입입니다. soldDate(정산 매출일)나 paidOutDate(정산 지급일) 중 하나입니다.
결제 금액을 정산받을 날짜 기준으로 조회하고 싶으면 paidOutDate를 사용하세요. 파라미터를 사용하지 않으면 soldDate 기준으로 조회됩니다.
더 자세한 내용은 정산 조회하기에서 살펴보세요.
page integer
조회할 페이지 값입니다. 최소값은 1입니다.
size integer
한 페이지에서 응답으로 보여줄 정산 기록 개수를 의미합니다. 기본값은 100이고 설정할 수 있는 최대값은 10000입니다.

Response

성공

정산 조회에 성공했다면 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"
  }
]

수동 정산 요청

* 수동 정산 요청 API는 추가 계약 후 사용할 수 있습니다.

POST /v1/settlements

매입하고 싶은 결제 건을 paymentKey로 특정해서 카드사에 정산을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

paymentKey 필수 · string
수동 정산을 요청할 결제 건을 특정하는 키 값 입니다. 최대 길이는 200자입니다.

Response

성공

수동 정산 요청에 성공했다면 result 값이 true로 돌아옵니다.

실패

수동 정산 요청 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/settlements \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 830d5b12-720f-401d-89f0-3d96a93812ea' \
  --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"}'

응답

{
  "result": true
}

현금영수증

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

CashReceipt 객체

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

객체 상세

receiptKey string
발급 혹은 취소 요청한 현금영수증 한 건을 특정하는 키 값입니다. 최대 길이는 200자입니다.
현금영수증 발급 API로 요청한 발급 건을 취소하면 앞서 발급했던 건의 receiptKey에 prefix로 c_가 추가되어 돌아옵니다.
issueNumber string
현금영수증 발급번호입니다. 최대 길이는 9자입니다.
issueStatus string
현금영수증 발급 상태입니다. 발급 승인 여부는 요청 후 1-2일 뒤 조회할 수 있습니다.
- IN_PROGRESS: 현금영수증 발급이 대기 중인 상태입니다.
- COMPLETED: 현금영수증이 발급된 상태입니다.
- FAILED: 현금영수증 발급에 실패한 상태입니다.
amount integer
현금영수증 처리된 금액입니다.
taxFreeAmount integer
면세 처리된 금액입니다.
orderId string
주문 ID입니다. 최소 길이는 6자, 최대 길이는 64자입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 사용한 값입니다. 결제 상태가 변해도 값이 유지됩니다.
orderName string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
type string
현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.
approvalNumber string
DEPRECATED

현금영수증 발급 승인번호입니다. 최대 길이는 9자입니다.
transactionType string
현금영수증 발급 종류입니다. 현금영수증 발급·취소 건을 구분합니다.
CONFIRM - 현금영수증을 발급했을 때
CANCEL - 발급된 현금영수증을 취소했을 때
businessNumber string
현금영수증을 발급한 사업자등록번호입니다. 길이는 10자입니다.
customerIdentityNumber string
현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다.
현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.
failure nullable · object
결제 실패 정보입니다.
- code string
  오류 타입을 보여주는 에러 코드입니다.
- message string
  에러 메시지입니다. 에러 발생 이유를 알려줍니다. 최대 길이는 510자입니다.
requestedAt string
현금영수증 발급 혹은 취소를 요청한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
approvedAt string
DEPRECATED

현금영수증이 발급된 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
(e.g. 2022-01-01T00:00:00+09:00)
canceledAt nullable · string
DEPRECATED

현금영수증을 발급을 취소한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.
(e.g. 2022-01-01T00:00:00+09:00)
receiptUrl string
발행된 현금영수증을 확인할 수 있는 주소입니다.

현금영수증 발급 요청

POST /v1/cash-receipts

현금영수증 발급을 요청합니다.

API 직접 실행해보기

Request Body 파라미터

amount 필수 · integer
현금영수증을 발급할 금액입니다.
orderId 필수 · string
주문 ID입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
customerIdentityNumber 필수 · string
현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 최대 길이는 30자입니다.
현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.
type 필수 · string
현금영수증의 종류입니다. 소득공제, 지출증빙 중 하나입니다.
taxFreeAmount integer
면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

Response

성공

현금영수증 발급 요청에 성공했다면 CashReceipt 객체가 돌아옵니다.

실패

현금영수증 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 발급 요청 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/cash-receipts \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: b43d8f78-5a8b-49e9-8fc2-27e6d9e5f8f2' \
  --data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerIdentityNumber":"01012341234","type":"소득공제"}'

응답

{
  "receiptKey": "aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
  "orderId": "oid-220728",
  "orderName": "토스티셔츠 외 2건",
  "type": "소득공제",
  "issueNumber": "160594074",
  "receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
  "businessNumber": "1111111111",
  "transactionType": "CONFIRM",
  "amount": 10000,
  "taxFreeAmount": 909,
  "issueStatus": "IN_PROGRESS",
  "failure": null,
  "requestedAt": "2022-07-27T22:39:19+09:00",
  "customerIdentityNumber": "01000001234"
}

현금영수증 발급 취소 요청

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

receiptKey를 이용해서 현금영수증 발급을 취소합니다.

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

API 직접 실행해보기

Path 파라미터

receiptKey 필수 · string
현금영수증의 키 값입니다. 최대 길이는 200자입니다.

Request Body 파라미터

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

Response

성공

현금영수증 발급 취소 요청에 성공했다면 CashReceipt 객체가 돌아옵니다.

실패

현금영수증 발급 취소 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 발급 취소 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/cash-receipts/qKl56WYb7w4vZnjEJeQVxbAdOll6d8PmOoBN0k12dzgRG9px/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Idempotency-Key: d1f1a4d6-6b62-4a44-9329-95ed5b4b8c52'

응답

{
  "receiptKey": "c_aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
  "orderId": "oid-220728",
  "orderName": "",
  "type": "소득공제",
  "issueNumber": "160592932",
  "receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
  "businessNumber": "1111111111",
  "transactionType": "CANCEL",
  "amount": 5000,
  "taxFreeAmount": 455,
  "taxExemptionAmount":0,
  "issueStatus": "IN_PROGRESS",
  "failure": null,
  "requestedAt": "2022-07-27T22:40:13+09:00",
  "customerIdentityNumber": "01000001234"
}

현금영수증 조회

* 현금영수증 조회 API는 버전 2022-07-27 이상에서만 지원합니다. API 버전은 개발자센터에서 확인·변경할 수 있습니다.

GET /v1/cash-receipts

특정 기간 동안 발급된 현금영수증을 조회합니다.

API 직접 실행해보기

Query 파라미터

requestDate 필수 · string
현금영수증 발급이 요청된 날짜로 조회하고 싶을 때 사용합니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)
cursor integer
특정 현금영수증 발급 건 이후의 기록을 조회할 때 사용합니다. 이전 조회에서 돌아온 lastCursor 값을 전달합니다. 많은 양의 기록을 페이지 단위로 나누어 처리할 때 사용할 수 있습니다.
limit integer
한 번에 응답받을 기록의 개수입니다. 기본값은 100이고 설정할 수 있는 최대값은 10000입니다.

Response

성공

현금영수증 조회에 성공했다면 아래 값을 포함한 객체가 내려갑니다.

hasNext: 다음 기록을 조회할 수 있는 지 여부입니다. 이 값이 false면 더 조회할 기록이 없습니다.
lastCursor: 특정 현금영수증 건 이후의 기록을 조회할 때 사용합니다. 다음 기록을 조회할 때 cursor 파라미터에 이 값을 사용합니다. 이 값은 integer 타입입니다.
data: 조회 요청에서 cursor로 특정한 현금영수증 건 이후의 기록입니다. CashReceipt 객체가 담긴 배열이 돌아옵니다.

실패

현금영수증 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

현금영수증 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request GET \
  --url 'https://api.tosspayments.com/v1/cash-receipts?requestDate=2022-07-27' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

응답

{
  "hasNext": false,
  "lastCursor": 213805090,
  "data": [
    {
      "receiptKey": "J4qjZblEopLBa5PzR0Arn97KPWlpvVvmYnNeDMyW2G1OgwK7",
      "orderId": "20220723MMZKT",
      "orderName": "토스티셔츠 외 1건",
      "type": "소득공제",
      "issueNumber": "160280710",
      "receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/20220723MMZKT/test_ka7r9?ref=PX",
      "businessNumber": "4118601799",
      "transactionType": "CONFIRM",
      "amount": 10000,
      "taxFreeAmount": 0,
      "issueStatus": "COMPLETED",
      "failure": null,
      "requestedAt": "2022-07-27T12:27:41+09:00",
      "customerIdentityNumber": "01012345678"
    },
    {
      "receiptKey": "c_J4qjZblEopLBa5PzR0Arn97KPWlpvVvmYnNeDMyW2G1OgwK7",
      "orderId": "20220723MMZKT",
      "orderName": "",
      "type": "소득공제",
      "issueNumber": "160496437",
      "receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/20220723MMZKT/test_ka7r9?ref=PX",
      "businessNumber": "4118601799",
      "transactionType": "CANCEL",
      "amount": 10000,
      "taxFreeAmount": 0,
      "issueStatus": "COMPLETED",
      "failure": null,
      "requestedAt": "2022-07-29T20:28:06+09:00",
      "customerIdentityNumber": "01012345678"
    }
  ]
}

지급대행

지급대행 API를 사용해 상점 하위의 서브몰 정보를 관리하고 정산된 금액을 서브몰에 지급할 수 있습니다.

* 지급대행 API는 추가 계약이 필요한 유료 서비스입니다. 지급대행 서비스를 추가 계약하면 하위 API를 모두 사용할 수 있습니다. 계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

* 지급대행 API는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Submall 객체

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

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

객체 상세

subMallId string
서브몰의 ID입니다. 최대 길이는 20자입니다.
type string
서브몰의 타입입니다. CORPORATE(법인), INDIVIDUAL(개인) 중 하나입니다.
companyName nullable · string
서브몰의 상호명입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다. 서브몰의 type이 CORPORATE(법인)일 때만 사용됩니다.
representativeName nullable · string
서브몰의 대표자명입니다. 최대 길이는 40자입니다. 서브몰의 type이 CORPORATE(법인)일 때만 사용됩니다.
businessNumber nullable · string
서브몰의 사업자등록번호 입니다. 길이는 10자입니다. 서브몰의 type이 CORPORATE(법인)일 때만 사용됩니다.
account object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bankCode string
  은행 숫자 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber string
  계좌번호입니다. 최대 길이는 20자입니다.
- holderName nullable · string
  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.
email nullable · string
서브몰 이메일 주소입니다.
phoneNumber nullable · string
서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다. 길이는 8자 이상 11자 이하여야 합니다.
metadata nullable · object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

서브몰 등록

* 서브몰 등록 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

POST /v1/payouts/sub-malls

상점 하위에 새로운 서브몰을 등록합니다. 서브몰 등록은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Request Body 파라미터

subMallId 필수 · string
서브몰의 ID입니다. 최대 길이는 20자입니다.
account 필수 · object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
  지급받을 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber 필수 · string
  계좌번호입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.
- holderName string
  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.
type 필수 · string
서브몰의 타입입니다. CORPORATE(법인), INDIVIDUAL(개인) 중 하나의 값을 넣어주세요.
email 필수 · string
서브몰 이메일 주소입니다.
phoneNumber 필수 · string
서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다.
companyName string
서브몰의 상호명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.
representativeName string
서브몰의 대표자명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 20자, 영문 40자입니다.
businessNumber string
서브몰의 사업자등록번호 입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 길이는 10자입니다.
metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

Response

성공

서브몰 등록에 성공했다면 생성된 Submall 객체가 돌아옵니다.

실패

서브몰 등록에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

서브몰 등록 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payouts/sub-malls \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 9c57d3e3-8d96-4e6a-9fd9-5434091eb173' \
  --data '{"subMallId":"testmall100","account":{"bank":"03","accountNumber":"34000000000011","holderName":"김토페"},"type":"CORPORATE","email":"example@email.com","phoneNumber":"01012341234","companyName":"테스트몰100","representativeName":"김토페","businessNumber":"1200220000"}'

응답

{
  "subMallId": "testmall100",
  "type": "CORPORATE",
  "companyName": "테스트몰100",
  "representativeName": "김토페",
  "businessNumber": "1200220000",
  "account": {
    "bankCode": "03",
    "accountNumber": "00123412341234",
    "holderName": "김토페"
  },
  "email": "testmall100@test.com",
  "phoneNumber": "01012341234",
  "metadata": null
}

서브몰 조회

* 서브몰 조회 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

GET /v1/payouts/sub-malls

상점 하위에 등록되어 있는 서브몰을 조회합니다. 서브몰 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Response

성공

서브몰 조회에 성공했다면 Submall 객체가 담긴 배열이 돌아옵니다.

실패

서브몰 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

서브몰 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

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": {
      "bankCode": "03",
      "accountNumber": "00123412341234",
      "holderName": "김토페"
    },
    "email": "testmall100@test.com",
    "phoneNumber": "01012341234",
    "metadata": null
  },
  {
    "subMallId": "testmall300",
    "type": "CORPORATE",
    "companyName": "테스트몰300",
    "representativeName": "박토스",
    "businessNumber": "1200330000",
    "account": {
      "bankCode": "20",
      "accountNumber": "00123456785678",
      "holderName": "박토스"
    },
    "email": "testmall300@test.com",
    "phoneNumber": "01011112222",
    "metadata": null
  }
]

서브몰 수정

* 서브몰 수정 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

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

submallId에 해당하는 서브몰의 정보를 Request Body 파라미터 값으로 수정합니다. 서브몰 수정은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Path 파라미터

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

Request Body 파라미터

account 필수 · object
서브몰에서 정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bank 필수 · string
  지급받을 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber 필수 · string
  계좌번호입니다. - 없이 숫자만 넣어야 합니다. 최대 길이는 20자입니다.
- holderName string
  지급받을 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.
companyName string
서브몰의 상호명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.
representativeName string
서브몰의 대표자명입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 최대 길이는 공백을 포함한 한글 20자, 영문 40자입니다.
businessNumber string
서브몰의 사업자등록번호 입니다. 서브몰의 type이 CORPORATE일 때 필수로 보내야 하는 파라미터입니다. 길이는 10자입니다.
email string
서브몰 이메일 주소입니다.
phoneNumber string
서브몰 연락처입니다. - 없이 숫자만 넣어야 합니다. 길이는 8자 이상 11자 이하여야 합니다.
metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

Response

성공

서브몰 수정에 성공했다면 수정된 Submall 객체가 돌아옵니다.

실패

서브몰 수정에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

서브몰 수정 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 6f873db5-8bfb-4d30-9b07-4cc7d4fba7f9' \
  --data '{"account":{"bank":"03","accountNumber":"34000000000011","holderName":"김토페"},"companyName":"테스트몰200","representativeName":"김토페","businessNumber":"1200220000"}'

응답

{
  "subMallId": "testmall100",
  "type": "CORPORATE",
  "companyName": "테스트몰200",
  "representativeName": "김토페",
  "businessNumber": "1200220000",
  "account": {
    "bankCode": "03",
    "accountNumber": "00123412341234",
    "holderName": "김토페"
  },
  "email": "testmall100@test.com",
  "phoneNumber": "01012341234"
}

서브몰 삭제

* 서브몰 삭제 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

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

submallId에 해당하는 서브몰 정보를 삭제합니다. 서브몰 삭제는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Path 파라미터

subMallId 필수 · string
서브몰의 ID입니다. 최대 길이는 20자입니다.

Response

성공

서브몰 삭제에 성공했다면 삭제된 서브몰 아이디가 문자열로 돌아옵니다. 삭제된 서브몰 ID는 다시 사용할 수 없습니다.

실패

서브몰 삭제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

서브몰 삭제 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/testmall100/delete \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Idempotency-Key: ed54f35c-990f-45f3-9f01-430124ed9d87'

응답

testmall100

Payout 객체

지급대행 정보를 담고 있는 객체입니다.

객체 상세

payoutKey string
하나의 지급대행 건의 키입니다. 최대 길이는 24자입니다.
subMallId nullable · string
서브몰의 ID입니다. 최대 길이는 20자입니다.
payoutDate string
금액이 지급될 날짜와 시간 정보입니다. yyyyMMdd 형식으로 돌아옵니다. (e.g. 20220101)
payoutAmount number
지급할 금액입니다.
account nullable · object
정산 금액을 지급받을 계좌 정보를 담은 객체입니다.
- bankCode string
  은행 숫자 코드입니다. 은행 코드와 증권사 코드를 참고하세요.
- accountNumber string
  지급받을 계좌번호입니다.
- holderName nullable · string
  지급받을 계좌의 예금주입니다. 최대 길이는 60자입니다.
requestedAt string
지급대행을 요청한 날짜와 시간 정보입니다. yyyyMMddHHmmSS 형식으로 돌아옵니다. (e.g. 20220101125959)
status string
지급대행 상태입니다. 아래와 같은 상태 값을 가질 수 있습니다.
- REQUESTED: 지급이 요청된 상태입니다.
- IN_PROGRESS: 지급을 처리하고 있는 상태입니다.
- COMPLETED: 서브몰에 지급이 완료된 상태입니다.
- FAILED: 지급 요청이 실패한 상태입니다.
- CANCELED: 지급 요청을 취소한 상태입니다.
failure nullable · object
지급대행 요청이 실패하면 보내주는 정보입니다. status 필드가 FAILED 일 때만 정보를 보여줍니다.
- code string
  오류 타입을 보여주는 에러 코드입니다. INVALID_ACCOUNT, TRANSFER_FAILED 두 가지 코드만 돌아옵니다.
- message string
  에러 메시지입니다. 에러 발생 이유를 알려줍니다.
transferSummary string
지급대행으로 입금된 금액의 세부 내용(적요)입니다. 서브몰 통장에 표기되는 정보입니다. 최대 길이는 7자입니다.
metadata nullable · object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

지급 가능한 잔액 조회

* 지급 가능한 잔액 조회 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

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

서브몰에 정산하기 전에 상점이 현재 지급할 수 있는 잔액을 먼저 조회합니다. 지급 가능한 잔액 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Response

성공

지급 가능한 잔액 조회에 성공했다면 balance 필드에 잔액 정보가 담긴 객체가 돌아옵니다.

실패

지급 가능한 잔액 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

지급 가능한 잔액 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

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

응답

{
  "balance": 2000000
}

지급대행 요청

* 지급대행 요청 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

POST /v1/payouts/sub-malls/settlements

서브몰 정보를 배열로 보내서 지급대행을 요청합니다. 한 번에 처리할 수 있는 배열의 최대 길이는 1000개입니다. 1000개를 초과하는 경우에는 지급대행이 처리되지 않습니다.

내부 처리로 인해 11:00시-12:00시 사이에는 지급대행 요청을 할 수 없습니다.

지급대행 요청은 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

* 멱등키를 요청 헤더에 추가하면 중복 지급 없이 안전하게 처리됩니다.

Request Body 파라미터

subMallId 필수 · string
서브몰의 ID입니다. 최대 길이는 20자입니다.
payoutDate 필수 · string
정산한 금액을 지급할 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)
payoutAmount 필수 · integer
정산할 금액입니다.
transferSummary string
지급대행으로 입금된 금액의 세부 내용(적요)입니다. 서브몰 통장에 표기되는 정보입니다. 최대 길이는 7자입니다.
metadata object
서브몰과 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 50개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하여야 합니다. key와 value 모두 문자열 형식이어야 합니다.

Response

성공

지급대행 요청에 성공했다면 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' \
  --header 'Idempotency-Key: 82c36b72-99c9-4ee4-a198-2f11f1c1a694' \
  --data '[{"subMallId":"testmall100","payoutAmount":100,"payoutDate":"2022-01-03"},{"subMallId":"testmall200","payoutAmount":200,"payoutDate":"2022-01-03"}]'

응답

[
  {
    "payoutKey": "FPA1000000001",
    "requestId": "102200046000003",
    "subMallId": null,
    "payoutDate": "20221107",
    "payoutAmount": 50,
    "requestedAt": "20221106210031",
    "account": {
        "bankCode": "03",
        "accountNumber": "00123412341234",
        "holderName": null
    },
    "status": "COMPLETED",
    "metadata": null,
    "failure": null,
    "transferSummary": null
  },
  {
    "payoutKey": "FPA1000000002",
    "requestId": "102200046000004",
    "subMallId": null,
    "payoutDate": "20221107",
    "payoutAmount": 50,
    "requestedAt": "20221106210031",
    "account": {
        "bankCode": "20",
        "accountNumber": "X6505636518308",
        "holderName": null
    },
    "status": "COMPLETED",
    "metadata": null,
    "failure": null,
    "transferSummary": null
  }
]

지급대행 요청 취소

* 지급대행 요청 취소 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

POST /v1/payouts/sub-malls/settlements/{payoutKey}/cancel

payoutKey를 Path 파라미터에 추가해서 요청한 지급대행을 취소합니다. 아직 status 값이 REQUESTED인 요청 건만 취소할 수 있습니다.

지급대행 취소는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Path 파라미터

payoutKey 필수 · string
요청한 지급대행 건의 키입니다.

Response

성공

지급대행 취소에 성공했다면 payoutKey에 해당하는 Payout 객체가 돌아옵니다.

실패

지급대행 취소에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

지급대행 요청 취소 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/{payoutKey}/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Idempotency-Key: 5c8656e9-5d1a-4ef3-92ce-8d7220d91f6b'

응답

{
  "payoutKey": "FPA1000000001",
  "requestId": "102200046000003",
  "subMallId": null,
  "payoutDate": "20221107",
  "payoutAmount": 50,
  "requestedAt": "20221106210031",
  "account": {
      "bankCode": "03",
      "accountNumber": "00123412341234",
      "holderName": null
  },
  "status": "CANCELED",
  "metadata": null,
  "failure": null,
  "transferSummary": null
}

지급대행 단건 조회

* 지급대행 단건 조회 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

GET /v1/payouts/sub-malls/settlements/{payoutKey}

payoutKey를 Path 파라미터에 추가해서 조회하고 싶은 한 건의 지급 정보를 조회합니다. 지급대행 단건 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Path 파라미터

payoutKey 필수 · string
하나의 지급대행 건의 키입니다. 최대 길이는 24자입니다.

Response

성공

지급대행 단건 조회에 성공했다면 payoutKey에 해당하는 Payout 객체가 돌아옵니다.

실패

지급대행 단건 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

지급대행 단 건 조회 API에서 발생할 수 있는 에러를 살펴보세요.

요청

curl --request GET \
  --url https://api.tosspayments.com/v1/payouts/sub-malls/settlements/FPA1000000001 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='

응답

{
  "payoutKey": "FPA1000000001",
  "requestId": "102200046000003",
  "subMallId": null,
  "payoutDate": "20221107",
  "payoutAmount": 50,
  "requestedAt": "20221106210031",
  "account": {
      "bankCode": "03",
      "accountNumber": "00123412341234",
      "holderName": null
  },
  "status": "COMPLETED",
  "metadata": null,
  "failure": null,
  "transferSummary": null
}

지급대행 조회

* 지급대행 조회 API는 지급대행 서비스를 계약한 뒤 사용할 수 있습니다.

GET /v1/payouts/sub-malls/settlements

지급대행 요청에서 사용한 payoutDate를 기준으로, 지정한 날짜 사이에 지급되었거나 지급될 예정인 지급대행 건을 조회합니다. 지급대행 조회는 최대 60초가 소요됩니다. 타임아웃 값을 최소 60초로 설정하세요.

Query 파라미터

startDate 필수 · string
조회를 시작하고 싶은 날짜 정보입니다. ISO 8601 형식인 yyyy-MM-dd를 사용합니다. (e.g. 2022-01-01)
endDate 필수 · string
조회를 마치고 싶은 날짜 정보입니다. yyyy-MM-dd ISO 8601 형식입니다. (e.g. 2022-01-01)

Response

성공

지급대행 조회에 성공했다면 각 지급대행 정보를 가지고 있는 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",
    "requestId": "102200046000003",
    "subMallId": null,
    "payoutDate": "20221107",
    "payoutAmount": 50,
    "requestedAt": "20221106210031",
    "account": {
        "bankCode": "03",
        "accountNumber": "00123412341234",
        "holderName": null
    },
    "status": "COMPLETED",
    "metadata": null,
    "failure": null,
    "transferSummary": null
  },
  {
    "payoutKey": "FPA1000000002",
    "requestId": "102200046000004",
    "subMallId": null,
    "payoutDate": "20221107",
    "payoutAmount": 50,
    "requestedAt": "20221106210031",
    "account": {
        "bankCode": "20",
        "accountNumber": "X6505636518308",
        "holderName": null
    },
    "status": "COMPLETED",
    "metadata": null,
    "failure": null,
    "transferSummary": null
  }
]

카드 혜택 조회

카드사별 혜택을 조회합니다. 즉시 할인, 무이자 할부 정보가 내려갑니다.

CardPromotion 객체

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

객체 상세

discountCards array
카드사의 즉시 할인 정보입니다.
- companyCode string
  카드사 숫자 코드입니다. 카드사 코드를 참고하세요.
- discountAmount number
  할인 금액입니다.
- balance number
  남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다.
- discountCode string
  즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다.
- dueDate string
  할인 종료일입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.
- minimumPaymentAmount number
  즉시 할인을 적용할 수 있는 최소 결제 금액입니다.
- maximumPaymentAmount number
  즉시 할인을 적용할 수 있는 최대 결제 금액입니다.
interestFreeCards array
카드사의 무이자 할부 정보입니다.
- companyCode string
  카드사 숫자 코드입니다. 카드사 코드를 참고하세요.
- dueDate string
  무이자 할부 행사 종료일입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.
- installmentFreeMonths array
  무이자 할부를 적용할 수 있는 개월 수 입니다.
- minimumPaymentAmount number
  무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

카드 혜택 조회

GET /v1/promotions/card

카드사별 혜택을 조회합니다. 즉시 할인, 무이자 정보가 내려갑니다.

API 직접 실행해보기

Response

성공

카드사 혜택 조회에 성공했다면 CardPromotion 객체가 돌아옵니다.

실패

카드사 혜택 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청

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

응답

{
    "discountCards": [
      {
        "companyCode": "61",
        "discountAmount": 1000,
        "balance": 100000,
        "discountCode": "001",
        "dueDate": "2021-12-31",
        "maximumPaymentAmount": 50000,
        "minimumPaymentAmount": 10000
      },
      {
        "companyCode": "71",
        "discountAmount": 1000,
        "balance": 100000,
        "discountCode": "002",
        "dueDate": "2021-12-31",
        "maximumPaymentAmount": 50000,
        "minimumPaymentAmount": 10000
      }
    ],
    "interestFreeCards": [
      {
        "companyCode": "11",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "31",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "33",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "35",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "36",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "41",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "46",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "71",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4],
        "minimumPaymentAmount": 50000
      },
      {
        "companyCode": "91",
        "dueDate": "2021-12-31",
        "installmentFreeMonths": [2, 3, 4, 5, 6],
        "minimumPaymentAmount": 50000
      }
    ]
  }

Payment 객체

객체 상세

결제 승인

Request Body 파라미터

Response

paymentKey로 결제 조회

Path 파라미터

Response

orderId로 결제 조회

Path 파라미터

Response

결제 취소

Path 파라미터

Request Body 파라미터

Response

카드 번호 결제

Request Body 파라미터

Response

가상계좌 발급 요청

Request Body 파라미터

Response

자동결제

Billing 객체

객체 상세

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

Request Body 파라미터

Response

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

Request Body 파라미터

Response

카드 자동결제 승인

Path 파라미터

Request Body 파라미터

Response

거래

Transaction 객체

객체 상세

거래 조회

Query 파라미터

Response

정산

Settlement 객체

객체 상세

정산 조회

Query 파라미터

Response

수동 정산 요청

Request Body 파라미터

Response

현금영수증

CashReceipt 객체

객체 상세

현금영수증 발급 요청

Request Body 파라미터

Response

현금영수증 발급 취소 요청

Path 파라미터

Request Body 파라미터

Response

현금영수증 조회

Query 파라미터

Response

지급대행

Submall 객체

객체 상세

서브몰 등록

Request Body 파라미터

Response

서브몰 조회

Response

서브몰 수정

Path 파라미터

Request Body 파라미터

Response

서브몰 삭제

Path 파라미터

Response

Payout 객체

객체 상세

`paymentKey`로 결제 조회

`orderId`로 결제 조회

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

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