가맹점 결제 승인
자동 승인 설정을 false로 사용하는 가맹점에서만 처리하는 로직입니다.
구매자 인증 완료 상태(PAY_APPROVED)의 결제 건을 가맹점이 주체가 되어 최종 승인하고 결제를 완료 처리합니다.
결제 승인에 관한 자세한 내용은 아래 문서를 참고하세요.
토스페이 시작하기 > 결제 승인하기
필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 '어떤 결제건'을 최종 승인할지 알려주세요.
필요에 따라 결제건의 유효성 검증을 할 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
https://pay.toss.im/api/v2/execute요청 파라미터
apiKeystring필수가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
payTokenstring필수토스페이 토큰 (승인할 결제 건의 토큰값)
orderNostring가맹점의 상품 주문번호. 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다. '숫자, 영문자, 특수문자 _-:.^@'만 사용 가능하며, 50자 이내여야 합니다. 동일 주문번호는 구매자 인증 완료(PAY_APPROVED) 이후 절대 재사용이 불가합니다. 최초 생성 후 2년이 지난 주문번호는 재사용할 수 없습니다. 테스트 환경과 라이브 환경 간의 주문번호 충돌 방지를 위해 가맹점 관리가 필요합니다.
응답 파라미터
codeinteger응답코드
0성공-1실패 (실패사유는 msg와 errorCode로 제공)modestring결제환경
LIVE실거래용TEST테스트용approvalTimestring결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss). 요청에 따른 결제건 처리 시간입니다. 환불 시에도 동일한 변수로 리턴되므로 구분하여 관리하시기 바랍니다.
stateMsgstring상태 응답 텍스트 값
amountinteger상품금액. 결제 생성 시 요청된 총 금액
discountedAmountinteger할인된 금액. 할인된 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다. 결제 상점에 따라 할인조건은 차이가 있을 수 있습니다.
paidAmountinteger지불수단 승인금액. 총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
payMethodstring결제수단
TOSS_MONEY토스머니CARD카드orderNostring승인된 상품 주문번호
payTokenstring승인된 결제토큰
transactionIdstring거래 트랜잭션 아이디. 결제의 거래구분을 위하여 토스서버에서 유니크한 값을 생성해서 전달드립니다. 매출전표를 호출하거나 환불 진행 시 구분 값으로 활용할 수 있습니다.
cashReceiptMgtKeystring현금영수증 관리번호 식별값. 국세청 승인번호는 아니며 토스페이에서 자체적으로 만든 식별 값입니다. 해당 필드 존재로 현금영수증 발급 구분 가능합니다.
cardCompanyNamestring승인 카드사명. 아래 테이블을 참고해 주세요.
cardCompanyCodeinteger카드사 코드. 자세한 내용은 카드 코드(/guide/card-code)를 참조해주세요.
cardAuthorizationNostring구매자가 확인할 수 있는 카드사 승인번호. 정상적인 카드사 승인번호는 라이브 키 결제에서 확인하실 수 있습니다.
spreadOutinteger사용자가 선택한 카드 할부개월. 5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
noInterestboolean카드 무이자 적용 여부
true무이자false일반salesCheckLinkUrlstring신용카드 매출전표 호출 URL. 승인된 카드 결제건의 매출전표를 확인할 수 있는 URL입니다. 구매자의 추가인증 완료 후 거래내역을 확인할 수 있습니다. 토스 매출전표 참고사항(/guide/credit-check)
cardMethodTypestring카드 타입. 승인된 카드의 타입을 구분할 수 있습니다. 예를 들어, 상점의 신용카드 결제 비율을 알고 싶다면 이 값을 활용해 주세요!
CREDIT신용카드CHECK체크카드PREPAYMENT선불카드cardNumberstring마스킹된 카드번호. 카드번호 16자리 중 중간자리는 마스킹됩니다.
cardUserTypestring카드 사용자 구분
PERSONAL본인 카드PERSONAL_FAMILY가족 카드CORP_PERSONAL법인지정 결제계좌 임직원CORP_PRIVATE법인 공용CORP_COMPANY법인지정 결제계좌 회사(하나카드만)cardBinNumberstring카드 BIN 넘버. 카드사에서 준 카드 BIN 번호(마스킹되어 있을 수 있습니다). 100% 신뢰는 불가합니다.
cardNum4Printstring사용자가 선택한 카드의 끝 4자리. 사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드번호 끝 4자리를 전달합니다. (카드사에 따라 마스킹이 포함되어 있을 수 있습니다)
accountBankCodestring은행 코드. 사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankNamestring은행 명. 은행코드 리스트(/guide/bank-code)
accountNumberstring계좌번호. 계좌번호는 일부 마스킹을 포함하고 있습니다.
msgstring응답이 성공이 아닌 경우 설명 메시지입니다.
errorCodestring에러 코드
PAYMENT_EXISTING_PAYMENT이미 존재하는 결제입니다.COMMON_INVALID_API_KEY바르지 않은 apiKey 입니다.COMMON_BREAK_TIME_OF_BANK지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해주세요.그 외의 에러코드에러코드 참조(/guide/error-code)예제
요청 예제
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;import 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)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 postResponse응답 예제
payMethod가 CARD인 경우
{
"code": 0,
"mode": "LIVE",
"orderNo": "TossTest20190718",
"amount": 2000,
"approvalTime": "2019-07-18 11:28:02",
"stateMsg": "결제 완료",
"discountedAmount": 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",
"cardMethodType": "CREDIT",
"cardNumber": "654321******1234",
"cardUserType": "PERSONAL",
"cardNum4Print": "1234",
"cardBinNumber": "654321"
}payMethod가 TOSS_MONEY인 경우
{
"code": 0,
"mode": "LIVE",
"orderNo": "TossTest20190718",
"amount": 2000,
"approvalTime": "2019-07-18 11:28:02",
"stateMsg": "결제 완료",
"discountedAmount": 0,
"paidAmount": 2000,
"payMethod": "TOSS_MONEY",
"payToken": "example-payToken",
"transactionId": "2da1ca05-d91d-410f-976d-7a610242da8a",
"cashReceiptMgtKey": "0123456-abcd-9abcd0Df",
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "110******676"
}