개발자센터
V1
V2
파트너 정산 릴리즈 노트 기술 블로그

빌링키 관련 API

빌링키에 관련된 API 를 확인할 수 있습니다.

⌨ 빌링키 다건 조회

GET https://api.portone.io/v2/billing-keys

빌링키 다건 조회

Parameters

Query

billing_key*
array

빌링키

store_id
string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Responses

200
200 응답

billing_keys * Array[BillingKey]

빌링키 정보

BillingKey

billing_key * string

빌링키


merchant_id * string

고객사 ID


store_id * string

하위 상점 ID


channel * Channel

결제 채널 정보


origin Origin

결제를 요청한 근원에 대한 정보


customer * Customer

구매자 정보


issued_at string

발급 일시 (statusISSUED인 경우 제공)


custom_data string

커스텀 데이터


issue_id string

고객사가 채번 하는 빌링키 발급 건 고유 ID


issue_name string

빌링키 발급 건 이름


payment_method_detail * BillingKeyPaymentMethod

빌링키 결제수단 상세정보



id string

구매자 ID


name string

구매자 이름


birthYear string

구매자 생년


gender Gender

"MALE", "FEMALE", "OTHER"


email string

구매자 이메일


phone_number string

구매자 전화번호


one_line_address string

구매자 주소 (한 줄)


separated_address SeparatedAddress

구매자 주소 (단위별)

SeparatedAddress

country Country

국가

"AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"


province string

시/도/구


city string

도시


address_line_1 * string

일반 주소


address_line_2 * string

상세 주소



zipcode string

구매자 우편번호


401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR"


params object

에러 세부사항


⌨ 빌링키 발급

POST https://api.portone.io/v2/billing-keys

빌링키 발급

Parameters

Body

store_id
string

하위 상점 ID

customer
CustomerForm

고객 정보

custom_data
string
channel_key*
string

결제 채널 키

payment_method_option*
InstantBillingKeyPaymentMethodForm

가능한 결제 수단: 카드, 휴대폰 소액 결제 선택한 결제 수단에 따라

card

mobile_phone

중 하나에만 값이 들어있어야 합니다.

Responses

200
빌링키 발급 성공

billing_key * string


customer_id * string


requested_at * string


issued_at * string


400
잘못된 요청

code * string

INVALID_REQUEST: 파라미터를 포함한 요청을 처리하는 데에 실패했습니다. 올바른 형식의 파라미터를 전송했는지 확인해주세요.\

"INVALID_REQUEST"


params object

에러 상세 정보를 담은 파라미터 모음


401
인증 실패

code * string

UNAUTHORIZED: 권한이 없습니다. 올바른 API Key를 헤더에 제공했는지 확인해주세요.\

"UNAUTHORIZED"


params object

에러 상세 정보를 담은 파라미터 모음


403
권한 없음

code * string

PERMISSION_DENIED: 해당 요청을 수행하기 위한 권한이 없습니다.\

"PERMISSION_DENIED"


params object

에러 상세 정보를 담은 파라미터 모음


404
하위 상점이나 결제 채널을 찾을 수 없습니다.

code * string

STORE_NOT_FOUND: 하위 상점을 찾을 수 없습니다.
CHANNEL_NOT_FOUND: 결제 채널을 찾을 수 없습니다.\

"STORE_NOT_FOUND", "CHANNEL_NOT_FOUND"


params object

에러 상세 정보를 담은 파라미터 모음


500
내부 서버 에러

code * string

"PORTONE_ERROR", "PG_PROVIDER_ERROR"


params object

에러 상세 정보를 담은 파라미터 모음


address_line_1 * string

주소1


address_line_2 * string

주소2


city string

도시


province string

주, 도, 시


country Country

국가

"AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"


customer_id string

고객사의 고객 고유 ID - 값을 넣지 않으면 PortOne에서 자체 채번합니다.


phone_number string

휴대폰 번호


customer_name CustomerName

고객 이름 정보. full_name만 채워져 있거나, first_name & last_name이 채워져 있어야 함

CustomerName

full_name string


first_name string


last_name string



email string

고객 이메일


zipcode string

우편번호


address Address

주소 형식

Address

address_line_1 * string

주소1


address_line_2 * string

주소2


city string

도시


province string

주, 도, 시


country Country

국가

"AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"



gender Gender

성별

"MALE", "FEMALE", "OTHER"


birth_year string

출생연도


birth_month string

출생월


birth_day string

출생일


country Country

국가

"AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"


card InstantBillingKeyCardForm

빌링키 발급 시에 필요한 카드 관련 정보

InstantBillingKeyCardForm

card_credential * CardCredential

카드를 이용한 결제 및 빌링키 발급에 필요한 인증 관련 정보


cvc string


vbv VBV

3DS 인증 결과를 담는 객체 (Verified by Visa)



mobile_phone MobileForm

휴대폰을 이용한 소액결제와 정기결제를 위한 빌링키 발급 시에 사용하는 휴대폰 관련 정보

MobileForm

carrier Carrier

휴대폰 통신사

"SKT", "KT", "LGU", "HELLO", "KCT", "SK7"



⌨ 빌링키 단건 조회

GET https://api.portone.io/v2/billing-keys/{billing_key}

빌링키 단건 조회

Parameters

Path

billing_key*
string

빌링키

Query

store_id
string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Responses

200
200 응답

billing_key * BillingKey

빌링키 정보

BillingKey

billing_key * string

빌링키


merchant_id * string

고객사 ID


store_id * string

하위 상점 ID


channel * Channel

결제 채널 정보


origin Origin

결제를 요청한 근원에 대한 정보


customer * Customer

구매자 정보


issued_at string

발급 일시 (statusISSUED인 경우 제공)


custom_data string

커스텀 데이터


issue_id string

고객사가 채번 하는 빌링키 발급 건 고유 ID


issue_name string

빌링키 발급 건 이름


payment_method_detail * BillingKeyPaymentMethod

빌링키 결제수단 상세정보



id string

구매자 ID


name string

구매자 이름


birthYear string

구매자 생년


gender Gender

"MALE", "FEMALE", "OTHER"


email string

구매자 이메일


phone_number string

구매자 전화번호


one_line_address string

구매자 주소 (한 줄)


separated_address SeparatedAddress

구매자 주소 (단위별)

SeparatedAddress

country Country

국가 코드

"AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BS", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW"


province string

시/도/구


city string

도시


address_line_1 * string

일반 주소


address_line_2 * string

상세 주소



zipcode string

구매자 우편번호


401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


404
리소스를 찾을 수 없음

code * string

"BILLING_KEY_NOT_FOUND"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR"


params object

에러 세부사항


⌨ 빌링키 삭제

DELETE https://api.portone.io/v2/billing-keys/{billing_key}

빌링키 삭제

Parameters

Path

billing_key*
string

빌링키

Query

store_id
string

하위 상점 ID - 값을 넣지 않으면 Merchant 유저의 기본값으로 설정된 상점의 id가 입력됩니다.

Responses

200
200 응답

deleted_at * string

빌링키 삭제 시각


400
금지된 요청

code * string

"INVALID_REQUEST", "BILLING_KEY_NOT_ISSUED", "BILLING_KEY_ALREADY_DELETED", "BOOKED_SCHEDULE_EXISTENCE"


params object

에러 세부사항


401
인증 실패

code * string

"UNAUTHORIZED"


params object

에러 세부사항


404
리소스를 찾을 수 없음

code * string

"BILLING_KEY_NOT_FOUND"


params object

에러 세부사항


500
내부 서버 오류

code * string

"PORTONE_ERROR", "PG_PROVIDER_ERROR"


params object

에러 세부사항