토스페이 연동가이드
API 레퍼런스자동 결제 API

빌링키 상태 조회

가맹점은 생성된 빌링키를 관리하고 회원 관리의 목적으로 빌링키의 상태를 조회할 수 있습니다. 사용자가 토스앱에서 결제수단을 변경한 경우 결제수단(payMethod) 정보가 업데이트될 수 있습니다.

빌링키 조회 API 사양은 다음과 같습니다.

각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.

엔드포인트

POSThttps://pay.toss.im/api/v1/billing-key/status

요청 파라미터

apiKeystring필수

결제 가맹점의 API Key. 가맹점에 발급된 API Key. 빌링키 생성요청 시 사용된 API Key와 동일해야 합니다. 그렇지 않으면 오류가 발생합니다.

최대 길이: 30
userIdstring필수

가맹점 사용자 식별 값. 가맹점이 생성한 사용자 식별 값. [빌링키 생성 요청](/reference/billing/create)에서 가맹점이 토스로 전달한 값

최대 길이: 50
displayIdstring

가맹점이 생성한 표시 가능한 빌링키 식별 값. 가맹점이 생성한 표시 가능한 빌링키 식별 값, 존재한다면 필수. [빌링키 생성 요청](/reference/billing/create)에서 가맹점이 토스로 전달한 값

최대 길이: 50

응답 파라미터

codeinteger

성공 여부

최대 길이: 2
가능한 값:
0: 성공-1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCodestring

에러코드. code가 -1일 때만 에러코드와 실패 사유를 전달합니다. (errorCode는 사전 예고 없이 추가될 수 있으니 유의가 필요합니다.)

최대 길이: 40
msgstring

에러 메시지. 한 가지 에러코드에 상황별로 다른 에러 메시지를 전달합니다. 여러 상황이 발생할 수 있으니 되도록이면 전달되는 에러 메시지 그대로를 처리해주세요.

최대 길이: 120
statusstring

빌링키 상태 값

최대 길이: 30
가능한 값:
ACTIVE: 빌링키 활성화 (사용자의 인증이 완료되어 사용할 수 있는 상태)CREATE: 미인증AUTH: 인증REMOVE: 삭제FAIL: 실패CANCEL: 취소
userIdstring

가맹점 사용자 식별 값

최대 길이: 50
displayIdstring

가맹점이 생성한 표시 가능한 빌링키 식별 값

최대 길이: 50
billingKeystring

생성된 자동결제 사용자 빌링키

최대 길이: 50
payMethodstring

사용자가 토스앱에서 인증한 결제수단. 토스 앱에서 선택한 결제수단에 따라 토스머니(TOSS_MONEY) 또는 카드(CARD)를 전달합니다.

최대 길이: 10
cardCompanyNointeger

사용자가 선택한 카드의 카드코드. 결제수단이 카드인 경우에만 포함

최대 길이: 2
cardCompanyNamestring

사용자가 선택한 카드의 카드사명. 사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드사명을 함께 전달합니다.

최대 길이: 2
cardNumberstring

마스킹된 카드번호

최대 길이: 20
cardNum4Printstring

사용자가 선택한 카드의 끝 4자리

최대 길이: 4
cardBinNumberstring

카드사에서 준 카드 BIN 번호(마스킹되어 있을 수도 있음)

최대 길이: 8
cardUserTypestring

카드 사용자 구분

최대 길이: 20
가능한 값:
PERSONAL: 본인 카드PERSONAL_FAMILY: 가족 카드CORP_PERSONAL: 법인지정 결제계좌 임직원CORP_PRIVATE: 법인 공용CORP_COMPANY: 법인지정 결제계좌 회사(하나카드만)
cardMethodTypestring

카드 타입. 승인된 카드의 타입을 구분

최대 길이: 10
가능한 값:
CREDIT: 신용카드CHECK: 체크카드PREPAYMENT: 선불카드
accountBankCodestring

사용자가 선택한 계좌의 은행코드. 결제수단이 토스머니인 경우에만 포함

최대 길이: 3
accountBankNamestring

사용자가 선택한 계좌의 은행명. [은행코드 리스트](/guide/bank-code)

최대 길이: 20
accountNumberstring

마스킹된 계좌번호

최대 길이: 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.body
Dim 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 postResponse

Example 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":"토스머니"
}