결제 생성
결제 건을 생성합니다.
결제 생성 완료 후, 구매자의 결제 인증을 얻어 완료처리하는 방법은 토스페이 시작하기 > 3. 구매자 인증 받기를 참고하세요.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
https://pay.toss.im/api/v2/payments요청 파라미터
apiKeystring필수가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
orderNostring필수가맹점의 상품 주문번호. 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다.
- '숫자, 영문자, 특수문자
_-:.^@'만 사용 가능하며, 50자 이내여야 합니다. - 동일 주문번호는 구매자 인증 완료(PAY_APPROVED) 이후 절대 재사용이 불가합니다.
- 최초 생성 후 2년이 지난 주문번호는 재사용할 수 없습니다.
- 테스트 환경과 라이브 환경 간의 주문번호 충돌 방지를 위해 가맹점 관리가 필요합니다.
productDescstring필수상품 설명. 상품 설명은 공백으로만 설정할 수 없고, 백슬래시("\\")와 따옴표(",")를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요. 토스 인코딩 방식 참고사항
retUrlstring필수구매자 인증완료 후 연결할 가맹점 웹페이지 URL. 사용자 인증이 완료되는 시점에 인증 데이터와 함께 결제완료 페이지로 이동시킵니다. 이 때, 전달되는 인증 데이터는 아래 링크에서 확인해 보실 수 있습니다. (단, 전달되는 인증 데이터는 결제수단 별로 차이가 있을 수 있습니다.) 구매자 인증완료 참고사항
retCancelUrlstring필수토스페이창에 진입한 사용자가 결제를 중단할 때 사용자를 이동시킬 가맹점 취소 페이지. 이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 강제로 종료하지 않고 가맹점의 취소 페이지로 이동할 수 있습니다. 구매자 편의를 위하여 반드시 활용해주세요!
retAppSchemestring결제 완료 후 연결할 가맹점 측 앱 스킴 값. 가맹점의 결제 구현환경이 App to App인 경우 retAppScheme 값을 선언해 주시면 토스페이 완료 후 가맹점 앱으로 redirect 할 수 있습니다.
autoExecutestring자동 승인 여부 설정. 가맹점의 판매 상품에 따라 '자동 승인 설정' 을 활용할 수 있습니다. true 를 선언한 경우 resultCallback 을 필수 값으로 체크합니다. 자동 승인 설정 참고사항
resultCallbackstring결제 결과 콜백 URL. 자동 승인 설정(autoExecute=true) 시 ResultCallback 구현이 필수이며, 결제 상태 확인을 위해 모든 가맹점에 사용을 권장합니다. 결제 결과를 수신할 가맹점의 외부에서 접근 가능한 URL이어야 하며, localhost, 192.168.x.x 등 내부망 도메인 및 사설 IP는 사용할 수 없습니다.
callbackVersionstring결제 결과 콜백 버전. 콜백 버전에 따라 전달되는 응답 값이 다를 수 있으니 최신 버전(V2) 이용을 권장합니다. 이 값이 포함되지 않을 경우 승인 콜백은 V2 버전의 데이터가 전달됩니다. V1: 콜백 데이터를 파라미터 형식으로 전달 (application/x-www-form-urlencoded). V2: 콜백 데이터를 JSON 형식으로 전달.
amountinteger필수총 결제 금액.
- 카드 결제를 지원하는 가맹점: 최대 10억 원까지 결제 가능
- 카드 결제를 지원하지 않는 가맹점: 최대 200만 원까지만 결제 가능 (200만 원을 초과하는 경우 결제 생성 단계에서 에러가 발생할 수 있습니다)
- 일부 고액·현금성 상품은 카드사·은행의 1회 한도가 더 낮을 수 있으며, 이 경우 결제가 실패할 수 있습니다.
amountTaxFreeinteger필수결제 금액 중 비과세 금액. 판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수 값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.
amountTaxableinteger결제 금액 중 과세 금액. 별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.
amountVatinteger결제 금액 중 부가세. 값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
amountServiceFeeinteger결제 금액 중 봉사료. 봉사료 금액입니다.
disposableCupDepositinteger일회용컵 보증금. 결제 금액 중 일회용컵 보증금 금액입니다. 일회용컵 보증금이 포함된 결제는 부분취소가 불가능합니다.
expiredTimestring결제 만료 기한 (기본값 15분, 최대 60분 설정 가능). 형식: YYYY-MM-DD HH:MM:SS (예: 2020-03-03 12:30:20)
enablePayMethodsstring결제수단 구분 변수. 가맹점 필요에 따라 결제창에 노출하는 결제수단을 제어할 수 있습니다.
TOSS_MONEY결제수단 중 토스머니만 노출CARD결제수단 중 카드만 노출null 또는 그 외의 값상점에 설정된 기본 결제수단으로 노출cashReceiptboolean현금영수증 발급 가능 여부. 현금영수증 기능을 활용하시는 경우 true, 미사용의 경우 false로 선언해 주시기 바랍니다. 반드시 true 또는 false 값을 전달해 주셔야 하고, null과 같은 비정상 값을 전달할 경우 해당 필드는 명시적으로 false로 처리됩니다.
cashReceiptTradeOptionstring현금영수증 발급 타입. 문화비 관련 상품의 경우, 발급 타입을 설정하여 보내주세요.
CULTURE문화비GENERAL일반 (기본값)PUBLIC_TP교통비cardOptionsobject카드 옵션. 결제창에 특정 카드만 노출하고 싶다면, options 변수에 토스 카드 코드를 추가해 주세요. 예를 들어, 삼성카드와 롯데카드만 결제가 가능하도록 노출을 제어한다면 아래와 같이 토스 카드 코드를 넘겨주시면 됩니다."cardOptions": {"options": [{"cardCompanyCode": 3}, {"cardCompanyCode": 5}]}
installmentstring할부 제한 타입. 신용카드 결제 시, 사용자의 할부 선택을 제한할 수 있습니다.
USE할부 사용 (기본값)NOT_USE할부 미사용응답 파라미터
codeinteger응답코드. 이 값을 받지 못했다면 가맹점에서 제한하는 방화벽의 이슈일 수 있으니 토스 방화벽 설정을 확인해 주세요!
0성공-1실패 (실패 사유는 msg와 errorCode 제공)checkoutPagestring결제를 진행할 수 있는 토스페이 웹페이지 URL. 토스가 전달한 값 그대로를 구매자에게 띄워주세요.
payTokenstring토스페이 토큰. 매회 유니크한 토큰 값이 생성됩니다. 가맹점에서는 이 값을 반드시 저장하고 관리하셔야 합니다.
msgstring응답이 성공이 아닌 경우 설명 메시지입니다.
errorCodestring에러 코드. 그 외의 에러 코드
COMMON_PAY_ERROR문제가 발생하였습니다.COMMON_INVALID_PARAMETER요청한 값이 바르지 않습니다.예제
요청 예제
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo":"1",
"amount":10000,
"amountTaxFree":0,
"productDesc":"테스트결제",
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute":true,
"resultCallback":"https://pay.toss.im/payfront/demo/callback",
"callbackVersion":"V2",
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1",
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel"
}'import java.nio.charset.StandardCharsets;
URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
url = new URL("https://pay.toss.im/api/v2/payments");
connection = url.openConnection();
connection.addRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
connection.setDoInput(true);
org.json.simple.JSONObject jsonBody = new JSONObject();
jsonBody.put("orderNo", "1");
jsonBody.put("amount", 10000);
jsonBody.put("amountTaxFree", 0);
jsonBody.put("productDesc", "테스트 결제");
jsonBody.put("apiKey", "sk_test_w5lNQylNqa5lNQe013Nq");
jsonBody.put("autoExecute", true);
jsonBody.put("resultCallback", "https://pay.toss.im/payfront/demo/callback");
jsonBody.put("callbackVersion", "V2");
jsonBody.put("retUrl", "https://pay.toss.im/payfront/demo/completed?orderno=1");
jsonBody.put("retCancelUrl", "https://pay.toss.im/payfront/demo/cancel");
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"] = "https://pay.toss.im/payfront/demo/callback";
$arrayBody["callbackVersion"] = "V2";
$arrayBody["retUrl"] = "https://pay.toss.im/payfront/demo/completed?orderno=1";
$arrayBody["retCancelUrl"] = "https://pay.toss.im/payfront/demo/cancel";
$jsonBody = json_encode($arrayBody);
$ch = curl_init('https://pay.toss.im/api/v2/payments');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonBody);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($jsonBody))
);
$result = curl_exec($ch);
curl_close($ch);
echo "Response: ".$result;import urllib, urllib2
url = "https://pay.toss.im/api/v2/payments"
params = {
"orderNo": "1",
"amount": 10000,
"amountTaxFree": 0,
"productDesc":"테스트 결제",
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute": true,
"resultCallback": "https://pay.toss.im/payfront/demo/callback",
"callbackVersion": "V2",
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1",
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel"
}
response = urllib.urlopen(url, urllib.urlencode(params))
print(response.read())require 'net/http'
require 'json'
uri = URI.parse("https://pay.toss.im/api/v2/payments")
params = {
"orderNo" => "1",
"amount"=> 10000,
"amountTaxFree"=> 0,
"productDesc" => "테스트 결제",
"apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute" => true,
"resultCallback" => "https://pay.toss.im/payfront/demo/callback",
"callbackVersion" => "V2",
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1",
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel"
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request.set_form_data(params)
response = http.request(request)
p JSON.parse(response.body)Dim data, httpRequest, postResponse
data = "apiKey=sk_test_w5lNQylNqa5lNQe013Nq"
data = data & "&orderNo=1"
data = data & "&amount=10000"
data = data & "&amountTaxFree=0"
data = data & "&productDesc=ASPtestProduct"
data = data & "&autoExecute=true"
data = data & "&resultCallback=https://pay.toss.im/payfront/demo/callback"
data = data & "&callbackVersion=V2"
data = data & "&retUrl=https://pay.toss.im/payfront/demo/completed?orderno=1"
data = data & "&retCancelUrl=https://pay.toss.im/payfront/demo/cancel"
Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v2/payments", False
httpRequest.SetRequestHeader "Content-Type", "application/json"
httpRequest.Send data
postResponse = httpRequest.ResponseText
Response.Write postResponse응답 예제
{
"code": 0,
"checkoutPage": "https://pay.toss.im/payfront/auth?payToken=example-payToken",
"payToken": "example-payToken"
}