토스페이 API 소개

토스를 통한 결제 서비스를 사용하기 위한 API입니다.
토스페이를 활용한 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요!

토스페이 개발 가이드는 수시로 업데이트 됩니다. 사전 예고없이 업데이트 될 수 있으니 지속적으로 확인해 주시길 부탁드립니다.

>> '토스페이 시작하기' 문서로 바로가기


토스페이 서비스를 지원하는 브라우저는 다음과 같습니다.

PC 브라우저, Android, iOS 모두 TLS 1.2 이상의 환경에서 동작이 가능하며, 디바이스 같은 경우 토스 앱의 최소 지원 버전 기준입니다.
토스 앱 최신버전이 아닌 경우, 결제 진행이 원활하지 않을 수 있으니 가급적 최신 버전의 토스앱을 이용해 주시길 부탁드립니다.

  • IE 11, Safari 7, Chrome 38, Firefox 27 부터 지원
  • Android 5.0 Lollipop 부터 지원
  • iOS 11 부터 지원
  • Java 를 사용하시는 경우, jdk 1.8 이상 버전 사용을 권장합니다


토스페이는 iframe 방식을 공식적으로 지원하지 않습니다.
iframe 방식을 이용하는 경우 결제가 원활하지 않을 수 있으므로 페이지 전환방식의 연동을 권장드립니다.


또한, 토스페이는 기본적으로 Server to Server 호출 방식을 지향합니다.
웹 브라우저를 통하여 클라이언트 단에서 토스 도메인으로 직접 결제 API를 호출하는 방식을 사용할 경우,
결제와 관련된 데이터가 외부에 노출되어 보안사고가 발생할 수 있으니 유의해 주시길 부탁드립니다.

결제 상태

결제 건이 생성된 후, 결제가 진행됨에 따라 결제 상태가 변경되며, 각 결제 상태마다 판매자 또는 구매자가 요청할 수 있는 행동도 변합니다. 아래는 결제 상태 목록과 각 상태에 대한 설명입니다.

결제 상태 목록

PAY_STANDBY
결제 대기 중
결제 건이 생성되었고, 구매자의 결제 진행을 대기 중인 상태. 이 상태에서 구매자나 가맹점이 결제를 취소할 수 있습니다. 또한 설정한 '만료 기간'이 도래하면 자동으로 취소됩니다.
PAY_APPROVED
구매자 인증 완료
결제를 위한 구매자 인증 완료되고, 가맹점의 최종 승인을 기다리는 상태.
(결제 생성 시 'autoExecute'를 false로 설정한 경우에만 이 단계를 거칩니다.
이 상태에서도 설정한 결제 '유효기간이 만료'되면 자동으로 취소처리 됩니다.)
PAY_CANCEL
결제 취소
결제가 완료되기 전에 구매자가 결제를 취소하거나 유효기간이 만료된 거래. (결론적으론 금액의 이동 없이 종료된 건)
PAY_PROGRESS
결제 진행 중
구매자가 결제를 승인하여 구매자의 계좌에서 결제 금액을 출금 처리 중인 상태입니다.
PAY_COMPLETE
결제 완료
구매자 및 가맹점의 결제 승인 및 출금이 정상적으로 완료된 상태입니다
REFUND_PROGRESS
환불 진행 중
전액 또는 부분 환불을 진행 중인 상태로, 완료되기 전 까지 다른 환불을 진행할 수 없습니다.
REFUND_SUCCESS
환불 성공
전액 또는 부분 환불이 완료되어, 환불 처리한 금액이 구매자의 계좌로 입금 완료된 상태입니다.
SETTLEMENT_COMPLETE
정산 완료
결제 완료된 금액에 대해 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과)
SETTLEMENT_REFUND_COMPLETE
환불 정산 완료
전액 또는 부분 환불에 대한 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과했거나 전액 환불에 대한 정산 완료된 경우)
              
              
              
              
              
              
            

HTTP 응답 코드

HTTP Response Code

200
OK : 정상
400
Bad Request : 파라미터 오류
401
Unauthorized : 가맹점 key 오류
404
Not Found : 존재하지 않는 요청
50x
Server error : 서버 오류
              
              
              
              
              
              
            

결제 생성

결제 건을 생성합니다.

결제 생성 완료 후, 구매자의 결제 인증을 얻어 완료처리하는 방법은 아래 문서를 참고하세요.
토스페이 시작하기 > 3. 구매자 인증 받기

endpoint

(POST)
https://pay.toss.im/api/v2/payments

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
테스트가 완료되면 운영 오픈 전 반드시 '실 거래용 Key'로 변경 후 체크해주세요!
orderNo string 필수 Max Length: 50
가맹점의 상품 주문번호
주문번호는 50자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다.
주문번호는 매회 유니크한 값으로 활용해 주셔야하며, 구매자 인증완료(PAY_APPROVED) 전의 주문번호는 재사용이 가능합니다.
단, 사용자 인증완료 후에는 재 사용이 불가하며 최초 생성 후 2년이 지난 주문 번호는 재사용이 불가합니다.
테스트와 라이브 환경 사이에서 중복되지 않도록 가맹점의 관리가 필요하며 중복되는 경우 오류가 발생합니다.
productDesc string 필수 Max Length: 255
상품 설명
상품 설명은 공백으로만 설정할 수 없고, 백슬래시(\)와 따옴표(",')를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요.
토스 인코딩 방식 참고사항
retUrl string 필수 Max Length: 255
구매자 인증완료 후 연결할 가맹점 웹페이지 URL
사용자 인증이 완료되는 시점에 인증 데이터와 함께 결제완료 페이지로 이동시킵니다. 이 때, 전달되는 인증 데이터는 아래 링크에서 확인해 보실 수 있습니다. (단, 전달되는 인증 데이터는 결제수단 별로 차이가 있을 수 있습니다.)
구매자 인증완료 참고사항
retCancelUrl string 필수 Max Length: 255
토스페이창에 진입한 사용자가 결제를 중단할때 사용자를 이동시킬 가맹점 취소 페이지
이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 강제로 종료하지 않고 가맹점의 취소 페이지로 이동할 수 있습니다. 구매자 편의를 위하여 반드시 활용해주세요!
구매자가 결제창을 종료한 경우 즉시 가맹점이 설정한 retCancelUrl로 redirect 되며, 토스 서버에서는 강제로 결제상태를 취소처리 합니다.
상점에서 취소거래 구분이 필요하다면 주문번호를 활용하는 등 자체적으로 거래구분 처리 해주세요.
retAppScheme string Max Length: 255
결제 완료 후 연결할 가맹점 측 앱 스킴 값
가맹점의 결제 구현환경이 App to App인 경우 retAppScheme 값을 선언해 주시면 토스페이 완료 후 가맹점 앱으로 redirect 할 수 있습니다.
단, 사용자의 진입점이 앱이 아닌 일반 웹브라우저인 경우 retAppScheme가 포함되어 있다면 이전 브라우저가 뜨지 않아 결제가 완료될 수 없으니 반드시 유념해 주세요.
iOS 앱 결제의 경우 필수 구현을 권장합니다. iOS 특성 상, 자동 앱 전환이 되지 않기 때문에 가맹점 앱 스킴 값을 이 곳에 선언해 주셔야 인증 후 가맹점 앱으로 랜딩됩니다. safari 등 모바일 웹 브라우저에서 자동 전환되지 않는 이슈는 OS 이슈인 점 참고 부탁드립니다. (Ex. testshop://)
토스 앱 가이드 참고사항
autoExecute Max Length: 5
자동 승인 여부 설정
가맹점의 판매 상품에 따라 '자동 승인 설정' 을 활용할 수 있습니다.
true 를 선언한 경우 resultCallback 을 필수 값으로 체크합니다.
자동 승인 설정 참고사항
resultCallback Max Length: 500
결제 결과 callback URL
이 값은 autoExecute를 true로 사용하시는 경우에만 필수 값입니다.
토스 서버가 정상 출금 완료 후 이 곳에 입력한 URL로 성공 결과를 전송하기 때문에 가맹점 서버에서 반드시 확인하셔야 합니다.
callback 데이터가 수신되지 않았다면 네트워크의 문제일 수 있으니 '토스 방화벽 설정' 을 확인해 주세요!
callbackVersion Max Length: 2
결제 결과 callback 버전
이 값은 autoExecute를 true로 사용하시는 경우에만 필수 값입니다.
callback 버전에 따라 전달되는 응답 값이 다를 수 있으니 최신 버전(V2) 이용을 권장합니다. 이 값이 포함되지 않을 경우 기존의 V1 버전의 데이터가 전달됩니다.
V1 : callback 리턴값을 파라미터로 받을 수 있습니다.
V2 : callback 리턴값을 JSON으로 받을 수 있습니다.
amount integer 필수 Max Length: 7
총 결제 금액
금액과 관련된 모든 파라미터는 Number 형태로 보내주셔야 에러가 발생하지 않습니다.
amountTaxFree integer 필수
결제 금액 중 비과세금액
판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수 값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.
amountTaxable Max Length: 7
결제 금액 중 과세금액
별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.
amountVat integer Max Length: 7
결제 금액 중 부가세
값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
amountServiceFee integer Max Length: 7
결제 금액 중 봉사료
expiredTime string Max Length: 20
결제 만료 기한 (기본값 15분, 최대 60분 설정 가능)
형식 : 2020-03-03 12:30:20
enablePayMethods string Max Length: 100
결제수단 구분변수
가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다. 아래 옵션 값에 따라 설정 가능합니다.

TOSS_MONEY 결제수단 중 토스머니만 노출
CARD 결제수단 중 카드만 노출
null 혹은 그 외의 값 상점에 설정된 기본 결제수단으로 노출
cashReceipt boolean Max Length: 5
현금영수증 발급 가능 여부
현금영수증 기능을 활용하시는 경우 true, 미 사용의 경우 false로 선언해 주시기 바랍니다. 그러나, 기본 값이 true이기 때문에 현금영수증 사용 시 별도로 선언하지 않으셔도 됩니다.
토스 머니 결제건에 한해서 현금영수증 발행 여부를 설정할 수 있습니다.
cashReceiptTradeOption string Max Length: 10
현금영수증 발급타입
문화비 관련 상품의 경우, 발급 타입을 설정하여 보내주세요.

CULTURE 문화비
GENERAL 일반(default)
PUBLIC_TP 교통비
cardOptions object
결제창에 특정 카드만 노출하고 싶다면, options 변수에 토스 카드코드를 추가해 주세요. 예를들어, 삼성카드와 현대카드만 결제가 가능하도록 노출을 제어한다면 아래와 같이 토스 카드코드를 넘겨주시면 됩니다.
"cardOptions":
{"options": [{"cardCompanyCode":3},{"cardCompanyCode":5}]}
installment string Max Length: 10
할부 제한 타입
신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다.

USE 할부 사용(default)
NOT_USE 할부 미사용

response

code integer Max Length: 2
응답코드
이 값을 받지 못했다면 가맹점에서 제한하는 방화벽의 이슈일 수 있으니
'토스 방화벽 설정' 을 확인해 주세요!

0 성공
-1 실패 (실패사유는 msg와 errorCode 제공)
checkoutPage string Max Length: 255
결제를 진행할 수 있는 토스페이 웹페이지 URL
토스가 전달한 값 그대로를 구매자에게 띄워주세요.
payToken string Max Length: 30
토스페이 토큰
매회 유니크한 토큰 값이 생성됩니다. 가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다.
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드

COMMON_PAY_ERROR 문제가 발생하였습니다.
COMMON_INVALID_PARAMETER 요청한 값이 바르지 않습니다.
그 외의 에러 코드
Definition
POST https://pay.toss.im/api/v2/payments
Example Request
curl https://pay.toss.im/api/v2/payments \
    -H "Content-Type: application/json" \
    -d '{
        "orderNo":"1",
        "amount":10000,
        "amountTaxFree":0,
        "productDesc":"테스트결제",
        "apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",
        "autoExecute":true,
        "resultCallback":"https://YOUR-SITE.COM/callback",
        "callbackVersion":"V2",
        "retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
        "retCancelUrl": "http://YOUR-SITE.COM/close"
        }'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/payments");
	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("amount", 10000);
	jsonBody.put("amountTaxFree", 0);
	jsonBody.put("productDesc", "테스트 결제");
	jsonBody.put("apiKey", "sk_test_w5lNQylNqa5lNQe013Nq");
    jsonBody.put("autoExecute", true);
    jsonBody.put("resultCallback", "http://"http://YOUR-SITE.COM/callback");
    jsonBody.put("callbackVersion", "V2");  
    jsonBody.put("retUrl", "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1");
    jsonBody.put("retCancelUrl", "http://YOUR-SITE.COM/close");

	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());$arrayBody = array();
$arrayBody["orderNo"] = "1";
$arrayBody["amount"] = 10000;
$arrayBody["amountTaxFree"] = 0;
$arrayBody["productDesc"] = "테스트 결제";
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$arrayBody["autoExecute"] = true;
$arrayBody["resultCallback"] = "http://YOUR-SITE.COM/callback";
$arrayBody["callbackVersion"] = "V2";
$arrayBody["retUrl"] = "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1";
$arrayBody["retCancelUrl"] = "http://YOUR-SITE.COM/close";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v2/payments');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonBody))
);

$result = curl_exec($ch);
curl_close($ch);

echo "Response: ".$result;Dim data, httpRequest, postResponse

data = "apiKey=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&orderNo=1"
data = data & "&amount=10000"
data = data & "&amountTaxFree=0"
data = data & "&productDesc=ASPtestProduct"
data = data & "&autoExecute=true"
data = data & "&resultCallback=http://YOUR-SITE.COM/callback"
data = data & "&callbackVersion=V2"
data = data & "&retUrl=http://YOUR-SITE.COM/ORDER-CHECK?orderno=1"
data = data & "&retCancelUrl=http://YOUR-SITE.COM/close"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v2/payments"
params = {
    "orderNo": "1",
    "amount": 10000,
    "amountTaxFree": 0,
    "productDesc":"테스트 결제",
    "apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
    "autoExecute": true,
    "resultCallback": "http://YOUR-SITE.COM/callback",
    "callbackVersion": "V2",
    "retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
    "retCancelUrl": "http://YOUR-SITE.COM/close"
}

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

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

params = {
        "orderNo" => "1",
        "amount"=> 10000,
        "amountTaxFree"=> 0,
        "productDesc" => "테스트 결제",
        "apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq",
        "autoExecute" => true,
        "resultCallback" => "http://YOUR-SITE.COM/callback",
        "callbackVersion" => "V2",
        "retUrl": "http://YOUR-SITE.COM/ORDER-CHECK?orderno=1",
        "retCancelUrl": "http://YOUR-SITE.COM/close"
}

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)
Example Response
{"code":0,"checkoutPage":"https://pay.toss.im/payfront/auth?payToken=example-payToken","payToken":"example-payToken"}

결제 결과 callback (resultCallback)

결제 처리가 완료되면 결제 상태가 변경되고, 토스는 가맹점 서버로 변경 사항을 알려드립니다.

결제완료 callback을 받았을 때, 결제완료 상태를 변경하시고 재고차감 등의 로직을 처리해 주세요.
자동 승인 설정 시 (autoExecute가 true) 필수적으로 활용해야 합니다.

* callback 연동 전, 방화벽 정보를 반드시 확인해 주세요!
* 생성된 결제 건에 resultCallback 파라미터 값이 있을 경우에만 동작합니다.
* 아래는 callback V2버전이며, 가맹점 측에서는 최신버전의 callback 을 이용해 주시길 부탁드립니다. (callbackVersion 설명참고)
* 사전 예고 없이 field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

parameter

status string Max Length: 20
PAY_COMPLETE
결제 완료
환불 등 '결제 완료' 이외 상태는 전달되지 않습니다.
payToken string Max Length: 30
승인된 결제 토큰
orderNo string Max Length: 50
결제생성 구간에서 전달된 가맹점 주문번호
payMethod string Max Length: 10
승인된 결제수단
카드 승인건의 경우, 카드 데이터가 함께 포함되어 전달됩니다.

TOSS_MONEY 토스머니
CARD 카드
amount integer Max Length: 7
결제요청된 금액
최초 가맹점에서 결제 요청된 금액이 리턴됩니다.
discountedAmount integer Max Length: 7
할인된 금액
할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.
paidAmount integer Max Length: 7
지불수단 승인금액
총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
paidTs string Max Length: 20
결제 완료 처리 시간
형식 : 2020-04-03 14:22:37
transactionId string Max Length: 40
거래 트랜잭션 아이디
결제의 거래구분을 위하여 토스 서버에서 유니크한 값을 생성해서 전달드립니다.
cardCompanyCode integer Max Length: 2
승인된 카드사 코드
cardAuthorizationNo string Max Length: 8
카드 승인번호
spreadOut string Max Length: 8
사용자가 선택한 카드 할부개월
5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
noInterest boolean Max Length: 5
카드 무이자 적용 여부

true 무이자
false 일반
cardMethodType string Max Length: 10
카드 타입
승인된 카드의 타입을 구분할 수 있습니다.

CREDIT 신용카드
CHECK 체크카드
PREPAYMENT 선불카드
cardNumber string Max Length: 20
마스킹된 카드번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
cardUserType string Max Length: 20
카드 사용자 구분

PERSONAL 본인 카드
PERSONAL_FAMILY 가족 카드
CORP_PERSONAL 법인지정 결제계좌 임직원
CORP_PRIVATE 법인 공용
CORP_COMPANY 법인지정 결제계좌 회사(하나카드만)
cardBinNumber string Max Length: 8
카드 BIN 넘버
카드사에서 준 카드 빈번호(마스킹 되어 있을 수 있습니다)
100% 신뢰는 불가

cardNum4Print string Max Length: 4
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod) 이 '카드' 인 경우 카드번호 끝 4자리를 전달(카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
salesCheckLinkUrl string
신용카드 매출전표 호출URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL
accountBankCode string Max Length: 3
은행 코드
사용자가 선택한 결제수단(payMethod) 이 '토스머니' 인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName string Max Length: 20
accountNumber string Max Length: 30
계좌번호
계좌번호는 일부 마스킹을 포함하고 있습니다.

HTTP 응답 코드

HTTP Response Code

200
OK : 정상
400
Bad Request : 파라미터 오류
401
Unauthorized : 가맹점 key 오류
404
Not Found : 존재하지 않는 요청
50x
Server error : 서버 오류
xxx
Server error : 기타 등등
Definition
POST https://YOUR-SITE.COM/callback (결제 생성 시 가맹점에서 설정한 callback URL)
Content-Type application/json;charset=UTF-8
Example Request
{
 "status": "PAY_COMPLETE",
 "payToken": "example-payToken",
 "orderNo": "1",
 "payMethod": "CARD",
 "amount": 3000,
 "discountedAmount": 600,
 "paidAmount": 2300,
 "paidTs": "2020-04-03 14:22:37",
 "transactionId" : "dc3b951a-9781-462e-ab5a-b8a0bea0222a",
 "cardCompanyCode": 3,
 "cardAuthorizationNo": "87654321",
 "spreadOut": 0,
 "noInterest": false,
 "cardMethodType": "CREDIT",
 "cardUserType": "PERSONAL",
 "cardNumber": "654321******1234",
 "cardBinNumber": "654321",
 "cardNum4Print": "1234",
 "salesCheckLinkUrl": "https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=2da1ca05-d91d-410f-976d-7a610242da8a",
 //"paidPoint": 0, // 2020.08.06 이후 fadeout 된 레거시 포인트 금액으로 0원으로 나감
}                            
                        

가맹점 결제 승인

자동 승인 설정을 false로 사용하는 가맹점에서만 처리하는 로직입니다.
구매자 인증 완료 상태(PAY_APPROVED)의 결제 건을 가맹점이 주체가 되어 최종 승인하고 결제를 완료 처리합니다.

결제 승인에 관한 자세한 내용은 아래 문서를 참고하세요.
토스페이 시작하기 > 결제 승인하기

필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 '어떤 결제건'을 최종 승인할지 알려주세요.
필요에 따라 결제건의 유효성 검증을 할 수 있습니다.

* 사전 예고 없이 Response field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

endpoint

(POST)
https://pay.toss.im/api/v2/execute

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
payToken string 필수 Max Length: 30
토스페이 토큰 (승인할 결제 건의 토큰값)
orderNo string Max Length: 50
가맹점의 상품 주문번호
결제 승인 시 orderNo를 함께 보내면 일치 여부를 확인합니다. payToken과 연결된 결제건과 orderNo가 다르면 승인 실패처리하여 다시 한번 유효성을 검증합니다.

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
mode string Max Length: 4
결제환경

LIVE 실거래용
TEST 테스트용
approvalTime string Max Length: 20
결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss)
요청에 따른 결제건 처리 시간입니다. 환불시에도 동일한 변수로 리턴되므로 구분하여 관리하시기 바랍니다.
stateMsg string Max Length: 120
상태 응답 텍스트 값
amount integer Max Length: 7
상품금액
결제 생성 시 요청 된 총 금액
discountedAmount integer Max Length: 7
할인된 금액
할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.
paidAmount integer Max Length: 7
지불수단 승인금액
총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
payMethod string Max Length: 10
결제수단

TOSS_MONEY 토스머니
CARD 카드
orderNo string Max Length: 50
승인된 상품 주문번호
payToken string Max Length: 30
승인된 결제토큰
transactionId string Max Length: 40
거래 트랜잭션 아이디
결제의 거래구분을 위하여 토스서버에서 유니크한 값을 생성해서 전달드립니다. 매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다.
cashReceiptMgtKey string Max Length: 36
현금영수증 관리번호 식별값
국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별 값입니다.
해당 필드 존재로 현금영수증 발급 구분 가능
cardCompanyName string Max Length: 2
승인 카드사명
아래 테이블을 참고해 주세요.
cardCompanyCode integer Max Length: 2
카드사 코드
토스에서 정의한 카드사 코드는 다음과 같으며,
미지원 카드사는 현재 준비중입니다. (매입 카드사 기준입니다.)


cardCompanyName cardCompanyCode
신한 1
현대 2
삼성 3
국민 4
롯데 5
하나 6
우리 7
농협 8
씨티 (현재 미지원) 9
비씨(BC) 10
cardAuthorizationNo string Max Length: 8
구매자가 확인할 수 있는 카드사 승인번호
정상적인 카드사 승인번호는 라이브 키 결제에서 확인하실 수 있습니다.
spreadOut integer Max Length: 2
사용자가 선택한 카드 할부개월
5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
noInterest boolean Max Length: 5
카드 무이자 적용 여부

true 무이자
false 일반
salesCheckLinkUrl string
신용카드 매출전표 호출URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL 입니다. 구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다.
토스 매출전표 참고사항
cardMethodType string Max Length: 10
카드 타입
승인된 카드의 타입을 구분할 수 있습니다. 예를들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해 주세요!

CREDIT 신용카드
CHECK 체크카드
PREPAYMENT 선불카드
cardNumber string Max Length: 20
마스킹된 카드번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
cardUserType string Max Length: 20
카드 사용자 구분

PERSONAL 본인 카드
PERSONAL_FAMILY 가족 카드
CORP_PERSONAL 법인지정 결제계좌 임직원
CORP_PRIVATE 법인 공용
CORP_COMPANY 법인지정 결제계좌 회사(하나카드만)
cardBinNumber string Max Length: 8
카드 BIN 넘버
카드사에서 준 카드 빈번호(마스킹 되어 있을 수 있습니다)
100% 신뢰는 불가

cardNum4Print string Max Length: 4
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod) 이 '카드' 인 경우 카드번호 끝 4자리를 전달(카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
accountBankCode string Max Length: 3
은행 코드
사용자가 선택한 결제수단(payMethod) 이 '토스머니' 인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName string Max Length: 20
accountNumber string Max Length: 30
계좌번호
계좌번호는 일부 마스킹을 포함하고 있습니다.
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드

PAYMENT_EXISTING_PAYMENT 이미 존재하는 결제입니다.
COMMON_INVALID_API_KEY 바르지 않은 API key 입니다.
COMMON_BREAK_TIME_OF_BANK 지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요.
그 외의 에러 코드
Definition
POST https://pay.toss.im/api/v2/execute
Example Request
curl "https://pay.toss.im/api/v2/execute" \
    -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/execute");
	connection = url.openConnection();
	connection.addRequestProperty("Content-Type", "application/json");
	connection.setDoOutput(true);
	connection.setDoInput(true);

	org.json.simple.JSONObject jsonBody = new JSONObject();
	jsonBody.put("payToken", "example-payToken");
	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());$arrayBody = array();
$arrayBody["payToken"] = "example-payToken";
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v2/execute');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonBody))
);

$result = curl_exec($ch);
curl_close($ch);

echo "Response: ".$result;Dim data, httpRequest, postResponse

data = "apiKey=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&payToken=example-payToken"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v2/execute"
params = {
    "payToken": "example-payToken",
    "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/execute")

params = {
        "payToken" => "example-payToken",
        "apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq"
}

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)
Example Response
{
    "code": 0,
    "mode": "LIVE",
    "orderNo": "TossTest20190718",
    "amount": 2000,
    "approvalTime": "2019-07-18 11:28:02",
    "stateMsg": "결제 완료",
    "discountedAmount": 0,
    "paidAmount": 2000,
    "payMethod": "CARD", //"TOSS_MONEY"
    "payToken": "example-payToken",
    "transactionId": "2da1ca05-d91d-410f-976d-7a610242da8a",
   
    //payMethod 가 CARD 일때
    "cardCompanyCode": 3,
    "cardCompanyName": "삼성",
    "cardAuthorizationNo": "87654321",
    "spreadOut": 0,
    "noInterest": false,
    "salesCheckLinkUrl": "https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=2da1ca05-d91d-410f-976d-7a610242da8a",
    "cardMethodType": "CREDIT",
    "cardNumber": "654321******1234"
    "cardUserType": "PERSONAL",
    "cardNum4Print": "1234",
    "cardBinNumber": "654321"

    //payMethod 가 TOSS_MONEY 일때
    //"cashReceiptMgtKey": "0123456-abcd-9abcd0Df",
    //"accountBankCode" : "88",
    //"accountBankName" : "신한은행",
    //"accountNumber" : "110******676"
				
}

            

결제 환불

결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다.
기 환불처리된 거래는 원복이 불가하오니 환불전 반드시 가맹점 측의 체크가 필요합니다.

* 사전 예고 없이 Response field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

endpoint

(POST)
https://pay.toss.im/api/v2/refunds

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
payToken string 필수 Max Length: 30
토스페이 토큰
refundNo string Max Length: 36
환불 번호
미입력 시 자동 생성되며 환불 완료 응답에서 확인 가능합니다.
매회 요청마다 유니크한 값을 사용하시길 권장드립니다.
refundNo를 활용하면 중복 환불요청을 방지할 수 있고, 네트워크나 기타의 이유로 처리 응답을 수신하지 못한 경우 재 활용할 수 있습니다.
idempotent boolean Max Length: 5
멱등성 적용 여부
true : 사용 (default), false : 미사용
멱등성 적용을 원하시는 경우 true, 미 사용의 경우 false로 선언해 주시기 바랍니다.
미입력 시 기본값으로 멱등성이 활성화되어, 동일한 요청을 반복적으로 수행하더라도 동일한 결과인 성공으로 응답("code": 0) 처리됩니다.
reason string Max Length: 255
환불 사유
환불 사유는 한글 및 숫자, 영문자, 특수문자 _-:.^@()[]#/!%?& 만 허용합니다.
amount
환불할 금액
미입력시 환불할 결제건의 남은 전액을 환불 처리하며, 부분환불 시 필수로 amount를 활용해주세요.
만일 즉시할인이 적용된 거래의 부분환불이 필요한 경우, 가맹점에서는 환불이 필요한 총 요청 금액만 전달해 주시면됩니다. 계산은 토스페이 서버에서 자동으로 처리합니다.
amountTaxFree Max Length: 7
환불할 금액 중 비과세금액
환불할 금액중 비과세 금액, 없으면 0으로 설정합니다.
amountTaxable integer Max Length: 7
환불할 금액 중 과세금액
amountVat integer Max Length: 7
환불할 금액 중 부가세
값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
amountServiceFee integer Max Length: 7
환불할 금액 중 봉사료
결제 생성 시 봉사료 설정한 경우에만 입력 가능

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
refundNo string Max Length: 36
환불 번호
환불요청 시 가맹점이 전달한 refundNo로 리턴됩니다. 미 입력 시, 서버에서 자동 생성하며 transactionId 값과 동일한 value 값을 리턴합니다.
refundableAmount integer Max Length: 7
환불 가능 금액
환불 성공 후 남은 환불 가능 금액
discountedAmount integer Max Length: 7
할인된 금액
환불 성공 후 남은 할인적용 금액이 전달되고, 전액 환불이거나 할인 적용이 안되었다면 0 을 리턴합니다.
예를들어, 10% 할인을 받아 10,000원 결제를 9,000에 결제했고, 4,000원을 부분 환불하면 최종적으로 6,000원 결제의 600원 할인을 받은 것이 되므로 discountedAmount 값은 600원으로 리턴됩니다.
가맹점 측에서는 환불요청 금액만 전달해 주시면 되고, 토스페이 서버에서 자동으로 우선순위를 지정하여 할인금액을 차감합니다.
paidAmount integer Max Length: 7
지불수단 승인금액
환불 성공 후 남은 지불수단의 승인금액
refundedAmount integer Max Length: 7
환불요청 금액
가맹점에서 환불 요청시 전달한 amount 금액
refundedDiscountAmount integer Max Length: 7
환불요청 금액 중 실 차감된 즉시할인 금액
환불요청 시 전달한 amount 금액 중 토스 서버에서 자동 차감된 즉시할인 금액으로 차감액이 없으면 0으로 리턴됩니다.
refundedPaidAmount integer Max Length: 7
환불요청 금액 중 실 차감된 지불수단 금액
환불요청 시 전달한 amount 금액 중 토스 서버에서 자동 차감된 지불수단 금액으로 차감액이 없으면 0으로 리턴됩니다.
approvalTime string Max Length: 20
결제건의 환불 처리 시간 (yyyy-MM-dd HH:mm:ss)
cashReceiptMgtKey string Max Length: 36
현금영수증 관리번호 식별값
국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별 값입니다.
해당 필드 존재로 현금영수증 발급 구분 가능
payToken string Max Length: 30
환불된 결제토큰
transactionId string Max Length: 40
거래 트랜잭션 아이디
환불된 거래건의 매출전표 확인을 위하여 필요한 옵션 값이므로 가맹점의 관리가 필요합니다.
cardMethodType string Max Length: 10
카드 타입
승인된 카드의 타입을 구분할 수 있습니다.

CREDIT 신용카드
CHECK 체크카드
PREPAYMENT 선불카드
cardNumber string Max Length: 20
마스킹된 카드번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
cardUserType string Max Length: 20
카드 사용자 구분

PERSONAL 본인 카드
PERSONAL_FAMILY 가족 카드
CORP_PERSONAL 법인지정 결제계좌 임직원
CORP_PRIVATE 법인 공용
CORP_COMPANY 법인지정 결제계좌 회사(하나카드만)
cardBinNumber string Max Length: 8
카드 BIN 넘버
카드사에서 준 카드 빈번호(마스킹 되어 있을 수 있습니다)
100% 신뢰는 불가

cardNum4Print string Max Length: 4
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod) 이 '카드' 인 경우 카드번호 끝 4자리를 전달(카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
salesCheckLinkUrl string
신용카드 매출전표 호출URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL
accountBankCode string Max Length: 3
은행 코드
사용자가 선택한 결제수단(payMethod) 이 '토스머니' 인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName string Max Length: 20
accountNumber string Max Length: 30
계좌번호
계좌번호는 일부 마스킹을 포함하고 있습니다.
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드

INACTIVE_USER 탈퇴한 사용자입니다. 환불이 불가능합니다.
COMMON_REFUND_ERROR 환불이 불가능한 상태입니다.
REFUND_EXCEED_DAILY 환불 금액이 상점의 일일 환불 한도보다 클 수 없습니다.
그 외의 에러 코드
Definition
POST https://pay.toss.im/api/v2/refunds
Example Request
curl "https://pay.toss.im/api/v2/refunds" \
    -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/refunds");
	connection = url.openConnection();
	connection.addRequestProperty("Content-Type", "application/json");
	connection.setDoOutput(true);
	connection.setDoInput(true);

	org.json.simple.JSONObject jsonBody = new JSONObject();
	jsonBody.put("payToken", "example-payToken");
	jsonBody.put("amount", "5000");
	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());$arrayBody = array();
$arrayBody["payToken"] = "example-payToken";
$arrayBody["amount"] = 5000;
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v2/refunds');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonBody))
);

$result = curl_exec($ch);
curl_close($ch);

echo "Response: ".$result;Dim data, httpRequest, postResponse

data = "apiKey=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&payToken=example-payToken"
data = data & "&amount=1000"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v2/refunds"
params = {
    "payToken": "example-payToken",
    "amount": 5000,
    "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/refunds")

params = {
        "payToken" => "example-payToken",
        "amount"=> 5000,
        "apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq"
}

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)
Example Response
{ 
 "code": 0,
 "refundNo": "3243c76e-e9cf-4669-881b-33a3b82ddf49",
 "approvalTime": "2020-04-29 11:32:52",
 "cashReceiptMgtKey": "0123456-abcd-9abcd0Df", 
 "refundableAmount": 2000,
 "discountedAmount": 0,
 "paidAmount": 1000,
 "refundedAmount": -2000,
 "refundedDiscountAmount": 0,
 "refundedPaidAmount": -2000,
 "payToken": "example-payToken",
 "transactionId": "3243c76e-e9cf-4669-881b-33a3b82ddf49"
 "cardMethodType": "CREDIT",
 "cardNumber": "654321******1234"
 "cardUserType": "PERSONAL",
 "cardNum4Print": "1234",
 "cardBinNumber": "654321"

//payMethod 가 TOSS_MONEY 일때
//"cashReceiptMgtKey": "0123456-abcd-9abcd0Df",
//"accountBankCode" : "88",
//"accountBankName" : "신한은행",
//"accountNumber" : "110******676"
				
}


            

결제 상태 확인

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

* 사전 예고 없이 Response field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

endpoint

(POST)
https://pay.toss.im/api/v2/status

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
payToken 또는 orderNo string 필수 Max Length: 50
토스페이 토큰 또는 가맹점 주문번호

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
mode string Max Length: 4
결제환경

LIVE 실거래용
TEST 테스트용
payToken string Max Length: 30
토스페이 토큰
상태조회가 필요한 거래건의 결제토큰을 입력해 주세요.
payStatus string Max Length: 30
결제 상태

PAY_STANDBY 결제 대기 중
PAY_APPROVED 구매자 인증 완료
PAY_CANCEL 결제 취소
PAY_PROGRESS 결제 진행 중
PAY_COMPLETE 결제 완료
REFUND_PROGRESS 환불 진행 중
REFUND_SUCCESS 환불 성공
SETTLEMENT_COMPLETE 정산 완료
SETTLEMENT_REFUND_COMPLETE 환불 정산 완료
orderNo string Max Length: 50
토스페이와 연계된 상점 주문번호
payMethod string Max Length: 10
결제수단

TOSS_MONEY 토스머니
CARD 카드
amount integer Max Length: 7
가맹점이 토스로 전달한 결제 총 금액
discountedAmount integer Max Length: 7
할인된 금액
할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.
discountAmountV2 integer Max Length: 7
즉시 할인 적용 금액
토스페이 창에서 자동으로 적용된 즉시할인 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.
paidPointV2 integer Max Length: 7
토스 포인트 사용금액
결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0 으로 리턴됩니다.
paidAmount integer Max Length: 7
지불수단 승인금액
가맹점이 요청한 총 금액(amount) 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다.
토스 자동발행 현금영수증을 사용하지 않는 가맹점에서는 이 필드를 통해 현금영수증 발행처리 해주시면 됩니다.
refundableAmount integer Max Length: 7
환불 가능 잔액
환불 성공 후 남은 환불 가능 금액
amountTaxFree integer Max Length: 7
총 결제 금액 중 적용된 비과세 금액
amountTaxable integer Max Length: 7
총 결제 금액 중 적용된 과세 금액
결제생성에서 비과세 금액(amountTaxFree) 을 0으로 보내주시면 토스 서버에서 자동으로 과세처리 하고, 해당 필드로 적용사항을 확인해 볼 수 있습니다.
amountVat integer Max Length: 7
총 결제 금액 중 적용된 부가세 금액
결제생성에서 비과세 금액(amountTaxFree) 을 0으로 보내주시면 토스 서버에서 자동으로 과세처리 하고, 해당 필드로 적용사항을 확인해 볼 수 있습니다.
amountServiceFee integer Max Length: 7
총 결제 금액 중 적용된 봉사료
disposableCupDeposit integer Max Length: 7
일회용 컵 보증금
accountBankCode string Max Length: 3
은행 코드
사용자가 선택한 결제수단(payMethod) 이 '토스머니' 인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName string Max Length: 20
accountNumber string Max Length: 30
계좌번호
계좌번호는 일부 마스킹을 포함하고 있습니다.
card list
조회건이 카드 결제일 경우에만 내려가는 카드정보
noInterest boolean Max Length: 5
카드 무이자 적용 여부

true 무이자
false 일반
spreadOut integer Max Length: 2
사용자가 선택한 카드 할부개월
5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
cardCompanyName string Max Length: 2
승인 카드사명
cardCompanyCode integer Max Length: 2
카드사 코드
cardAuthorizationNo string Max Length: 8
구매자가 확인할 수 있는 카드사 승인번호
cardMethodType string Max Length: 10
카드 타입
승인된 카드의 타입을 구분할 수 있습니다. 예를들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해 주세요!
CREDIT 신용카드
CHECK 체크카드
PREPAYMENT 선불카드
cardUserType string Max Length: 20
카드 사용자 구분

PERSONAL 본인 카드
PERSONAL_FAMILY 가족 카드
CORP_PERSONAL 법인지정 결제계좌 임직원
CORP_PRIVATE 법인 공용
CORP_COMPANY 법인지정 결제계좌 회사(하나카드만)
cardNumber string Max Length: 20
마스킹된 카드번호
카드번호 16자리 중 중간자리는 마스킹됩니다.
cardBinNumber string Max Length: 8
카드 BIN 넘버
카드사에서 준 카드 빈번호(마스킹 되어 있을 수 있습니다)
100% 신뢰는 불가

cardNum4Print string Max Length: 4
사용자가 선택한 카드의 끝 4자리
사용자가 선택한 결제수단(payMethod) 이 '카드' 인 경우 카드번호 끝 4자리를 전달(카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
salesCheckLinkUrl string
신용카드 매출전표 호출URL
transactions list
거래 트랜잭션
stepType string Max Length: 7
요청된 거래 타입

PAY 결제
REFUND 환불
transactionId string Max Length: 40
거래 트랜잭션 아이디
결제의 거래구분을 위하여 토스 서버에서 유니크한 값을 생성해서 전달드립니다. 거래 대사 시, 이 값을 활용하시길 권장드립니다.
transactionAmount integer Max Length: 7
요청된 거래 타입(stepType) 의 가맹점 전달금액
가맹점에서 전달한 요청 금액이 리턴됩니다.
'환불' 요청의 경우 -(마이너스) 금액이 리턴됩니다.
discountedAmount integer Max Length: 7
요청된 거래 타입(stepType) 중 적용된 할인금액
할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.
paidAmount integer Max Length: 7
요청된 거래 타입(stepType) 중 적용된 지불수단 금액
예를들어, '환불(REFUND)' 요청 이라면 환불 요청된 금액 중 실제 환불 처리된 지불수단 금액이 리턴됩니다.
regTs string Max Length: 20
요청 처리 시간
createdTs string Max Length: 20
사용자 최초 결제 요청 시간
결제 생성 시간
paidTs string Max Length: 20
결제 완료 처리 시간
Definition
POST https://pay.toss.im/api/v2/status
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());$arrayBody = array();
$arrayBody["orderNo"] = "1";
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$jsonBody = json_encode($arrayBody);
// echo "Request: ".$request."
"; $ch = curl_init('https://pay.toss.im/api/v2/status'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($jsonBody)) ); $result = curl_exec($ch); curl_close($ch); echo "Response: ".$result;
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 postResponseimport 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)
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"
}