토스 결제 API 소개

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

>> '토스 결제 시작하기' 문서로 바로가기


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

PC 브라우저, Android, iOS 모두 TLS 1.1 이상의 환경에서 동작이 가능하며, 디바이스 같은 경우 토스 앱의 최소 지원 버전 기준입니다.

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


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

결제 상태

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

생성된 결제의 현재 상태를 파악하려면 결제 상태 확인 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/v1/payments

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
테스트가 완료되면 운영 오픈 전 반드시 '실 거래용 Key'로 변경 후 체크해주세요!
orderNo string 필수 Max Length: 50
가맹점의 상품 주문번호
주문번호는 50자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다.
가맹점 주문번호 테스트와 라이브 환경 사이에서 중복되지 않도록 가맹점의 관리가 필요합니다. 중복되는 경우 오류가 발생합니다.
productDesc string 필수 Max Length: 255
상품 설명
상품 설명은 공백으로만 설정할 수 없고, 백슬래시(\)와 따옴표(",')를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요.
retUrl string 필수 Max Length: 255
Web 결제 완료 후 연결할 웹페이지의 URL (결제 최종 승인 및 완료 처리할 페이지)
결제 완료 화면으로의 이동일 뿐, 정확한 결제 성공 유무를 보장할 수 없으니 반드시 resultCallback 을 통하여 처리하시기 바랍니다.
retCancelUrl string 필수 Max Length: 255
토스 브릿지 페이지에서 사용자가 결제를 중단할때 사용자를 이동시킬 가맹점 페이지
이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 종료하지 않고 취소 버튼을 통하여 가맹점이 설정한 URL로 redirect됩니다.
구매자 편의를 위하여 반드시 활용해주세요!
구매자가 결제창을 종료한 경우, 가맹점이 설정한 URL로 redirect 되며 결제의 상태 또한 토스서버에서 자동 취소처리 합니다.
retAppScheme string Max Length: 255
App 결제 완료 후 연결할 앱 스킴 값 (결제 최종 승인 및 완료 처리할 페이지)
가맹점의 결제 구현환경이 App to App인 경우 retAppScheme을 선언해 주시고, Web인 경우 retUrl을 활용해 주세요.
앱 결제를 이용하는 경우를 대비하여 이 곳에 가맹점 앱 스킴값을 적용하면, 결제 완료 후 토스앱 이동의 이탈을 막고 가맹점 앱으로 redirect 됩니다.
iOS 앱 결제의 경우 필수 구현을 권장합니다. iOS 특성 상, 자동 앱 전환이 되지 않기 때문에 가맹점 앱 스킴 값을 이 곳에 선언해 주셔야 인증 후 가맹점 앱으로 랜딩됩니다.
토스 앱 가이드 참고사항
autoExecute boolean 필수 Max Length: 5
자동 승인 여부 설정
true 를 사용하는 경우, 구매자 인증이 완료되면 토스가 알아서 승인을 진행합니다. 가맹점의 판매 상품에 따라 활용해 주시면 됩니다.
resultCallback string 필수 Max Length: 255
결제 결과 callback URL
토스 서버가 정상 출금 완료 후 이 곳에 입력한 URL로 성공 결과를 전송하기 때문에 가맹점 서버에서 반드시 확인하셔야 합니다.
callback URL에 80, 443 이외의 port가 포함되면 이용할 수 없으니 유의해주세요.
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
결제 만료 기한 (기본값 10분, 최대 1시간 설정 가능)
형식 : 1970-01-01 00:00:00
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 교통비
metadata string Max Length: 1024
결제와 연관된 추가 데이터
cardOptions Object
결제창에 특정 카드만 노출하고 싶다면, options 변수에 토스 카드코드를 추가해 주세요. 예를들어, 삼성카드와 현대카드만 결제가 가능하도록 노출을 제어한다면 아래와 같이 토스 카드코드를 넘겨주시면 됩니다. "cardOptions": {"options": [{"cardCompanyCode":3},{"cardCompanyCode":5}]}

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode 제공)
checkoutPage string Max Length: 255
생성된 결제를 진행하는 웹페이지 URL (구매자를 이 URL로 보내야 함)
토스가 전달한 값 그대로 사용하세요.
payToken string Max Length: 30
Toss 결제 토큰
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드

COMMON_PAY_ERROR 문제가 발생하였습니다.
COMMON_INVALID_PARAMETER 요청한 값이 바르지 않습니다.
그 외의 에러 코드
Definition
POST https://pay.toss.im/api/v1/payments
Example Request
curl https://pay.toss.im/api/v1/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",
        "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/v1/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("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["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/v1/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 & "&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/v1/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/v1/payments"
params = {
    "orderNo": "1",
    "amount": 10000,
    "amountTaxFree": 0,
    "productDesc":"테스트 결제",
    "apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
    "autoExecute": true,
    "resultCallback": "http://YOUR-SITE.COM/callback",
    "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/v1/payments")

params = {
        "orderNo" => "1",
        "amount"=> 10000,
        "amountTaxFree"=> 0,
        "productDesc" => "테스트 결제",
        "apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq",
        "autoExecute" => true,
        "resultCallback" => "http://YOUR-SITE.COM/callback",
        "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 파라미터 값이 있을 경우에만 동작합니다.
* 사전 예고 없이 field 가 추가될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.

parameter

status string Max Length: 20
PAY_SUCCESS
결제완료
payToken string Max Length: 30
Toss 결제 토큰
orderNo string Max Length: 50
Toss 결제와 이어진 주문번호
payMethod string Max Length: 10
결제수단

TOSS_MONEY 토스머니
CARD 카드
discountedAmount integer Max Length: 7
할인된 금액
할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.
paidPoint integer Max Length: 7
토스 포인트 사용금액
결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0 으로 리턴됩니다.
paidAmount integer Max Length: 7
지불수단 승인금액
총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
paidTs string Max Length: 20
결제 처리 시각
형식 : 2019-06-17 14:22:37
metadata string Max Length: 1024
결제 생성 시 저장한 연관 정보

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/x-www-form-urlencoded;charset=UTF-8
Example Request
{
 "status": "PAY_SUCCESS",
 "payToken": "example-payToken",
 "orderNo": "1",
 "payMethod": "TOSS_MONEY",
 "discountedAmount": 600,
 "paidPoint": 100,
 "discountedAmount": 300,
 "paidTs": "2019-06-17 13:59:59"
}                            
                        

가맹점 결제 승인

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

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

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

* 카드결제는 실 카드사 통신을 위하여 Live ApiKey로 진행하셔야 정상결과를 확인하실 수 있습니다.
* 사전 예고 없이 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로 제공)
approvalTime string Max Length: 20
결제건의 승인 처리 시각 (yyyy-MM-dd HH:mm:ss)
요청에 따른 결제건 처리 시각입니다. 환불시에도 동일한 변수로 리턴되므로 구분하여 관리하시기 바랍니다.
amount integer Max Length: 7
승인한 결제 금액
discountedAmount integer Max Length: 7
할인된 금액
할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.
paidPoint 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
결제 트랜잭션 코드
결제의 거래구분을 위하여 토스서버에서 유니크한 값을 생성해서 전달드립니다. 매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다.
cardCompanyName string Max Length: 2
결제 카드사명
cardCompanyCode integer Max Length: 2
결제 카드사 코드
그 외의 카드사는 현재 준비중이며, 카드사 추가될 경 예고없이 업데이트 될 수 있습니다.

cardCompanyName cardCompanyCode
신한 1
현대 2
삼성 3
국민 (현재 미지원) 4
롯데 5
하나 6
우리 (현재 미지원) 7
농협 (현재 미지원) 8
씨티 (현재 미지원) 9
비씨 10
cardAuthorizationNo integer Max Length: 8
구매자가 확인할 수 있는 카드사 승인번호
spreadOut integer Max Length: 2
카드 할부개월
일시불 결제의 경우 0으로 리턴됩니다.
noInterest boolean Max Length: 5
무이자 여부
true : 무이자, false : 일반
salesCheckLinkUrl string
신용카드 매출전표 호출URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL 입니다. 구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다.
토스 매출전표 참고사항
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",
    "discountedAmount": 0,
    "paidPoint": 0,
    "paidAmount": 2000,
    "payMethod": "CARD",
    "payToken": "example-payToken",
    "transactionId": "2da1ca05-d91d-410f-976d-7a610242da8a",
    "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"
}

            

결제 취소

결제 대기 중인 결제 건을 취소합니다. (결제가 완료되어 구매자의 계좌에서 출금된 상태에서는 취소할 수 없으며 환불 처리해야 합니다)

endpoint

(POST)
https://pay.toss.im/api/v1/cancel

parameters

apiKey string 필수 Max Length: 30
가맹점 key
웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
payToken string 필수 Max Length: 30
Toss 결제 토큰
reason string Max Length: 50
취소 사유

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드
Definition
POST https://pay.toss.im/api/v1/cancel
Example Request
curl "https://pay.toss.im/api/v1/cancel" \
    -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/v1/cancel");
	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("reason", "재고 부족");
	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["reason"] = "재고 부족";
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v1/cancel');
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 & "&reason=SoldOut"
​
Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v1/cancel", False
httpRequest.SetRequestHeader "Content-Type", "application/x-www-form-urlencoded"
httpRequest.Send data
​
postResponse = httpRequest.ResponseText
​
Response.Write postResponse
import urllib, urllib2

url = "https://pay.toss.im/api/v1/cancel"
params = {
    "payToken": "example-payToken",
    "reason":"재고 부족",
    "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/v1/cancel")

params = {
        "payToken" => "example-payToken",
        "reason" => "재고 부족",
        "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}
            

결제 환불

결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다.

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: 40
환불 번호
미입력 시 자동 생성되며 환불 완료 응답에서 확인 가능합니다.
매회 요청마다 유니크한 값을 사용하시길 권장드립니다.
reason string Max Length: 50
환불 사유
amount integer 필수
환불할 금액
미입력시 환불할 결제건의 남은 전액을 환불 처리
amountTaxFree integer 필수 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: 40
환불 번호
환불요청 시 가맹점이 전달한 refundNo로 리턴됩니다. 미 입력 시, 서버에서 자동 생성하며 transactionId 값과 동일한 value 값을 리턴합니다.
refundableAmount integer Max Length: 7
환불 가능 금액
환불 성공 후 남은 환불 가능 금액
discountedAmount integer Max Length: 7
할인된 금액
결제 시 할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.
부분 환불 시 discountedAmount 값은 부분 환불 이후의 최종적으로 할인된 금액입니다.
예를들어, 10% 할인을 받아 10,000원 결제를 9,000에 결제했고, 4,000원을 부분 환불하면 최종적으로 6,000원 결제의 600원 할인을 받은 것이 되므로 discountedAmount 값은 600원으로 리턴됩니다.
할인 속성에 따라 부분환불 가능 최소 금액이 설정되어 있을 수 있으며, 최소 금액을 초과하여 환불을 진행하시는 경우 오류가 발생할 수 있습니다.
paidPoint integer Max Length: 7
토스 포인트 잔액
환불 성공 후 남은 포인트 잔액
paidAmount integer Max Length: 7
지불수단 승인금액
환불 성공 후 남은 지불수단의 승인금액
approvalTime string Max Length: 20
결제건의 환불 처리 시각 (yyyy-MM-dd HH:mm:ss)
payToken string Max Length: 30
환불된 결제토큰
transactionId string Max Length: 40
결제 트랜잭션 코드
환불된 거래건의 매출전표 확인을 위하여 필요한 옵션 값이므로 가맹점의 관리가 필요합니다.
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": "2019-07-18 11:32:52",
 "refundableAmount": 0,
 "discountedAmount": 0,
 "paidPoint": 0,
 "paidAmount": 2000,
 "payToken": "example-payToken",
 "transactionId": "3243c76e-e9cf-4669-881b-33a3b82ddf49"
}


            

결제 상태 확인

생성된 결제의 현재 상태를 조회합니다.

endpoint

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

parameters

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

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
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
토스 결제와 이어진 주문번호
amount integer Max Length: 7
결제 금액
amountTaxable integer Max Length: 7
결제 금액 중 과세금액 (복합과세)
amountTaxFree integer Max Length: 7
결제 금액 중 비과세금액 (복합과세)
amountVat integer Max Length: 7
결제 금액 중 부가세 (복합과세)
amountServiceFee integer Max Length: 7
결제 금액 중 봉사료 (복합과세)
timeCreated string Max Length: 7
결제 생성 시각
timePayComplete string Max Length: 20
결제 완료 시각
timePayCancel string Max Length: 20
결제 취소 시각
productDesc string Max Length: 255
상품 설명
availableActions list
가능한 액션 목록

CANCEL 결제 취소
REFUND 결제 환불
refunds list
조회한 결제건에 대한 환불 요청 및 결과
timeRefundSuccess string Max Length: 20
환불 완료 시각
metadata string Max Length: 1024
결제와 연관된 추가 데이터
msg string Max Length: 120
응답이 성공이 아닌 경우 설명 메세지
errorCode string Max Length: 40
에러 코드
payMethod string Max Length: 10
결제수단

TOSS_MONEY 토스머니
CARD 카드
cardCompanyName string Max Length: 2
결제 카드사명
카드 결제의 경우에만 리턴
테스트용 apiKey로 결제 진행 시 리턴되지 않습니다.
cardCompanyCode integer Max Length: 2
결제 카드사 코드
그 외의 카드사는 현재 준비중이며, 카드사 추가될 경 예고없이 업데이트 될 수 있습니다.

cardCompanyName cardCompanyCode
신한 1
현대 2
삼성 3
국민 (현재 미지원) 4
롯데 5
하나 6
우리 (현재 미지원) 7
농협 (현재 미지원) 8
씨티 (현재 미지원) 9
비씨 10
cardAuthorizationNo integer Max Length: 8
구매자가 확인할 수 있는 카드사 승인번호
spreadOut integer Max Length: 2
카드 할부개월
일시불 결제의 경우 0으로 리턴됩니다.
noInterest boolean Max Length: 5
무이자 여부
true : 무이자, false : 일반
salesCheckLinkUrl string
신용카드 매출전표 호출URL
승인된 카드 결제건의 매출전표를 확인할 수 있는 URL 입니다. 구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다.
토스 매출전표 참고사항
Definition
POST https://pay.toss.im/api/v1/status
Example Request
curl "https://pay.toss.im/api/v1/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/v1/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/v1/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/v1/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/v1/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/v1/status") params = { "orderNo" => "1", "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
{
    "payToken": "example-payToken",
    "payStatus": "REFUND_SUCCESS",
    "orderNo": "1",
    "amount":110000,
    "amountTaxable":100000,
    "amountTaxFree":0,
    "amountVat":10000,
    "amountServiceFee":0,
    "timeCreated":"2017-02-15 11:59:48",
	"timePayComplete":"2017-02-15 12:01:19",
	"timePayCancel":"",
    "productDesc":"테스트 상품",
    
    "availableActions": [
    "REFUND"
    ],
    "refunds": [
        {
        "reason": "일부 상품 환불",
        "amount": 100,
        "refundNo": "7161b8e3-4b79-49d7-ab3c-3ae898aa073b",
        "timeRefundSuccess": "2017-02-15 16:12:40",
        "status": "SUCCESS"
        },
        {
        "reason": "일부 상품 환불",
        "amount": 200,
        "refundNo": "a636fe94-4e1e-41c8-90d9-b17180bdaf04",
        "timeRefundSuccess": "2017-02-15 16:12:43",
        "status": "SUCCESS"
        },
        {
        "reason": "일부 상품 환불",
        "amount": 500,
        "refundNo": "cc92a9ef-8a81-2938-dda9-ff8a78ae29b8",
        "timeRefundSuccess": "2017-02-15 16:12:46",
        "status": "SUCCESS"
        }
    ],
    "code": 0,
    "status": 200,
    "metadata": "metadata",
    "payMethod": "CARD",
    "cardCompanyCode": 3,
    "cardCompanyName": "삼성",
    "cardAuthorizationNo": "87654321",
    "spreadOut": "6",
    "noInterest": "false"
    "salesCheckLinkUrl": "https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=2da1ca05-d91d-410f-976d-7a610242da8a"
}