토스페이 연동가이드

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

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

POST

요청 파라미터

apiKeystring필수

가맹점 API Key

최대 30자

userIdstring필수

가맹점 사용자 식별 값

최대 50자

displayIdstring

다중 빌링키 식별 값

최대 50자

응답 파라미터

userIdstring필수

가맹점 사용자 식별 값

최대 50자

billingKeystring필수

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

최대 50자

statusstring필수

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

최대 30자

가능한 값:

ACTIVECREATEAUTHREMOVEFAILCANCEL

payMethodstring

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

최대 10자

가능한 값:

TOSS_MONEYCARD

cardCompanyNointeger (int32)

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

cardCompanyNamestring

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

cardNum4Printstring

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

최대 4자

cardNumberstring

마스킹된 카드번호

최대 20자

cardBinNumberstring

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

최대 8자

cardUserTypestring

카드 사용자 구분. PERSONAL: 본인 카드, PERSONAL_FAMILY: 가족 카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용, CORP_COMPANY: 법인지정 결제계좌 회사(하나카드만)

최대 20자

가능한 값:

PERSONALPERSONAL_FAMILYCORP_PERSONALCORP_PRIVATECORP_COMPANY

cardMethodTypestring

카드 타입. 승인된 카드의 타입을 구분. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드

최대 10자

가능한 값:

CREDITCHECKPREPAYMENT

accountBankNamestring

사용자가 선택한 계좌의 은행명

최대 20자

accountBankCodestring

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

최대 3자

accountNumberstring

마스킹된 계좌번호. 토스머니일 경우 '토스머니'가 전달됩니다.

최대 30자

codeinteger (int32)

응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)

errorCodestring

에러 코드

msgstring

응답이 성공이 아닌 경우 설명 메시지

displayIdstring

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

최대 50자

빌링키 상태 조회

요청 파라미터

응답 파라미터

요청 예제

응답 예제