결제내역

1. KB국민카드 기업카드 결제내역 조회 시작kb_biz_card.payments.init

MCP 도구 이름 kb_biz_card__payments__init

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

결제내역 조회 화면을 열어 부서 목록과 기본 조회 조건을 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `kb_biz_card`이 API 고정값 (기본값) 예시 : kb_biz_card
action	string	-	Y	호출할 작업입니다. `kb_biz_card.payments.init`이 API 고정값 (기본값) 예시 : kb_biz_card.payments.init
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	date_from	string	N	조회시작일
	date_to	string	N	조회종료일

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-init-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.payments.init",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 departments 로 선택 가능한 부서 목록을, default_search_params 로 결제내역 조회의 기본 조건을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	default_search_params	결제내역 조회의 기본 조건 객체 - 선택한 부서 정보를 기관이 채워 줍니다
	departments	선택 가능한 부서 목록
	cards	이 카테고리는 카드 선택이 없어 항상 빈 배열입니다
	form_context	화면 진입에 필요한 부가 정보 객체
	session_context	이 조회에 쓰인 세션 컨텍스트 객체(provider · account_link_id · env_scope)
	raw_field_map	기관 원본 필드명 대응 객체

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.payments.init",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	INTERNAL_ERROR	포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류'(PROVIDER_UNAVAILABLE)와 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 인증서 인증 실패·세션 저장 실패 등 도메인 예외(KbBizCardLoginError/KbBizCardBusinessError)로 던져진 그 밖의 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

2. KB국민카드 기업카드 결제내역 페이지 조회kb_biz_card.payments.page

MCP 도구 이름 kb_biz_card__payments__page

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

앞서 정한 결제 조회 조건을 유지한 채 지정한 페이지만 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. kb_biz_card.payments.search 또는 kb_biz_card.payments.result 호출 응답의 search_context 를 그대로 넘겨야 합니다 - 직접 만들어 보내면 VALIDATION_INVALID_FIELD 로 거절됩니다. [KB국민카드 기업카드 로그인]
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `kb_biz_card`이 API 고정값 (기본값) 예시 : kb_biz_card
action	string	-	Y	호출할 작업입니다. `kb_biz_card.payments.page`이 API 고정값 (기본값) 예시 : kb_biz_card.payments.page
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

순번	변수명	타입	필수	설명
	search_context	object	Y	-
	page	number	Y	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-page-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.payments.page",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "search_context": "<필수: object>",
    "page": "<필수: number>"
  }
}'

Response

search 가 돌려준 search_context 조건 그대로, 지정한 페이지의 결제내역 건만 받습니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	이 페이지에서 읽은 건수
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next(payments 는 항상 이번 page·false 로 고정 - 위 주의 참고)
	rows	결제내역 목록(정리된 값)
	rows_raw	결제내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록
	company	조회 대상 회사(부서)명
	period	조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
	summary	합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.payments.page",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	INTERNAL_ERROR	포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류'(PROVIDER_UNAVAILABLE)와 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 인증서 인증 실패·세션 저장 실패 등 도메인 예외(KbBizCardLoginError/KbBizCardBusinessError)로 던져진 그 밖의 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

3. KB국민카드 기업카드 결제내역 전체 수집kb_biz_card.payments.result

MCP 도구 이름 kb_biz_card__payments__result

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

조건에 걸린 결제내역을 한 번에 모아 합계와 수집 범위까지 받습니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
이 액션은 실제 페이지 수를 읽지 않고 pagination.total_pages·has_next 를 언제나 이번 요청의 page·false 로 고정합니다(같은 provider 의 승인내역·매입내역은 정상). 결제내역이 여러 페이지여도 두 번째 페이지부터는 조용히 빠지므로, 전체가 필요하면 지금은 page 를 1씩 올려가며 kb_biz_card.payments.page 를 직접 반복 호출해 has_next 없이 직접 끝을 판단해야 합니다.
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `kb_biz_card`이 API 고정값 (기본값) 예시 : kb_biz_card
action	string	-	Y	호출할 작업입니다. `kb_biz_card.payments.result`이 API 고정값 (기본값) 예시 : kb_biz_card.payments.result
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
date_from	string	Y	조회시작일
date_to	string	Y	조회종료일
department_sequence_no	string	N	부서번호 예시 : 00000
department_name	string	N	부서명
query_scope	string	N	조회구분 예시 : 2
search_type	string	N	- 예시 : 1
max_pages	number	N	-

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-result-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.payments.result",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "2",
    "search_type": "1"
  }
}'

Response

1페이지부터 조건에 걸린 결제내역을 rows 로 한 번에 받습니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	이 페이지에서 읽은 건수
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next(payments 는 항상 이번 page·false 로 고정 - 위 주의 참고)
	rows	결제내역 목록(정리된 값)
	rows_raw	결제내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록
	company	조회 대상 회사(부서)명
	period	조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
	summary	합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.payments.result",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	INTERNAL_ERROR	포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류'(PROVIDER_UNAVAILABLE)와 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 인증서 인증 실패·세션 저장 실패 등 도메인 예외(KbBizCardLoginError/KbBizCardBusinessError)로 던져진 그 밖의 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

4. KB국민카드 기업카드 결제내역 조건 조회kb_biz_card.payments.search

MCP 도구 이름 kb_biz_card__payments__search

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

기간과 부서를 지정해 청구와 결제, 환급 내역을 합계까지 조회합니다.

KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]
이 액션은 실제 페이지 수를 읽지 않고 pagination.total_pages·has_next 를 언제나 이번 요청의 page·false 로 고정합니다(같은 provider 의 승인내역·매입내역은 정상). 결제내역이 여러 페이지여도 두 번째 페이지부터는 조용히 빠지므로, 전체가 필요하면 지금은 page 를 1씩 올려가며 kb_biz_card.payments.page 를 직접 반복 호출해 has_next 없이 직접 끝을 판단해야 합니다.
sandbox 환경에서는 실제 KB국민카드에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `kb_biz_card`이 API 고정값 (기본값) 예시 : kb_biz_card
action	string	-	Y	호출할 작업입니다. `kb_biz_card.payments.search`이 API 고정값 (기본값) 예시 : kb_biz_card.payments.search
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	Y	작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

변수명	타입	필수	설명
date_from	string	Y	조회시작일
date_to	string	Y	조회종료일
department_sequence_no	string	N	부서번호 예시 : 00000
department_name	string	N	부서명
query_scope	string	N	조회구분 예시 : 2
search_type	string	N	- 예시 : 1
page	number	N	- 예시 : 1

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-search-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_biz_card",
  "action": "kb_biz_card.payments.search",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "date_from": "<필수>",
    "date_to": "<필수>",
    "department_sequence_no": "00000",
    "query_scope": "2",
    "search_type": "1",
    "page": 1
  }
}'

Response

result.data 의 rows 로 조회된 결제내역 건을, pagination 으로 페이지 정보를, search_context 로 다음 페이지 조회(.page)에 그대로 넘길 조건을 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	account_link_id	연동 ID
	search_context	이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
	page	조회한 페이지 번호
	total_count	이 페이지에서 읽은 건수
	pagination	페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next(payments 는 항상 이번 page·false 로 고정 - 위 주의 참고)
	rows	결제내역 목록(정리된 값)
	rows_raw	결제내역 목록(기관 원본 문자열 그대로)
	raw_field_map	기관 원본 필드명 대응 객체
	pages_fetched	실제로 조회를 호출한 페이지 번호 목록
	source_pages	페이지별 조회 건수 목록
	company	조회 대상 회사(부서)명
	period	조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
	summary	합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_biz_card",
    "action": "kb_biz_card.payments.search",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	AUTH_REQUIRED	세션 없음 — KB국민카드 기업카드 세션이 없거나(로그인 전) 저장된 세션에 필요한 정보가 깨져 있습니다. 공동인증서 로그인을 다시 호출한 뒤 같은 account_link_id 로 다시 요청합니다. retryable=false - 재로그인 없이는 재시도해도 풀리지 않습니다.
	VALIDATION_INVALID_FIELD	파라미터 오류 — 필수값이 없거나 형식이 올바르지 않습니다(예: page<1, search_context 가 객체가 아님, 날짜 형식 오류, 소유하지 않은 account_link_id). retryable=false - page·search_context 는 반드시 같은 카테고리의 .search 또는 .result 응답을 그대로 다시 보냅니다.
	PROVIDER_TIMEOUT_CONNECT	연결 지연 — KB국민카드 포털 접속 자체가 시간 안에 되지 않았습니다. retryable 은 응답에 함께 옵니다.
	PROVIDER_TIMEOUT_READ	응답 지연 — 접속은 됐지만 응답이 시간 안에 오지 않았습니다. retryable 은 응답에 함께 옵니다.
	INTERNAL_ERROR	포털 응답 오류 — KB국민카드 포털이 오류 상태(4xx/5xx)로 응답했습니다. retryable=false - 위 '그 밖의 오류'(PROVIDER_UNAVAILABLE)와 코드가 다르니 재시도 가능 여부를 이 행 기준으로 판단합니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 인증서 인증 실패·세션 저장 실패 등 도메인 예외(KbBizCardLoginError/KbBizCardBusinessError)로 던져진 그 밖의 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.