API 명세서
공통 API
결제 상태 확인

결제 상태 확인

생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다.
상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다.

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

엔드포인트

POSThttps://pay.toss.im/api/v2/status

요청 파라미터

apiKeystring필수
maxLen: 30

가맹점 API Key

웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.

payToken 또는 orderNostring필수
maxLen: 50

토스페이 토큰 또는 가맹점 주문번호

토스페이 토큰 또는 가맹점 주문번호

Example Request

curl "https://pay.toss.im/api/v2/status" \
 -H "Content-Type: application/json" \
 -d '{
"payToken":"example-payToken",
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq"
}'

응답 파라미터

codeinteger
maxLen: 2

응답코드

값설명
0성공
-1실패 (실패사유는 msg와 errorCode로 제공)
modestring
maxLen: 4

결제환경

값설명
LIVE실거래용
TEST테스트용
payTokenstring
maxLen: 30

토스페이 토큰

상태조회가 필요한 거래건의 결제토큰을 입력해 주세요.

payStatusstring
maxLen: 30

결제 상태

값설명
PAY_STANDBY결제 대기 중
PAY_APPROVED구매자 인증 완료
PAY_CANCEL결제 취소
PAY_PROGRESS결제 진행 중
PAY_COMPLETE결제 완료
REFUND_PROGRESS환불 진행 중
REFUND_SUCCESS환불 성공
SETTLEMENT_COMPLETE정산 완료
SETTLEMENT_REFUND_COMPLETE환불 정산 완료
orderNostring
maxLen: 50

토스페이와 연계된 상점 주문번호

payMethodstring
maxLen: 10

결제수단

값설명
TOSS_MONEY토스머니
CARD카드
amountinteger
maxLen: 7

가맹점이 토스로 전달한 결제 총 금액

discountedAmountinteger
maxLen: 7

할인된 금액

할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.

discountAmountV2integer
maxLen: 7

즉시 할인 적용 금액

토스페이 창에서 자동으로 적용된 즉시할인 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.

paidPointV2integer
maxLen: 7

토스 포인트 사용금액

결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0으로 리턴됩니다.

paidAmountinteger
maxLen: 7

지불수단 승인금액

가맹점이 요청한 총 금액(amount) 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다.


토스 자동발행 현금영수증을 사용하지 않는 가맹점에서는 이 필드를 통해 현금영수증 발행처리 해주시면 됩니다.

refundableAmountinteger
maxLen: 7

환불 가능 잔액

환불 성공 후 남은 환불 가능 금액

amountTaxFreeinteger
maxLen: 7

총 결제 금액 중 적용된 비과세 금액

amountTaxableinteger
maxLen: 7

총 결제 금액 중 적용된 과세 금액

결제생성에서 비과세 금액(amountTaxFree)을 0으로 보내주시면 토스 서버에서 자동으로 과세처리 하고, 해당 필드로 적용사항을 확인해 볼 수 있습니다.

amountVatinteger
maxLen: 7

총 결제 금액 중 적용된 부가세 금액

결제생성에서 비과세 금액(amountTaxFree)을 0으로 보내주시면 토스 서버에서 자동으로 과세처리 하고, 해당 필드로 적용사항을 확인해 볼 수 있습니다.

amountServiceFeeinteger
maxLen: 7

총 결제 금액 중 적용된 봉사료

disposableCupDepositinteger
maxLen: 7

일회용 컵 보증금

accountBankCodestring
maxLen: 3

은행 코드

사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.

accountBankNamestring
maxLen: 20

은행 명

은행코드 리스트

accountNumberstring
maxLen: 30

계좌번호

계좌번호는 일부 마스킹을 포함하고 있습니다.

cardobject

카드 정보

조회건이 카드 결제일 경우에만 내려가는 카드정보

noInterestboolean
maxLen: 5

카드 무이자 적용 여부

값설명
true무이자
false일반
spreadOutinteger
maxLen: 2

사용자가 선택한 카드 할부개월

5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.

cardCompanyNamestring
maxLen: 2

승인 카드사명

cardCompanyCodeinteger
maxLen: 2

카드사 코드

cardAuthorizationNostring
maxLen: 8

구매자가 확인할 수 있는 카드사 승인번호

cardMethodTypestring
maxLen: 10

카드 타입

승인된 카드의 타입을 구분할 수 있습니다. 예를들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해 주세요!

값설명
CREDIT신용카드
CHECK체크카드
PREPAYMENT선불카드
cardUserTypestring
maxLen: 20

카드 사용자 구분

값설명
PERSONAL본인 카드
PERSONAL_FAMILY가족 카드
CORP_PERSONAL법인지정 결제계좌 임직원
CORP_PRIVATE법인 공용
CORP_COMPANY법인지정 결제계좌 회사(하나카드만)
cardNumberstring
maxLen: 20

마스킹된 카드번호

카드번호 16자리 중 중간자리는 마스킹됩니다.

cardBinNumberstring
maxLen: 8

카드 BIN 넘버

카드사에서 준 카드 빈번호(마스킹 되어 있을 수 있습니다). 100% 신뢰는 불가합니다.

cardNum4Printstring
maxLen: 4

사용자가 선택한 카드의 끝 4자리

사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드번호 끝 4자리를 전달(카드사에 따라 마스킹이 포함되어 있을 수 있습니다)

salesCheckLinkUrlstring
maxLen: 255

신용카드 매출전표 호출URL

transactionslist

거래 트랜잭션

stepTypestring
maxLen: 7

요청된 거래 타입

값설명
PAY결제
REFUND환불
transactionIdstring
maxLen: 36

거래 트랜잭션 아이디

결제의 거래구분을 위하여 토스 서버에서 유니크한 값을 생성해서 전달드립니다. 거래 대사 시, 이 값을 활용하시길 권장드립니다.

transactionAmountinteger
maxLen: 7

요청된 거래 타입(stepType)의 가맹점 전달금액

가맹점에서 전달한 요청 금액이 리턴됩니다. '환불' 요청의 경우 -(마이너스) 금액이 리턴됩니다.

discountedAmountinteger
maxLen: 7

요청된 거래 타입(stepType) 중 적용된 할인금액

할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.

paidAmountinteger
maxLen: 7

요청된 거래 타입(stepType) 중 적용된 지불수단 금액

예를들어, '환불(REFUND)' 요청이라면 환불 요청된 금액 중 실제 환불 처리된 지불수단 금액이 리턴됩니다.

regTsstring
maxLen: 20

요청 처리 시간

createdTsstring
maxLen: 20

사용자 최초 결제 요청 시간

결제 생성 시간

paidTsstring
maxLen: 20

결제 완료 처리 시간

Example Response

{
  "code": 0,
  "mode": "LIVE",
  "payToken": "rDgrfe4YRBnTNLo5lwpqb9",
  "orderNo": "TEST-2023-02-09T06:44:04.217Z",
  "payStatus": "PAY_COMPLETE",
  "payMethod": "CARD",
  "amount": 1000,
  "discountedAmount": 0,
  "discountAmountV2": 0,
  "paidPointV2": 0,
  //"paidPoint": 0, // 2020.08.06 이후 fadeout 된 레거시 포인트 금액으로 0원으로 응답
  "paidAmount": 1000,
  "refundableAmount": 1000,
  "amountTaxable": 909,
  "amountTaxFree": 0,
  "amountVat": 91,
  "amountServiceFee": 0,
  "disposableCupDeposit": 0,
  // payMethod 가 TOSS_MONEY 일때
  // "accountBankCode" : "88",
  // "accountBankName" : "신한은행",
  // "accountNumber" : "110**\*\***676",
  "card": {
    "noInterest": false,
    "spreadOut": 0,
    "cardAuthorizationNo": "30019610",
    "cardMethodType": "CREDIT",
    "cardUserType": "PERSONAL",
    "cardNumber": "557042******700*",
    "cardBinNumber": "557042",
    "cardNum4Print": "700*",
    "salesCheckLinkUrl": "https://staging.toss.im/payfront/web/external/sales-check?payToken=rDgrfe4YRBnTNLo5lwpqb9&transactionId=81a6bafc-b7b6-4959-82ba-e74034f379ea",
    "cardCompanyName": "국민",
    "cardCompanyCode": 4
  },
  "transactions": [
    {
      "stepType": "PAY",
      "transactionId": "81a6bafc-b7b6-4959-82ba-e74034f379ea",
      "paidAmount": 1000,
      "transactionAmount": 1000,
      "discountedAmount": 0,
      "pointAmount": 0,
      "regTs": "2023-02-09 15:44:25"
    }
  ],
  "createdTs": "2023-02-09 15:44:04",
  "paidTs": "2023-02-09 15:44:24"
}
결제 환불소개