빌링키 상태 조회
가맹점은 생성된 빌링키를 관리하고 회원 관리의 목적으로 빌링키의 상태를 조회할 수 있습니다. 사용자가 토스앱에서 결제수단을 변경한 경우 결제수단(payMethod) 정보가 업데이트될 수 있습니다.
빌링키 조회 API 사양은 다음과 같습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
https://pay.toss.im/api/v1/billing-key/status요청 파라미터
apiKeystring필수결제 가맹점의 API Key. 가맹점에 발급된 API Key. 빌링키 생성요청 시 사용된 API Key와 동일해야 합니다. 그렇지 않으면 오류가 발생합니다.
30userIdstring필수가맹점 사용자 식별 값. 가맹점이 생성한 사용자 식별 값. [빌링키 생성 요청](/reference/billing/create)에서 가맹점이 토스로 전달한 값
50displayIdstring가맹점이 생성한 표시 가능한 빌링키 식별 값. 가맹점이 생성한 표시 가능한 빌링키 식별 값, 존재한다면 필수. [빌링키 생성 요청](/reference/billing/create)에서 가맹점이 토스로 전달한 값
50응답 파라미터
codeinteger성공 여부
20: 성공-1: 실패 (실패 사유는 msg와 errorCode로 제공)errorCodestring에러코드. code가 -1일 때만 에러코드와 실패 사유를 전달합니다. (errorCode는 사전 예고 없이 추가될 수 있으니 유의가 필요합니다.)
40msgstring에러 메시지. 한 가지 에러코드에 상황별로 다른 에러 메시지를 전달합니다. 여러 상황이 발생할 수 있으니 되도록이면 전달되는 에러 메시지 그대로를 처리해주세요.
120statusstring빌링키 상태 값
30ACTIVE: 빌링키 활성화 (사용자의 인증이 완료되어 사용할 수 있는 상태)CREATE: 미인증AUTH: 인증REMOVE: 삭제FAIL: 실패CANCEL: 취소userIdstring가맹점 사용자 식별 값
50displayIdstring가맹점이 생성한 표시 가능한 빌링키 식별 값
50billingKeystring생성된 자동결제 사용자 빌링키
50payMethodstring사용자가 토스앱에서 인증한 결제수단. 토스 앱에서 선택한 결제수단에 따라 토스머니(TOSS_MONEY) 또는 카드(CARD)를 전달합니다.
10cardCompanyNointeger사용자가 선택한 카드의 카드코드. 결제수단이 카드인 경우에만 포함
2cardCompanyNamestring사용자가 선택한 카드의 카드사명. 사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드사명을 함께 전달합니다.
2cardNumberstring마스킹된 카드번호
20cardNum4Printstring사용자가 선택한 카드의 끝 4자리
4cardBinNumberstring카드사에서 준 카드 BIN 번호(마스킹되어 있을 수도 있음)
8cardUserTypestring카드 사용자 구분
20PERSONAL: 본인 카드PERSONAL_FAMILY: 가족 카드CORP_PERSONAL: 법인지정 결제계좌 임직원CORP_PRIVATE: 법인 공용CORP_COMPANY: 법인지정 결제계좌 회사(하나카드만)cardMethodTypestring카드 타입. 승인된 카드의 타입을 구분
10CREDIT: 신용카드CHECK: 체크카드PREPAYMENT: 선불카드accountBankCodestring사용자가 선택한 계좌의 은행코드. 결제수단이 토스머니인 경우에만 포함
3accountBankNamestring사용자가 선택한 계좌의 은행명. [은행코드 리스트](/guide/bank-code)
20accountNumberstring마스킹된 계좌번호
30예제
Example Request
curl https://pay.toss.im/api/v1/billing-key/status \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
//"displayId": "TEST_SERVICE_1",
"userId": "TOSS-TEST-1"
}'import java.nio.charset.StandardCharsets;
import java.net.URL;
import java.net.URLConnection;
import java.io.BufferedOutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
URL url = null;
URLConnection connection = null;
StringBuilder responseBody = new StringBuilder();
try {
url = new URL("https://pay.toss.im/api/v1/billing-key/status");
connection = url.openConnection();
connection.addRequestProperty("Content-Type", "application/json");
connection.setDoOutput(true);
connection.setDoInput(true);
org.json.simple.JSONObject jsonBody = new org.json.simple.JSONObject();
jsonBody.put("apiKey", "sk_test_w5lNQylNqa5lNQe013Nq");
// jsonBody.put("displayId", "TEST_SERVICE_1");
jsonBody.put("userId", "TOSS-TEST-1");
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());<?php
$arrayBody = array();
$arrayBody["apiKey"] = "sk_test_w5lNQylNqa5lNQe013Nq";
// $arrayBody["displayId"] = "TEST_SERVICE_1";
$arrayBody["userId"] = "TOSS-TEST-1";
$jsonBody = json_encode($arrayBody);
$ch = curl_init('https://pay.toss.im/api/v1/billing-key/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;
?>import requests
url = "https://pay.toss.im/api/v1/billing-key/status"
data = {
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
# "displayId": "TEST_SERVICE_1",
"userId": "TOSS-TEST-1",
}
response = requests.post(url, json=data)
print(response.text)require 'net/http'
require 'uri'
require 'json'
uri = URI.parse("https://pay.toss.im/api/v1/billing-key/status")
params = {
"apiKey" => "sk_test_w5lNQylNqa5lNQe013Nq",
# "displayId" => "TEST_SERVICE_1",
"userId" => "TOSS-TEST-1",
}
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Content-Type'] = 'application/json'
request.body = params.to_json
response = http.request(request)
puts response.bodyDim data, httpRequest, postResponse
data = "{""apiKey"":""sk_test_w5lNQylNqa5lNQe013Nq"", ""userId"":""TOSS-TEST-1""}"
' data = data & ",""displayId"":""TEST_SERVICE_1"""
Set httpRequest = Server.CreateObject("MSXML2.ServerXMLHTTP")
httpRequest.Open "POST", "https://pay.toss.im/api/v1/billing-key/status", False
httpRequest.SetRequestHeader "Content-Type", "application/json"
httpRequest.Send data
postResponse = httpRequest.ResponseText
Response.Write postResponseExample Response
// payMethod 가 CARD 일때
{
"code": 0,
"userId": "TEST=2023-07-03T14:29:00.201Z",
"displayId": "테스트777",
"billingKey": "8JZBi0gmKZlfxaV4Zm4762",
"status": "ACTIVE",
"payMethod": "CARD",
"cardMethodType": "CREDIT",
"cardUserType": "PERSONAL",
"cardCompanyNo": 7,
"cardCompanyName": "우리",
"cardNum4Print": "410*",
"cardNumber": "531764******410*",
"cardBinNumber": "531764"
}
// payMethod 가 TOSS_MONEY(계좌) 일때
{
"code": 0,
"userId": "TEST=2023-07-03T14:29:00.201Z",
"displayId": "테스트777",
"billingKey": "8JZBi0gmKZlfxaV4Zm4762",
"status": "ACTIVE",
"payMethod": "TOSS_MONEY",
"accountBankName": "신한은행",
"accountBankCode": "088",
"accountNumber": "110******676" // 토스머니일 경우 "accountNumber":"토스머니"
}