토스페이 연동가이드

결제 상태 확인

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

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

엔드포인트

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

요청 파라미터

apiKeystring필수

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

payToken 또는 orderNostring필수

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

응답 파라미터

codeinteger

응답코드

가능한 값:
0성공
-1실패 (실패사유는 msg와 errorCode로 제공)
modestring

결제환경

가능한 값:
LIVE실거래용
TEST테스트용
payTokenstring

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

payStatusstring

결제 상태

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

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

payMethodstring

결제수단

가능한 값:
TOSS_MONEY토스머니
CARD카드
amountinteger

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

discountedAmountinteger

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

discountAmountV2integer

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

paidPointV2integer

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

paidAmountinteger

지불수단 승인금액. 가맹점이 요청한 총 금액(amount) 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 토스 자동발행 현금영수증을 사용하지 않는 가맹점에서는 이 필드를 통해 현금영수증 발행처리 해주시면 됩니다.

refundableAmountinteger

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

amountTaxFreeinteger

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

amountTaxableinteger

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

amountVatinteger

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

amountServiceFeeinteger

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

disposableCupDepositinteger

일회용 컵 보증금

accountBankCodestring

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

accountBankNamestring

은행 명. [은행코드 리스트](/docs/qna.html#faq-8)

accountNumberstring

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

cardobject

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

noInterestboolean

카드 무이자 적용 여부

가능한 값:
true무이자
false일반
spreadOutinteger

사용자가 선택한 카드 할부개월. 5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.

cardCompanyNamestring

승인 카드사명

cardCompanyCodeinteger

카드사 코드. 자세한 내용은 [카드 코드](/guide/card-code)를 참조해주세요.

cardAuthorizationNostring

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

cardMethodTypestring

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

가능한 값:
CREDIT신용카드
CHECK체크카드
PREPAYMENT선불카드
cardUserTypestring

카드 사용자 구분

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

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

cardBinNumberstring

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

cardNum4Printstring

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

salesCheckLinkUrlstring

신용카드 매출전표 호출URL

transactionslist

거래 트랜잭션

stepTypestring

요청된 거래 타입

가능한 값:
PAY결제
REFUND환불
transactionIdstring

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

transactionAmountinteger

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

discountedAmountinteger

요청된 거래 타입(stepType) 중 적용된 할인금액. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.

paidAmountinteger

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

regTsstring

요청 처리 시간

createdTsstring

사용자 최초 결제 요청 시간. 결제 생성 시간

paidTsstring

결제 완료 처리 시간

예제

Example Request

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

URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
url = new URL("https://pay.toss.im/api/v2/status");
connection = url.openConnection();
connection.addRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
connection.setDoInput(true);

    org.json.simple.JSONObject jsonBody = new JSONObject();
    jsonBody.put("orderNo", "1");
    jsonBody.put("apiKey", "sk_test_w5lNQylNqa5lNQe013Nq");

    BufferedOutputStream bos = new BufferedOutputStream(connection.getOutputStream());
    bos.write(jsonBody.toJSONString().getBytes(StandardCharsets.UTF_8));
    bos.flush();
    bos.close();

    BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8));
    String line = null;
    while ((line = br.readLine()) != null) {
        responseBody.append(line);
    }
    br.close();

} catch (Exception e) {
responseBody.append(e);
}
System.out.println(responseBody.toString());
import urllib, urllib2

url = "https://pay.toss.im/api/v2/status"
params = {
    "orderNo": "1",
    "apiKey": "sk_test_w5lNQylNqa5lNQe013Nq"
}

response = urllib.urlopen(url, urllib.urlencode(params))
print(response.read())
require 'net/http'
require 'json'

uri = URI.parse("https://pay.toss.im/api/v2/status")

params = {
        "orderNo" => "1",
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request.set_form_data(params)
response = http.request(request)

p JSON.parse(response.body)
Dim data, httpRequest, postResponse

data = "apiKey=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&orderNo=1"

Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v2/status", False
httpRequest.SetRequestHeader "Content-Type", "application/json"
httpRequest.Send data

postResponse = httpRequest.ResponseText

Response.Write postResponse

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