빌링키 상태 조회
가맹점은 생성된 빌링키를 관리하고 회원 관리의 목적으로 빌링키의 상태를 조회할 수 있습니다. 사용자가 토스앱에서 결제수단을 변경한 경우 결제수단(payMethod) 정보가 업데이트될 수 있습니다.
빌링키 조회 API 사양은 다음과 같습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
엔드포인트
요청 파라미터
결제 가맹점의 API Key
가맹점에 발급된 API Key
빌링키 생성요청 시 사용된 API Key와 동일해야 합니다. 그렇지 않으면 오류가 발생합니다.
가맹점 사용자 식별 값
가맹점이 생성한 사용자 식별 값
빌링키 생성 요청에서 가맹점이 토스로 전달한 값
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"
}'응답 파라미터
성공 여부
| 값 | 설명 |
|---|---|
| 0 | 성공 |
| -1 | 실패 (실패 사유는 msg와 errorCode로 제공) |
에러코드
code가 -1일 때만 에러코드와 실패 사유를 전달합니다.
(errorCode는 사전 예고 없이 추가될 수 있으니 유의가 필요합니다.)
에러 메시지
한 가지 에러코드에 상황별로 다른 에러 메시지를 전달합니다.
여러 상황이 발생할 수 있으니 되도록이면 전달되는 에러 메시지 그대로를 처리해주세요.
빌링키 상태 값
| 값 | 설명 |
|---|---|
| ACTIVE | 빌링키 활성화 (사용자의 인증이 완료되어 사용할 수 있는 상태) |
| CREATE | 미인증 |
| AUTH | 인증 |
| REMOVE | 삭제 |
| FAIL | 실패 |
| CANCEL | 취소 |
가맹점 사용자 식별 값
가맹점이 생성한 표시 가능한 빌링키 식별 값
생성된 자동결제 사용자 빌링키
사용자가 토스앱에서 인증한 결제수단
토스 앱에서 선택한 결제수단에 따라 토스머니(TOSS_MONEY) 또는 카드(CARD)를 전달합니다.
사용자가 선택한 카드의 카드코드
결제수단이 카드인 경우에만 포함
사용자가 선택한 카드의 카드사명
사용자가 선택한 결제수단(payMethod)이 '카드'인 경우 카드사명을 함께 전달합니다.
마스킹된 카드번호
사용자가 선택한 카드의 끝 4자리
카드사에서 준 카드 BIN 번호(마스킹되어 있을 수도 있음)
카드 사용자 구분
| 값 | 설명 |
|---|---|
| PERSONAL | 본인 카드 |
| PERSONAL_FAMILY | 가족 카드 |
| CORP_PERSONAL | 법인지정 결제계좌 임직원 |
| CORP_PRIVATE | 법인 공용 |
| CORP_COMPANY | 법인지정 결제계좌 회사(하나카드만) |
카드 타입
승인된 카드의 타입을 구분
| 값 | 설명 |
|---|---|
| CREDIT | 신용카드 |
| CHECK | 체크카드 |
| PREPAYMENT | 선불카드 |
사용자가 선택한 계좌의 은행코드
결제수단이 토스머니인 경우에만 포함
사용자가 선택한 계좌의 은행명
마스킹된 계좌번호
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":"토스머니"
}