토스 결제 API 소개

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

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

결제 상태

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

생성된 결제의 현재 상태를 파악하려면 결제 상태 확인 API를 활용하세요.

결제 상태 목록

PAY_STANDBY
결제 대기 중
: 결제 건이 생성되었고, 구매자의 결제 진행을 대기 중인 상태. 이 상태에서 구매자나 가맹점이 결제를 취소할 수 있습니다. 또한 설정한 '만료 기간'이 도래하면 자동으로 취소됩니다.
PAY_APPROVED 수동 승인 설정 시
구매자 인증 완료
: 결제를 위한 구매자 인증 완료되고, 가맹점의 최종 승인을 기다리는 상태.
(결제 생성 시 'autoExecute'를 false로 설정한 경우에만 이 단계를 거칩니다)
PAY_CANCEL
결제 취소
: 결제가 완료되기 전에 구매자나 가맹점이 결제를 취소한 상태입니다. (결론적으론 금액의 이동 없이 종료된 건)
PAY_PROGRESS
결제 진행 중
: 구매자가 결제를 승인하여 구매자의 계좌에서 결제 금액을 출금 처리 중인 상태입니다.
PAY_COMPLETE
결제 완료
: 구매자 및 가맹점의 결제 승인 및 출금이 정상적으로 완료된 상태입니다. 에스크로 결제 건의 경우, 자동으로 '배송등록 대기 중' 상태로 변경됩니다.
ESCROW_REQUEST 에스크로 only
배송등록 대기 중 (에스크로 요청)
: 에스크로 결제 건이 결제 완료된 후, 매매보호에 들어간 상태입니다. 판매자가 '배송 등록'을 하면 '구매확정 대기 중' 상태로 변경되며, 120일 동안 배송 등록을 하지 않는 경우에도 자동으로 '구매확정 대기 중' 상태로 변경됩니다.
ESCROW_RELEASE 에스크로 only
구매확정 대기 중 (에스크로 해제)
: 판매자가 '배송 등록'을 완료하고 구매자의 '구매 확정'을 대기 중인 상태입니다. 구매자가 구매 확정을 하면 판매자 대금 지급 과정을 시작하고, 구매자가 지급을 거부하면 '구매자 지급 거부' 상태로 변경됩니다.
ESCROW_DENY 에스크로 only
구매자 지급 거부 (에스크로 거부)
: 구매자가 지급을 거절한 상태입니다. 판매자는 이 건을 전액 환불 처리하거나 구매자에게 '구매 확정'을 다시 요청할 수 있습니다.
REFUND_PROGRESS
환불 진행 중
: 전액 또는 부분 환불을 진행 중인 상태로, 완료되기 전 까지 다른 환불을 진행할 수 없습니다.
REFUND_SUCCESS
환불 성공
: 전액 또는 부분 환불이 완료되어, 환불 처리한 금액이 구매자의 계좌로 입금 완료된 상태입니다.
SETTLEMENT_COMPLETE
정산 완료
: 결제 완료된 금액에 대해 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 180일 경과)
SETTLEMENT_REFUND_COMPLETE
환불 정산 완료
: 전액 또는 부분 환불에 대한 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 180일 경과했거나 전액 환불에 대한 정산 완료된 경우)
              
              
              
              
              
              
            

은행 정기 점검시간

은행 점검 시간에는 해당 은행 계좌를 통한 토스머니 충전이 불가합니다.

전체 은행 공통 점검시간

(매일)
23:20 ~ 익일 00:40

은행별 정기 점검시간

KDB산업
매주 일요일 00:00~04:00
IBK기업
KB국민
매월 세번째 (not 셋째주) 일요일 전날 23:50~00:30, 일요일 05:00~05:30
외환은행
수협은행
NH농협
매월 셋째주 월요일 00:00~04:00
우리은행
매주 목요일 23:45 ~ 금요일 00:45, 매달 둘째주 일요일 02:00 ~ 06:00
SC은행
신한은행
씨티은행
공휴일 다음날(매주 월요일 포함) 00:00~02:00
대구은행
분기말에 한번 토요일 00:00~06:00
부산은행
매월 셋째주 월요일 00:00~04:00
광주은행
둘째주 일요일 02:00~06:00
제주은행
월, 목 04:30~05:00
전북은행
매월 둘째주 토요일 00:00~04:00
경남은행
매월 둘째주 일요일 00:00~03:00
새마을은행
신협은행
저축은행
우체국
매일 04:00~05:00 점검
하나은행
                          
                          
                          
                          
                          
                          
                        

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

(이전) https://toss.im/tosspay/api/v1/payments

parameters

apiKey string
가맹점 key
orderNo string
가맹점의 상품 주문번호
주문번호는 50자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다.
amount integer
결제 금액
productDesc string
상품 설명
상품 설명은 공백으로만 설정할 수 없고, 백슬래시(\)와 따옴표(",')를 포함할 수 없으며 총 255자 이내여야 합니다.
autoExecute boolean
자동 승인 여부 설정(기본 값: false)

true 구매자 인증 완료 시, 바로 결제 완료 처리
(true로 설정하면 반드시 'resultCallback' 값을 설정하고 '결제 완료' callback을 받았을 때만 구매 완료 처리해야합니다)
false 구매자 인증 완료 후 가맹점의 최종 승인 시 결제 완료 처리
('결제 승인 API'를 통해 최종 승인합니다)
retUrl string
Web 결제 완료 후 연결할 웹페이지의 URL (결제 최종 승인 및 완료 처리할 페이지)
retAppScheme string
App 결제 완료 후 연결할 app scheme (결제 최종 승인 및 완료 처리할 페이지). retAppScheme을 사용할 경우 retUrl은 사용하지 않아도 됩니다.
amountTaxable integer
결제 금액 중 과세금액 (복합과세)
amountTaxFree integer
결제 금액 중 비과세금액 (복합과세), 없으면 0으로 설정
amountVat integer
결제 금액 중 부가세 (복합과세)
amountServiceFee integer
결제 금액 중 봉사료 (복합과세)
expiredTime timestamp
결제 만료 기한 (기본값 15분, 최대 1시간 설정 가능)
형식 : 1970-01-01 00:00:00
resultCallback string 자동 승인 설정시 필수
결제 결과 callback URL (성공, 취소, 환불 등)
escrow boolean
에스크로 결제 여부 (기본값 false)
cashReceipt boolean
현금영수증 발급 가능 여부
checkoutType string
결제창 타입을 선택합니다. (앱/웹) 지문인증을 지원하려면 'app' 또는 'both'를 선택하세요. (기본값 web)

web 토스 앱 없이 웹에서 결제
app 토스 앱을 통해서만 결제 가능
both 웹결제 / 앱을 통한 결제를 구매자가 선택
arsAuthSkippable character
인증된 기기에서 다시 결제할 때 ARS 인증 생략 여부를 설정합니다. (기본값 'Y')

Y 인증된 기기에서는 ARS 인증 생략
N 인증 여부와 관계 없이 ARS 인증 제공
* 고환금성 거래인 경우, 'N'으로 설정할 것을 권장합니다.
* checkoutType 값이 web/both인 경우에만 적용되는 설정입니다.
userPhone string
구매자가 결제 시 이용할 휴대전화번호 지정
(지정 시 구매자가 번호를 변경할 수 없으므로 전화번호 정보가 정확할 때만 이용하십시오)
partnerId string
가맹점 서비스의 User ID
(본 parameter를 통해 User ID를 전송하면 재결제 시 전화번호 입력 없이 사용자를 식별하여 결제 과정이 더 간단해집니다)
metadata string
결제와 연관된 추가 데이터 (최대 1024자)
retCancelUrl string
토스 브릿지 페이지에서 사용자가 결제를 중단할때 사용자를 이동시킬 가맹점 페이지

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode 제공)
checkoutPage string
생성된 결제를 진행하는 웹페이지 URL (구매자를 이 URL로 보내야 함)
payToken string
Toss 결제 토큰
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드

COMMON_INVALID_PARAMETER 요청한 값이 부족하거나 올바르지 않습니다.

결제 결과 Callback (resultCallback)

결제 상태가 변경될 때 토스가 판매자에게 변경 사항을 알립니다. 자동 승인 설정을 사용 시 (autoExecute가 true) 필수적으로 활용해야합니다.

* 생성된 결제 건에 resultCallback 파라미터 값이 있을 경우에만 동작합니다.

parameter

status string
PAY_SUCCESS, PAY_CANCEL, REFUND_SUCCESS 중 하나
payToken string
Toss 결제 토큰
orderNo string
Toss 결제와 이어진 주문번호
metadata string
결제 생성 시 저장한 연관 정보

response

기대하지 않음 (미사용)
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":"2015072012211",
        "amount":10000,
        "amountTaxFree":0,
        "productDesc":"테스트결제",
        "apiKey":"sk_test_apikey1234567890"
        }'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", "2015072012211");
	jsonBody.put("amount", 10000);
	jsonBody.put("amountTaxFree", 0);
	jsonBody.put("productDesc", "테스트 결제");
	jsonBody.put("apiKey", "sk_test_apikey1234567890");
	jsonBody.put("expiredTime", "2015-07-20 16:21:00");
	jsonBody.put("resultCallback", "https://myshop.com/toss/result.php");

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

	BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	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"] = "2015072012211";
$arrayBody["amount"] = 10000;
$arrayBody["amountTaxFree"] = 0;
$arrayBody["productDesc"] = "테스트 결제";
$arrayBody["apiKey"] = "sk_test_apikey1234567890";
$arrayBody["expiredTime"] = "2015-07-20 16:21:00";
$arrayBody["resultCallback"] = "https://myshop.com/toss/result.php";
$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_apikey1234567890"
data = data & "&orderNo=2015072012211"
data = data & "&amount=10000"
data = data & "&amountTaxFree=0"
data = data & "&productDesc=ASPtestProduct"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v1/payments"
params = {
    "orderNo": "2015072012211",
    "amount": 10000,
    "amountTaxFree": 0,
    "productDesc":"테스트 결제",
    "apiKey": "sk_test_apikey1234567890",
    "expiredTime":"2015-07-20 16:21:00",
    "resultCallback": "https://myshop.com/toss/result.php"
}

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" => "2015072012211",
        "amount"=> 10000,
        "amountTaxFree"=> 0,
        "productDesc" => "테스트 결제",
        "apiKey" => "sk_test_apikey1234567890",
        "expiredTime" => "2015-07-20 16:21:00",
        "resultCallback" => "https://myshop.com/toss/result.php"
}

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=test_token1234567890&retUrl=http://YOUR-SITE.COM","payToken":"test_token1234567890"}

결제 승인

구매자 인증 완료 상태(PAY_APPROVED)의 결제 건을 최종 승인하여 결제를 완료 처리합니다.

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

endpoint

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

(이전) https://toss.im/tosspay/api/v1/execute

parameters

apiKey string
가맹점 key
payToken string
토스 결제 토큰 (승인할 결제 건의 토큰값)
amount integer
결제 금액
(입력하는 경우, 구매자가 승인한 결제 금액과 이 값이 일치할 경우에만 승인 처리)
orderNo string
가맹점의 상품 주문번호
(입력하는 경우, 구매자가 승인한 주문번호와 이 값이 일치할 경우에만 승인 처리)

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
approvalTime timestamp
승인시각 (yyyy-MM-dd HH:mm:ss)
amount integer
승인한 결제 금액
orderNo string
승인한 상품 주문번호
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드
Definition
POST https://pay.toss.im/api/v1/execute
Example Request
curl "https://pay.toss.im/api/v1/execute" \
    -H "Content-Type: application/json" \
    -d '{
        "payToken":"test_token1234567890",
        "apiKey":"sk_test_apikey1234567890"
        }'URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
	url = new URL("https://pay.toss.im/api/v1/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", "test_token1234567890");
	jsonBody.put("apiKey", "sk_test_apikey1234567890");

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

	BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	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"] = "test_token1234567890";
$arrayBody["apiKey"] = "sk_test_apikey1234567890";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v1/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_apikey1234567890"
data = data & "&payToken=test_token1234567890"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v1/execute"
params = {
    "payToken": "test_token1234567890",
    "apiKey": "sk_test_apikey1234567890"
}

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

uri = URI.parse("https://pay.toss.im/api/v1/execute")

params = {
        "payToken" => "test_token1234567890",
        "apiKey" => "sk_test_apikey1234567890"
}

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,"approvalTime":"2016-11-16 13:59:59"}
            

결제 취소

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

endpoint

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

(이전) https://toss.im/tosspay/api/v1/cancel

parameters

apiKey string
가맹점 key
payToken string
Toss 결제 토큰
reason string
취소 사유 (최대 50자)

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드
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":"test_token1234567890",
        "apiKey":"sk_test_apikey1234567890"
        }'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", "test_token1234567890");
	jsonBody.put("reason", "재고 부족");
	jsonBody.put("apiKey", "sk_test_apikey1234567890");

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

	BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	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"] = "test_token1234567890";
$arrayBody["reason"] = "재고 부족";
$arrayBody["apiKey"] = "sk_test_apikey1234567890";
$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_apikey1234567890"
data = data & "&payToken=test_token1234567890"
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": "test_token1234567890",
    "reason":"재고 부족",
    "apiKey": "sk_test_apikey1234567890"
}

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" => "test_token1234567890",
        "reason" => "재고 부족",
        "apiKey" => "sk_test_apikey1234567890"
}

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/v1/refunds

(이전) https://toss.im/tosspay/api/v1/refunds

parameters

apiKey string
가맹점 key
payToken string
토스 결제 토큰
refundNo string
환불 번호
환불 상태 확인 시 필요. 미입력 시 자동 생성되며 환불 완료 응답에서 확인 가능
reason string
환불 사유 (최대 50자)
amount integer
환불할 금액
미입력시 환불할 결제건의 남은 전액을 환불 처리
amountTaxable integer
환불할 금액 중 과세금액
amountTaxFree integer
환불할 금액 중 비과세금액
환불할 금액중 비과세 금액, 없으면 0으로 설정
amountVat integer
환불할 금액 중 부가세
값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림
amountServiceFee integer
환불할 금액 중 봉사료
결제 생성 시 봉사료 설정한 경우에만 입력 가능

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
refundNo string
환불 번호
환불 상태 확인 시 필요
approvalTime timestamp
승인시각 (yyyy-MM-dd HH:mm:ss)
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드

COMMON_REFUND_ERROR 이미 환불된 결제입니다.
REFUND_EXCEED_AMOUNT 환불금액이 결제금액보다 더 클수 없습니다.
Definition
POST https://pay.toss.im/api/v1/refunds
Example Request
curl "https://pay.toss.im/api/v1/refunds" \
    -H "Content-Type: application/json" \
    -d '{
        "payToken":"test_token1234567890",
        "apiKey":"sk_test_apikey1234567890"
        }'URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
	url = new URL("https://pay.toss.im/api/v1/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", "test_token1234567890");
	jsonBody.put("amount", "5000");
	jsonBody.put("apiKey", "sk_test_apikey1234567890");

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

	BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	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"] = "test_token1234567890";
$arrayBody["amount"] = 5000;
$arrayBody["apiKey"] = "sk_test_apikey1234567890";
$jsonBody = json_encode($arrayBody);

$ch = curl_init('https://pay.toss.im/api/v1/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_apikey1234567890"
data = data & "&payToken=test_token1234567890"
data = data & "&amount=1000"

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

postResponse = httpRequest.ResponseText

Response.Write postResponseimport urllib, urllib2

url = "https://pay.toss.im/api/v1/refunds"
params = {
    "payToken": "test_token1234567890",
    "amount": 5000,
    "apiKey": "sk_test_apikey1234567890"
}

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

uri = URI.parse("https://pay.toss.im/api/v1/refunds")

params = {
        "payToken" => "test_token1234567890",
        "amount"=> 5000,
        "apiKey" => "sk_test_apikey1234567890"
}

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":"cc92a9ef-8a81-2938-dda9-ff8a78ae29b8","approvalTime":"2016-11-16 13:59:59"}
            

결제 상태 확인

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

endpoint

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

(이전) https://toss.im/tosspay/api/v1/status

parameters

apiKey string
가맹점 key
payToken 또는 orderNo string
토스 결제 토큰 또는 가맹점 주문번호 (payToken의 우선순위 높음)

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
payToken string
토스 결제 토큰
payStatus string
결제 상태

PAY_STANDBY 결제 대기 중
PAY_APPROVED 구매자 인증 완료
PAY_CANCEL 결제 취소
PAY_PROGRESS 결제 진행 중
PAY_COMPLETE 결제 완료
ESCROW_REQUEST 배송등록 대기 중
ESCROW_RELEASE 구매확정 대기 중
ESCROW_DENY 구매자 지급 거부
REFUND_PROGRESS 환불 진행 중
REFUND_SUCCESS 환불 성공
SETTLEMENT_COMPLETE 정산 완료
SETTLEMENT_REFUND_COMPLETE 환불 정산 완료
orderNo string
토스 결제와 이어진 주문번호
amount integer
결제 금액
amountTaxable integer
결제 금액 중 과세금액 (복합과세)
amountTaxFree integer
결제 금액 중 비과세금액 (복합과세)
amountVat integer
결제 금액 중 부가세 (복합과세)
amountServiceFee integer
결제 금액 중 봉사료 (복합과세)
timeCreated timestamp
결제 생성 시각
timePayComplete timestamp
결제 완료 시각
timePayCancel timestamp
결제 취소 시각
productDesc string
상품 설명
hasOwner boolean
구매자의 결제 정보 입력 여부
availableActions list
가능한 액션 목록

CANCEL 결제 취소
REFUND 결제 환불
ESCROW 에스크로 (배송등록/구매확정재요청)
refunds list
조회한 결제건에 대한 환불 요청 및 결과
timeRefundSuccess timestamp
환불 완료 시각
metadata string
결제와 연관된 추가 데이터
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드
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":"test_token1234567890",
        "apiKey":"sk_test_apikey1234567890"
        }'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", "2015072012211");
	jsonBody.put("apiKey", "sk_test_apikey1234567890");

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

	BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
	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"] = "2015072012211";
$arrayBody["apiKey"] = "sk_test_apikey1234567890";
$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_apikey1234567890" data = data & "&orderNo=2015072012211" Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP") httpRequest.Open "POST", "https://pay.toss.im/api/v1/status", False httpRequest.SetRequestHeader "Content-Type", "application/x-www-form-urlencoded" httpRequest.Send data postResponse = httpRequest.ResponseText Response.Write postResponseimport urllib, urllib2 url = "https://pay.toss.im/api/v1/status" params = { "orderNo": "2015072012211", "apiKey": "sk_test_apikey1234567890" } 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" => "2015072012211", "apiKey" => "sk_test_apikey1234567890" } 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": "test_token1234567890",
    "payStatus": "REFUND_SUCCESS",
    "orderNo": "2015072012211",
    "amount":11000,
    "amountTaxable":10000,
    "amountTaxFree":0,
    "amountVat":1000,
    "amountServiceFee":0,
    "timeCreated":"2017-02-15 11:59:48",
	"timePayComplete":"2017-02-15 12:01:19",
	"timePayCancel":"",
    "productDesc":"테스트 상품",
    "hasOwner": true,
    "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"
}
            

환불 상태 확인

요청하신 환불 건의 현재 상태를 조회합니다. (요청 건별 조회)

endpoint

(GET)
https://pay.toss.im/api/v1/refunds/{refundNo}

(이전) https://toss.im/tosspay/api/v1/refunds/{refundNo}

parameters

apiKey string
가맹점 key

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
refund list
환불 번호와 금액, 상태, 사유
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드
Definition
GET https://pay.toss.im/api/v1/refunds/{refundNo}
Example Request
curl -X GET \
  'https://pay.toss.im/api/v1/refunds/f0fe4083-fe1b-44e5-ba04-4390bc19bc5e?apiKey=sk_test_apikey1234567890' \
  -H 'content-type: application/json'OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"apiKey\":\"sk_test_LY5kmjV2l7LY5kmjV2l7\"\n}");
Request request = new Request.Builder()
  .url("https://pay.toss.im/api/v1/refunds/f0fe4083-fe1b-44e5-ba04-4390bc19bc5e?apiKey=sk_test_apikey1234567890")
  .get()
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();$request = new HttpRequest();
$request->setUrl('https://pay.toss.im/api/v1/refunds/f0fe4083-fe1b-44e5-ba04-4390bc19bc5e');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'apiKey' => 'sk_test_apikey1234567890'
));

$request->setHeaders(array(
  'content-type' => 'application/json'
));

$request->setBody('{
    "apiKey":"sk_test_LY5kmjV2l7LY5kmjV2l7"
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}import http.client

conn = http.client.HTTPSConnection("pay.toss.im")

payload = "{\n    \"apiKey\":\"sk_test_LY5kmjV2l7LY5kmjV2l7\"\n}"

headers = {
    'content-type': "application/json"
    }

conn.request("GET", "/tosspay/api/v1/refunds/f0fe4083-fe1b-44e5-ba04-4390bc19bc5e?apiKey=sk_test_apikey1234567890", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))require 'uri'
require 'net/http'

url = URI("https://pay.toss.im/api/v1/refunds/f0fe4083-fe1b-44e5-ba04-4390bc19bc5e?apiKey=sk_test_apikey1234567890")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["content-type"] = 'application/json'
request.body = "{\n    \"apiKey\":\"sk_test_LY5kmjV2l7LY5kmjV2l7\"\n}"

response = http.request(request)
puts response.read_body
Example Response
{
    "code": 0,
    "refund": {
        "refundNo": "7161b8e3-4b79-49d7-ab3c-3ae898aa073b",
        "status": "SUCCESS",
        "amount": 100,
        "reason": "부분 환불 테스트"
    }
}
            

에스크로 결제 진행

에스크로 결제를 완료하고 대금을 정산받기 위해서는 '배송 등록'이 필요합니다. 또, 구매자가 대금 지급을 거부하여 결제가 '구매자 지급 거부' 상태가 된 경우, '구매확정 재요청'을 통해 거부 상태를 해제할 수 있습니다.

본 API를 통해 '배송 등록'과 '구매확정 재요청'을 처리할 수 있습니다.

- '배송등록 대기 중' 상태에서 호출 시 : '배송 등록' 됨
- 구매자 지급 거부 상태에서 호출 시 : '구매확정 재요청' 됨

더 자세한 내용은 '토스 결제 시작하기 > 에스크로 결제 진행' 문서를 참고하세요.

endpoint

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

(이전) https://toss.im/tosspay/api/v1/escrow

parameters

apiKey string
가맹점 key
payToken string
토스 결제 토큰

response

code integer
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
msg string
응답이 성공이 아닌 경우 설명 메세지
errorCode string
에러 코드
Definition
POST https://pay.toss.im/api/v1/escrow
Example Request
curl "https://pay.toss.im/api/v1/escrow" \
    -H "Content-Type: application/json" \
    -d '{
    "payToken":"test_token1234567890",
    "apiKey":"sk_test_apikey1234567890"
    }'URL url = null;
    URLConnection connection = null;
    StringBuilder responseBody = new StringBuilder();
    try {
    url = new URL("https://pay.toss.im/api/v1/escrow");
    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", "test_token1234567890");
    jsonBody.put("apiKey", "sk_test_apikey1234567890");

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

    BufferedReader br = new BufferedReader(new InputStreamReader(connection.getInputStream()));
    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"] = "test_token1234567890";
    $arrayBody["apiKey"] = "sk_test_apikey1234567890";
    $jsonBody = json_encode($arrayBody);

    $ch = curl_init('https://pay.toss.im/api/v1/escrow');
    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;
Example Response
{"code":0}