토스 결제 API 소개

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

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


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

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

  • IE 11, Safari 7, Chrome 38, Firefox 27 부터 지원
  • IE 9, 10 는 일부 지원 (Window 8.1 이상, Enable TLS 1.1, 1.2)
  • 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자 이내여야 하고, '숫자, 영문자, 특수문자 _-:.^@'만 사용할 수 있습니다.
가맹점 주문번호 테스트와 라이브 환경 사이에서 중복되지 않도록 가맹점의 관리가 필요합니다. 중복되는 경우 오류가 발생합니다.
amount integer 필수 Max Length: 7
결제 금액
금액과 관련된 모든 파라미터는 Number 형태로 보내주셔야 에러가 발생하지 않습니다.
productDesc string 필수 Max Length: 255
상품 설명
상품 설명은 공백으로만 설정할 수 없고, 백슬래시(\)와 따옴표(",')를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요.
retUrl string 필수 Max Length: 255
Web 결제 완료 후 연결할 웹페이지의 URL (결제 최종 승인 및 완료 처리할 페이지)
결제 완료 화면으로의 이동일 뿐, 정확한 결제 성공 유무를 보장할 수 없으니 반드시 resultCallback 을 통하여 처리하시기 바랍니다.
retCancelUrl string 필수 Max Length: 255
토스 브릿지 페이지에서 사용자가 결제를 중단할때 사용자를 이동시킬 가맹점 페이지
이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 종료하지 않고 취소 버튼을 통하여 가맹점이 설정한 URL로 redirect됩니다.
구매자 편의를 위하여 반드시 활용해주세요!
단순 url의 이동일 뿐 실제 취소는 가맹점에서 추가 구현해 주셔야 합니다.
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가 포함되면 이용할 수 없으니 유의해주세요.
amountTaxable Max Length: 7
결제 금액 중 과세금액 (복합과세)
해당 값이 없을 경우 0 으로 보내주셔야 합니다. 빈 값의 경우 에러가 발생합니다. Max Length: 7
amountTaxFree integer 필수 Max Length: 7
결제 금액 중 비과세금액 (복합과세)
해당 값이 없을 경우 0 으로 보내주셔야 합니다. 빈 값의 경우 에러가 발생합니다. Max Length: 7
amountVat integer Max Length: 7
결제 금액 중 부가세 (복합과세)
해당 값이 없을 경우 0 으로 보내주셔야 합니다. 빈 값의 경우 에러가 발생합니다.
amountServiceFee integer Max Length: 7
결제 금액 중 봉사료 (복합과세)
해당 값이 없을 경우 0 으로 보내주셔야 합니다. 빈 값의 경우 에러가 발생합니다. Max Length: 7
expiredTime timestamp Max Length: 20
결제 만료 기한 (기본값 15분, 최대 1시간 설정 가능)
형식 : 1970-01-01 00:00:00
cashReceipt boolean Max Length: 5
현금영수증 발급 가능 여부
현금영수증 기능을 활용하시는 경우 true, 미 사용의 경우 false로 선언해 주시기 바랍니다. 그러나, 기본 값이 true이기 때문에 현금영수증 사용 시 별도로 선언하지 않으셔도 됩니다.
토스 머니 결제건에 한해서 현금영수증 발행 여부를 설정할 수 있습니다.
metadata string Max Length: 1024
결제와 연관된 추가 데이터

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 시스템 에러가 발생 하였습니다.
CORE_USER_ERROR 존재하지 않는 사용자 입니다.
COMMON_TEMP_DENIAL_ERROR 일시적 시스템 에러가 발생하였습니다.
그 외의 에러 코드
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_apikey1234567890",
        "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_apikey1234567890");
    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_apikey1234567890";
$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_apikey1234567890"
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/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": "1",
    "amount": 10000,
    "amountTaxFree": 0,
    "productDesc":"테스트 결제",
    "apiKey": "sk_test_apikey1234567890",
    "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_apikey1234567890",
        "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으로 리턴됩니다.
paidTs timestamp 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,
 "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가 다르면 승인 실패처리하여 다시 한번 유효성을 검증합니다.
amount integer Max Length: 7
결제 금액

response

code integer Max Length: 2
응답코드

0 성공
-1 실패 (실패사유는 msg와 errorCode로 제공)
approvalTime timestamp 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 으로 리턴됩니다.
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
에러 코드

PAY_EXPIRED 결제 기한이 만료되었습니다.
COMMON_TIMEOUT 출금 타임 아웃이 발생하였습니다.
PAY_UNAUTHORIZED 본인의 결제가 아닙니다.
COMMON_EXCEED_LIMIT 결제한도를 초과 하였습니다.
PAY_ALREADY_COMPLETED 이미 완료된 결제입니다.
PAY_ITS_NOT_ABLE_TO_PAY 결제를 진행 할 수 없는 상태 입니다.
COMMON_NOT_ENOUGH_CASH 잔고가 부족합니다.
EXECUTE_PAY_NOT_APPROVED 승인 되지 않은 결제 입니다.
COMMON_SIGN_FAILED_CS_CALL 전자서명에 실패 하였습니다.
COMMON_BREAK_TIME_OF_BANK 은행 점검시간 입니다.
그 외의 에러 코드
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":"example-payToken",
        "apiKey":"sk_test_apikey1234567890"
        }'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/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_apikey1234567890");

	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_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=example-payToken"

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": "example-payToken",
    "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" => "example-payToken",
        "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,
    "mode": "LIVE",
    "orderNo": "TossTest20190718",
    "amount": 2000,
    "approvalTime": "2019-07-18 11:28:02",
    "discountedAmount": 0,
    "paidPoint": 0,
    "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_apikey1234567890"
        }'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_apikey1234567890");

	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_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=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_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" => "example-payToken",
        "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/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 필수 Max Length: 7
환불할 금액
미입력시 환불할 결제건의 남은 전액을 환불 처리
amountTaxable integer Max Length: 7
환불할 금액 중 과세금액
amountTaxFree integer 필수 Max Length: 7
환불할 금액 중 비과세금액
환불할 금액중 비과세 금액, 없으면 0으로 설정 Max Length: 7
amountVat integer Max Length: 7
환불할 금액 중 부가세
값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림 Max Length: 7
amountServiceFee integer Max Length: 7
환불할 금액 중 봉사료
결제 생성 시 봉사료 설정한 경우에만 입력 가능 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
토스 포인트 사용금액
결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0 으로 리턴됩니다.
approvalTime timestamp 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/v1/refunds
Example Request
curl "https://pay.toss.im/api/v1/refunds" \
    -H "Content-Type: application/json" \
    -d '{
        "payToken":"example-payToken",
        "apiKey":"sk_test_apikey1234567890"
        }'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/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_apikey1234567890");

	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_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=example-payToken"
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": "example-payToken",
    "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" => "example-payToken",
        "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": "3243c76e-e9cf-4669-881b-33a3b82ddf49",
 "approvalTime": "2019-07-18 11:32:52",
 "refundableAmount": 0,
 "discountedAmount": 0,
 "paidPoint": 0,
 "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 timestamp Max Length: 7
결제 생성 시각
timePayComplete timestamp Max Length: 20
결제 완료 시각
timePayCancel timestamp Max Length: 20
결제 취소 시각
productDesc string Max Length: 255
상품 설명
availableActions list
가능한 액션 목록

CANCEL 결제 취소
REFUND 결제 환불
refunds list
조회한 결제건에 대한 환불 요청 및 결과
timeRefundSuccess timestamp 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_apikey1234567890"
        }'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_apikey1234567890");

	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_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=1" 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": "1", "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" => "1", "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": "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"
}