개발자 문서
API 레퍼런스

결제내역 - KB국민카드 기업카드

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

MCP 도구 이름 kb_biz_card__payments__init

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_biz_card이 API 고정값 (기본값)

예시 : kb_biz_card

actionstring-Y호출할 작업입니다.
  • kb_biz_card.payments.init이 API 고정값 (기본값)

예시 : kb_biz_card.payments.init

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
date_fromstringN결과의 default_search_params 에 그대로 돌려줄 조회 시작일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다
date_tostringN결과의 default_search_params 에 그대로 돌려줄 조회 종료일입니다. 이 값으로 조회하지는 않으며 보내지 않으면 null 입니다
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: init-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 departments 로 선택 가능한 부서 목록을, default_search_params 로 결제내역 조회의 기본 조건을 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
default_search_paramsobject결제내역 조회의 기본 조건 객체 - 선택한 부서 정보를 기관이 채워 줍니다
departmentsstring | number | boolean | object | array | null선택 가능한 부서 목록
cardsarray이 카테고리는 카드 선택이 없어 항상 빈 배열입니다
form_contextobject화면 진입에 필요한 부가 정보 객체
session_contextobject이 조회에 쓰인 세션 컨텍스트 객체(provider · account_link_id · env_scope)
raw_field_mapobject기관 원본 필드명 대응 객체
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

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

MCP 도구 이름 kb_biz_card__payments__page

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

  • KB국민카드 기업카드 세션 로그인을 먼저 호출해 세션을 등록한 뒤, 같은 account_link_id 로 호출합니다. [KB국민카드 기업카드 로그인]

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_biz_card이 API 고정값 (기본값)

예시 : kb_biz_card

actionstring-Y호출할 작업입니다.
  • kb_biz_card.payments.page이 API 고정값 (기본값)

예시 : kb_biz_card.payments.page

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
search_contextobjectY앞서 같은 종류의 조회(search)가 돌려준 결과의 search_context 객체를 그대로 보냅니다. 그 안에 조회 조건이 들어 있어 조건을 다시 적지 않고 다른 쪽을 받습니다
pagenumberY받을 쪽 번호입니다. 1 이상의 정수이고 search_context 와 함께 보냅니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: page-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • search 가 돌려준 search_context 조건 그대로, 지정한 페이지의 결제내역 건만 받습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber이 페이지에서 읽은 건수
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray결제내역 목록(정리된 값)
rows_rawarray결제내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
companystring | number | boolean | object | array | null조회 대상 회사(부서)명
periodobject조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
summaryobject합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

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

MCP 도구 이름 kb_biz_card__payments__result

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

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

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_biz_card이 API 고정값 (기본값)

예시 : kb_biz_card

actionstring-Y호출할 작업입니다.
  • kb_biz_card.payments.result이 API 고정값 (기본값)

예시 : kb_biz_card.payments.result

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
date_fromstringY조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

department_namestringN기관 조회 화면의 부서명 칸에 실어 보내는 부서 이름입니다. 보내지 않으면 빈 값입니다
query_scopestringN기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 2

search_typestringN결제내역의 조회 구분을 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 1 입니다

예시 : 1

max_pagesnumberN한꺼번에 모을 최대 쪽 수입니다. 1 이상의 정수이고 보내지 않으면 조회된 모든 쪽을 모읍니다
output_formatsarrayN이 결과를 엑셀(xlsx) 파일로도 받으려면 적습니다. 예: ["xlsx"]. 파일은 result.artifacts 에 함께 오고, 빼면 데이터만 옵니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: result-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • 1페이지부터 조건에 걸린 결제내역을 화면이 알려준 페이지 링크만큼 모아(max_pages 로 상한 지정 가능 - 링크에 없는 페이지는 모으지 못합니다) rows 로 한 번에 받습니다.
  • 아래 표의 rows[] 줄은 엑셀 파일(params 의 output_formats 에 ["xlsx"])의 열로 내보내는 칸이고, 열 이름은 엑셀 파일 맨 윗줄의 머리글입니다.
  • 아래 표의 줄은 엑셀로 내보내는 열이라 응답 행의 칸 전부가 아닐 수 있습니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber이 페이지에서 읽은 건수
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray결제내역 목록(정리된 값)
rows[].payment_datestring | null결제일
rows[].department_sequence_nostring | null부서번호
rows[].department_namestring | null부서명
rows[].payment_kindstring | null결제구분
rows[].categorystring | null구분
rows[].principal_amount_displaystring | null원금
rows[].fee_amount_displaystring | null수수료
rows[].overdue_fee_amount_displaystring | null연체료
rows[].other_amount_displaystring | null기타대금
rows[].total_amount_displaystring | null합계
rows_rawarray결제내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
companystring | number | boolean | object | array | null조회 대상 회사(부서)명
periodobject조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
summaryobject합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.

MCP 도구 이름 kb_biz_card__payments__search

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

기간을 지정해 청구와 결제, 환급 내역을 한 페이지씩 결제일별로 조회합니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • kb_biz_card이 API 고정값 (기본값)

예시 : kb_biz_card

actionstring-Y호출할 작업입니다.
  • kb_biz_card.payments.search이 API 고정값 (기본값)

예시 : kb_biz_card.payments.search

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
date_fromstringY조회 시작일입니다. YYYYMMDD 나 YYYY-MM-DD 로 보내며 하이픈과 점은 떼고 기관에 보냅니다
date_tostringY조회 종료일입니다. 시작일과 같은 형식으로 보냅니다
department_sequence_nostringN조회할 부서의 번호입니다. 부서 목록 조회(common.departments.select) 결과의 department_sequence_no 를 넣으며 보내지 않거나 비우면 00000 을 보냅니다. 모든 부서를 한꺼번에 조회하는 값은 확인하지 않았으니 부서마다 번호를 넣어 조회하세요

예시 : 00000

department_namestringN기관 조회 화면의 부서명 칸에 실어 보내는 부서 이름입니다. 보내지 않으면 빈 값입니다
query_scopestringN기관 조회 화면의 조회구분 칸에 실어 보내는 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않거나 비우면 2 입니다. 기본값 밖의 값은 확인하지 않았으니 비워 두기를 권합니다

예시 : 2

search_typestringN결제내역의 조회 구분을 정하는 기관 조회 화면의 값입니다. 값은 검사하지 않고 그대로 보내며 보내지 않으면 1 입니다

예시 : 1

pagenumberN받을 쪽 번호입니다. 1부터 세는 정수이고 보내지 않으면 1 입니다

예시 : 1

  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: search-$(date +%s)-$RANDOM" \
  --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

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 rows 로 조회된 결제내역 건을, pagination 으로 페이지 정보를, search_context 로 다음 페이지 조회(.page)에 그대로 넘길 조건을 확인합니다.
  • 여러 JSON 타입이 함께 표시된 칸은 서버가 세부 타입을 고정하지 않는 기관 원문 또는 동적 값입니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
account_link_idstring연동 ID
search_contextobject이 조회 조건 객체 - .page 호출에 그대로 넘깁니다
pagenumber조회한 페이지 번호
total_countnumber이 페이지에서 읽은 건수
paginationobject페이지 정보 객체 - current_page · pages · total_pages · total_count · has_next
rowsarray결제내역 목록(정리된 값)
rows_rawarray결제내역 목록(기관 원본 문자열 그대로)
raw_field_mapobject기관 원본 필드명 대응 객체
pages_fetchedarray실제로 조회를 호출한 페이지 번호 목록
source_pagesarray페이지별 조회 건수 목록
companystring | number | boolean | object | array | null조회 대상 회사(부서)명
periodobject조회 기간 객체 - date_from · date_to · query_text(기관이 보여준 조회기간 문구)
summaryobject합계 객체 - billing_total(청구) · payment_total(결제) · refund_total(환급)
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "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그 밖의 오류 — 인증서 인증 실패·세션 저장 실패처럼 위에서 나눈 경우 밖의 KB국민카드 연동 오류가 이 코드 하나로 옵니다(원인 문구는 매번 다릅니다). retryable=true 로 표시되지만, 원인이 인증서 자체거나 값 자체가 잘못됐다면 재시도로 풀리지 않습니다 - 메시지를 먼저 확인합니다.