> 지속적인 프로세스 개선 > 결제 처리 > Adyen > 데이터 템플릿

결제 처리 데이터 템플릿

Adyen

결제 처리 데이터 템플릿

이 템플릿은 Adyen 결제 처리를 분석하는 데 필요한 데이터를 수집하는 방법을 안내합니다. 추적해야 할 데이터 속성과 프로세스 활동, 데이터 추출 방법을 설명합니다. 효과적인 process mining에 필요한 정보를 빠짐없이 확보하는 데 활용하세요.

수집 권장 속성
추적할 주요 활동
Adyen 데이터 추출 안내

이벤트 로그가 처음이신가요? 알아보기 process mining 이벤트 로그 만드는 방법.

템플릿 다운로드

결제 처리 속성

Adyen의 결제 처리를 분석할 때 이벤트 로그에 포함할 것을 권장하는 데이터 필드입니다.

5 필수 6 권장 8 선택 사항

	이름	설명
	결제 거래 ID PspReference	Adyen이 각 결제 거래에 부여하는 고유 참조 식별자입니다.
설명 이 속성은 Adyen 환경에서 결제 전 과정의 기본 키로 사용됩니다. 최초 결제 요청을 승인, 매입, 정산, 환불 또는 차지백과 같은 후속 이벤트에 연결합니다. 분석에서는 이 ID를 사용해 개별 이벤트를 하나의 케이스로 묶고 전체 프로세스를 재구성합니다. 분석가는 구매자가 결제를 시작한 시점부터 최종 정산까지 해당 결제의 구체적인 흐름을 추적할 수 있습니다. 중요한 이유 서로 연결되지 않은 이벤트를 하나의 프로세스 인스턴스로 묶어 process mining에 활용하는 기본 연결 고리입니다. 확보 방법 Adyen Payment Response의 'pspReference' 또는 Settlement Detail Report의 'PSP Reference' 열입니다. 예시 851564567890123479145612345678908825641234567890
	이벤트 타임스탬프 EventDate	해당 결제 활동이 발생한 날짜와 시간입니다.
설명 이 속성은 승인이나 정산과 같은 이벤트가 시스템에 기록된 정확한 시각을 저장합니다. 이를 통해 케이스 내 활동을 시간순으로 정렬할 수 있습니다. 분석에서는 처리 시간 계산, 병목 식별, 시간에 따른 시스템 처리량 파악에 중요합니다. '전체 결제 처리 시간'과 같은 시간 기반 KPI를 계산하는 데 사용됩니다. 중요한 이유 이벤트 정렬과 모든 기간 기반 지표 계산에 필요합니다. 확보 방법 Adyen Notification Webhooks의 'eventDate' 필드입니다. 예시 2023-10-27T10:00:00+01:002023-10-27T10:05:30+01:002023-10-28T09:15:00+01:00
	활동명 EventCode	결제 프로세스에서 발생하는 구체적인 단계 또는 작업입니다.
설명 이 속성은 AUTHORISATION, CAPTURE, REFUND와 같이 발생한 구체적인 이벤트를 나타냅니다. 프로세스 맵의 노드를 구성하고 거래 흐름을 결정합니다. 분석할 때는 이 코드를 사람이 이해하기 쉬운 활동명으로 바꿔 프로세스 흐름을 시각화합니다. 코드 순서가 달라지면 정상적인 자동 처리와 예외 처리처럼 서로 다른 프로세스 경로를 나타냅니다. 중요한 이유 프로세스 마이닝 모델에서 프로세스의 ‘무엇’을 정의해 프로세스 흐름을 시각화합니다. 확보 방법 Adyen Notification Webhooks의 'eventCode' 필드입니다. 예시 AUTHORISATIONCAPTUREREFUNDCANCELLATIONCHARGEBACK
	원천 시스템 SourceSystem	데이터가 생성된 시스템의 이름입니다.
설명 이 고정 속성은 레코드가 Adyen에서 생성되었음을 나타냅니다. Adyen과 SAP처럼 여러 시스템의 데이터를 결합해 process mining을 수행할 때 데이터 계보를 추적하는 데 중요합니다. 분석에서는 결제 게이트웨이, ERP 또는 주문 관리 시스템 중 어느 곳에서 활동이 발생했는지 구분해 필터링할 수 있습니다. 중요한 이유 여러 시스템을 대상으로 process mining을 수행할 때 데이터 계보를 추적하는 데 필요합니다. 확보 방법 데이터 추출 중에는 값이 고정됩니다. 예시 AdyenAdyen_Production
	최종 데이터 업데이트 LastDataUpdate	레코드를 마지막으로 추출하거나 새로 고친 시각입니다.
설명 이 속성은 process mining 모델의 데이터 최신성을 나타냅니다. 사용자는 현재 실시간 데이터와 스냅샷 중 무엇을 보고 있는지 확인할 수 있습니다. 분석에서는 주로 데이터 거버넌스와 데이터 파이프라인의 정상 작동 여부를 확인하는 기술 필드로 사용됩니다. 중요한 이유 데이터 최신성을 추적하는 기술 필드입니다. 확보 방법 데이터 추출 시점의 시스템 시간입니다. 예시 2023-10-30T12:00:00Z
	가맹점 계정 MerchantAccount	Adyen에서 거래를 처리하는 특정 가맹점 계정입니다.
설명 Adyen에서는 하나의 회사 계정 아래 여러 가맹점 계정을 운영할 수 있습니다. 이 속성은 결제를 처리한 사업부, 브랜드 또는 지역 법인을 식별합니다. 분석에서는 주요 세분화 기준으로 사용됩니다. 사업부나 브랜드별 실적, 실패율, 거래량을 비교해 개선이 필요한 영역을 찾을 수 있습니다. 중요한 이유 사업부 또는 자회사별 실적을 구분하는 데 사용됩니다. 확보 방법 Adyen Payment Request/Response의 'merchantAccount'입니다. 예시 MyStore_UKMyStore_USGlobalSales_Main
	거래 금액 PaymentAmount	결제 거래의 금액입니다.
설명 이 속성은 거래의 금전적 가치를 나타냅니다. 원시 데이터에는 보통 최소 통화 단위(예: 센트)로 저장되므로 보고에 사용하기 전에 변환해야 합니다. '결제 처리량' 대시보드에 활용되며, 금액이 큰 재작업 케이스의 우선순위를 정하는 데 도움이 됩니다. 처리된 총 거래량과 거래 실패로 인한 재무 영향을 계산할 때도 사용됩니다. 중요한 이유 재무 영향 분석과 처리량 모니터링에 필요합니다. 확보 방법 Adyen Payment Request의 'amount.value'입니다. 예시 10005509900
	거절 사유 RefusalReason	결제가 거절되거나 실패한 이유를 설명하는 문구입니다.
설명 거래가 실패하면 Adyen은 사유 코드나 설명(예: '잔액 부족', 'CVC 거절', '카드 만료')을 제공합니다. '결제 거래 실패율' 대시보드에서 주요 분석 기준으로 사용됩니다. 사유를 분석하면 실패 원인이 기술 문제인지, 사기 방지 규칙인지, 구매자 행동인지 파악하고 적절한 개선 조치를 정할 수 있습니다. 중요한 이유 결제 실패의 근본 원인을 분석하는 주요 속성입니다. 확보 방법 Adyen Payment Response의 'refusalReason'입니다. 예시 거절됨잔액 부족카드 만료매입사 오류사기
	결제 상태 PaymentStatus	결제의 현재 상태입니다(예: 승인됨, 정산됨, 거절됨).
설명 이 속성은 결제 거래의 최신 상태를 나타냅니다. 보통 케이스에서 가장 최근에 발생한 활동을 기준으로 합니다. 케이스를 빠르게 필터링할 수 있습니다(예: '현재 거절된 결제 모두 표시'). '결제 처리량 및 상태 모니터링' 대시보드에 필요합니다. 중요한 이유 거래의 현재 상태를 한눈에 보여줍니다. 확보 방법 케이스의 마지막 이벤트 코드를 기준으로 합니다. 예시 정산됨거절됨승인됨
	결제 수단 PaymentMethod	Visa, PayPal 등 구매자가 결제에 사용한 수단입니다.
설명 이 속성은 신용카드 브랜드(Visa, MC), 디지털 지갑(PayPal, Apple Pay), 현지 결제 수단(iDEAL, Sofort) 등 결제에 사용된 수단의 유형을 기록합니다. '결제 수단별 실적 인사이트' 대시보드에서 중요한 기준으로 활용됩니다. 결제 수단별 승인율, 처리 속도, 기술적 오류를 비교할 수 있습니다. 중요한 이유 결제 제공업체별 성공률과 비용을 분석하는 데 필요합니다. 확보 방법 Adyen Payment Response의 'paymentMethod.brand' 또는 'paymentMethod.type'입니다. 예시 visamcpaypalidealklarna
	재작업 여부 IsRework	거래 재시도 또는 오류 수정이 있었는지 나타내는 표시입니다.
설명 케이스에 승인 시도가 여러 번 있거나 '결제 거절' 후 재시도와 같은 활동이 포함되면 참으로 설정되는 불리언 값입니다. '결제 재작업 및 예외 집중 영역' 대시보드에서 사용됩니다. 분석가는 이 속성으로 문제가 있는 케이스를 필터링해 프로세스 흐름이 정상 경로를 따르지 않는 이유를 파악할 수 있습니다. 중요한 이유 수동 또는 시스템 개입이 필요한 비효율적인 케이스를 식별합니다. 확보 방법 실패 이벤트 발생 횟수가 0보다 큰지 기준으로 계산됩니다. 예시 truefalse
	고객 ID ShopperReference	여러 거래에서 구매자를 식별하는 고유 참조값입니다.
설명 이 식별자는 여러 거래를 동일한 고객과 연결합니다. 결제 요청 시 가맹점이 제공합니다. 분석에서는 고객을 기준으로 거래를 살펴볼 수 있습니다. 사기 사례에서 반복적으로 문제를 일으키는 고객을 찾거나, 성공한 거래에서 충성 고객을 파악할 수 있습니다. '고객' 일반 매핑에도 사용됩니다. 중요한 이유 고객별 집계와 행동 분석을 지원합니다. 확보 방법 Adyen Payment Request의 'shopperReference'입니다. 예시 CUST-001user_12345email@example.com
	구매자 국가 ShopperCountry	구매자의 두 글자 국가 코드입니다.
설명 이 속성은 구매자의 위치를 나타내며, 일반적으로 카드 발급 국가나 청구지 주소를 기준으로 합니다. 지역별 실적 분석에 사용됩니다. 현지 은행 인프라의 영향으로 특정 국가에서 거절률이 높거나 처리 시간이 길어지는지 파악할 수 있습니다. 중요한 이유 지역별 결제 실적을 구분해 분석할 수 있습니다. 확보 방법 Adyen Payment Request의 'countryCode' 또는 'billingAddress.country'입니다. 예시 NLUSDE
	구매자 상호작용 유형 ShopperInteraction	결제가 Ecommerce, POS 또는 정기 결제(ContAuth)인지 나타냅니다.
설명 이 속성은 구매자와 가맹점 간 상호작용 유형을 구분합니다. 일반적인 값은 `Ecommerce`(온라인), `POS`(매장), `ContAuth`(정기 결제)입니다. 분석에서는 비즈니스 모델과 판매 채널을 구분하는 데 사용합니다. POS와 Ecommerce의 프로세스 흐름은 크게 다를 수 있으므로, 정확한 프로세스 탐색을 위한 중요한 필터입니다. 중요한 이유 온라인, 매장, 정기 결제의 프로세스 흐름을 구분합니다. 확보 방법 Adyen Payment Request의 'shopperInteraction'입니다. 예시 EcommerceContAuthPOSMoto
	매입사 참조번호 AcquirerReference	매입 은행이 제공하는 참조번호입니다.
설명 카드 거래를 처리하는 금융기관(매입사)이 부여한 외부 참조번호입니다. Adyen PSP 참조번호와는 별개입니다. '결제 대사 지연 분석'에 중요한 필드입니다. 외부 원장에 있는 은행 거래 내역과 Adyen 레코드를 대조할 때 기준으로 사용됩니다. 중요한 이유 3자 대사와 외부 데이터 대조에 필요합니다. 확보 방법 Adyen Payment Response의 'additionalData.acquirerReference'입니다. 예시 1234567890987654321
	사기 위험 점수 RiskScore	사기 탐지 엔진이 거래에 부여한 위험 점수입니다.
설명 Adyen의 RevenueProtect 엔진은 사기 가능성을 나타내는 숫자 점수(0~100)를 부여합니다. 점수가 높으면 수동 검토를 요청하거나 거래를 자동으로 차단하는 경우가 많습니다. 이 속성은 '재무 규정 준수 위험 개요' 분석에 활용됩니다. 높은 위험 점수와 차지백의 연관성을 분석하면 사기 방지 규칙을 조정할 수 있습니다. 위험 점수가 높아도 결제가 성공한 경우에는 위험 모델의 오탐일 가능성을 살펴볼 수 있습니다. 중요한 이유 사기 방지 로직의 효과를 분석하는 데 필요합니다. 확보 방법 Adyen Risk API 응답 또는 Reporting의 'fraudResult.accountScore'입니다. 예시 025100
	승인 코드 AuthorisationCode	승인 시 카드 발급사가 반환하는 승인 코드입니다.
설명 구매자의 카드에 자금이 예약되었음을 나타내는 코드입니다. 승인이 성공했다는 증거입니다. 주로 감사와 추적에 사용되며, '결제 승인' 활동이 유효했는지 확인합니다. 중요한 이유 감사 추적에 필요한 승인 성공 증빙입니다. 확보 방법 Adyen Payment Response의 'authCode'입니다. 예시 123456098712
	정산 배치 번호 BatchNumber	자금 정산에 연결된 배치 번호입니다.
설명 Adyen은 지급을 위해 정산된 결제를 배치로 묶습니다. 이 속성은 특정 거래가 어느 배치에 속하는지 나타냅니다. 분석에서는 지급 주기별로 결제를 그룹화하는 데 사용합니다. 특정 배치의 지연 여부를 감사하고 '결제 정산 완료' 활동을 추적하는 데 도움이 됩니다. 중요한 이유 개별 거래를 일괄 정산 내역과 연결합니다. 확보 방법 Adyen Settlement Detail Report의 'Batch Number'입니다. 예시 100255
	통화 PaymentCurrency	거래 통화를 나타내는 세 글자의 ISO 코드입니다.
설명 이 속성은 `PaymentAmount`의 통화를 지정합니다. 일반적인 값으로 EUR, USD, GBP 등이 있습니다. 분석에서는 시장별 거래를 그룹화하는 데 사용합니다. 여러 지역의 데이터를 집계할 때 금액을 동일한 기준으로 환산하는 데도 필요합니다. 중요한 이유 다중 통화 보고에서 금액 필드의 통화 기준을 나타냅니다. 확보 방법 Adyen Payment Request의 'amount.currency'입니다. 예시 EURUSDGBP

필수 권장 선택 사항

결제 처리 활동

Adyen 결제 흐름을 정확히 파악하려면 이벤트 로그에 기록해야 하는 주요 프로세스 단계와 이정표입니다.

5 권장 11 선택 사항

	활동	설명
	결제 거절	카드 발급사 또는 Adyen의 위험 규칙에 따라 거래가 거절된 상태입니다. 실패 상태를 포함한 승인 웹훅을 통해 기록합니다.
중요한 이유 'Payment Transaction Failure Rate' KPI에 직접 영향을 줍니다. 거절 사유를 분석하면 승인율을 높이는 데 도움이 됩니다. 확보 방법 Adyen Notification Webhook: eventCode 'AUTHORISATION', success='false'. 기록 AUTHORISATION 웹훅 실패 시 기록 이벤트 유형 explicit
	결제 매입	구매자에게서 판매자에게 자금을 이체하는 요청이 성공적으로 처리된 상태입니다. 즉시 처리되는 자동 매입 방식일 수도 있고, 나중에 처리되는 수동 매입 방식일 수도 있습니다.
중요한 이유 매출 인식을 확인하는 단계입니다. 승인부터 매입까지 걸리는 시간은 'Payment Authorization Lead Time' KPI를 계산하는 데 중요합니다. 확보 방법 Adyen Notification Webhook: eventCode 'CAPTURE', success='true'. 기록 CAPTURE 웹훅 성공 시 기록 이벤트 유형 explicit
	결제 승인	카드 발급사 또는 결제 수단이 거래를 승인하고 자금을 예약한 상태입니다. Adyen 표준 알림 웹훅을 통해 기록합니다.
중요한 이유 거래가 유효하고 자금을 사용할 수 있음을 나타내는 주요 단계입니다. 매입 처리의 선행 조건입니다. 확보 방법 Adyen Notification Webhook: eventCode 'AUTHORISATION', success='true'. 기록 AUTHORISATION 웹훅 성공 시 기록 이벤트 유형 explicit
	결제 요청 접수	Adyen 결제 플랫폼이 거래 요청을 처음 접수하는 단계입니다. 최초 API 요청의 타임스탬프 또는 pspReference 생성 시점을 기준으로 기록합니다.
중요한 이유 프로세스 인스턴스의 시작 시점을 나타냅니다. 전체 처리 주기를 계산하는 데 필요합니다. 확보 방법 Adyen Payment Response 로그 또는 pspReference 생성 시점의 타임스탬프입니다. 기록 API를 통해 pspReference가 생성될 때 기록 이벤트 유형 explicit
	결제 정산 완료	자금 청산이 완료되어 판매자의 Adyen 계정에 입금된 상태입니다. Settlement Detail Report에서 확인할 수 있습니다.
중요한 이유 성공적인 프로세스의 재무상 최종 단계입니다. 'Overall Payment Cycle Time' 및 'Payment Reconciliation Delay Analysis'에 필요합니다. 확보 방법 Adyen Settlement Detail Report(SDR)의 레코드 유형 'Settled'. 기록 거래가 Settlement Report에 표시될 때 기록 이벤트 유형 explicit
	결제 정산 요청	Adyen이 금융 처리를 위해 거래를 매입 은행이나 네트워크로 전달한 상태입니다. 상태가 SentForSettlement로 변경됩니다.
중요한 이유 운영 처리가 금융 청산 단계로 넘어가는 시점입니다. 이 단계의 지연은 현금 흐름에 영향을 줍니다. 확보 방법 Adyen Transaction Status API 또는 상태 변경 이력 로그를 통해 확인합니다. 기록 상태 필드가 SentForSettlement로 변경되는지 확인 이벤트 유형 inferred
	결제 취소	자금이 매입되기 전에 승인이 취소된 상태입니다. 구매자의 카드에 예약된 자금이 해제됩니다.
중요한 이유 유효한 주문이 완료 전에 종료되는 프로세스의 반복 경로를 나타냅니다. 고객 요청이나 재고 확인 시간 초과로 발생하는 경우가 많습니다. 확보 방법 Adyen Notification Webhook: eventCode 'CANCELLATION'. 기록 CANCELLATION 웹훅 수신 시 기록 이벤트 유형 explicit
	기술 오류 기록	웹훅 실패나 API 시간 초과와 같은 시스템 오류가 처리 중 발생한 상태입니다. 인터페이스의 특정 오류 코드로 확인합니다.
중요한 이유 기술적 실패와 재무상 실패를 구분해 'Payment Transaction Failure Rate' 분석에 직접 활용합니다. 확보 방법 Adyen Interface 로그 또는 API 호출의 특정 실패 응답입니다. 기록 오류 응답 코드 5xx 또는 4xx가 반환될 때 기록 이벤트 유형 explicit
	매입 실패	승인된 자금을 매입하려는 시도가 실패한 상태입니다. 기술적 시간 초과나 승인 후 매입 전 카드 상태 변경이 원인일 수 있습니다.
중요한 이유 재작업이나 재시도가 필요한 주요 오류 지점입니다. 'Payment Exception Rate'에 반영됩니다. 확보 방법 Adyen Notification Webhook: eventCode 'CAPTURE_FAILED'. 기록 CAPTURE_FAILED 웹훅 수신 시 기록 이벤트 유형 explicit
	위험 심사 수행	Adyen의 RevenueProtect 엔진이 거래에서 사기 징후를 분석합니다. 승인 응답에 사기 점수나 위험 결과가 있으면 이 활동이 수행된 것으로 판단합니다.
중요한 이유 위험 점수가 높으면 수동 검토나 자동 거절이 발생해 병목 또는 프로세스 종료로 이어질 수 있습니다. 확보 방법 Adyen Payment Response의 fraudResult 필드 또는 Case Management 로그입니다. 기록 fraudResult 객체가 있는 경우 수행된 것으로 판단 이벤트 유형 inferred
	지급 확인	정산된 거래 묶음에 해당하는 자금이 판매자의 은행 계좌로 지급된 상태입니다.
중요한 이유 사업체로 실제 현금이 이체된 것을 나타내며 'Payment Reconciliation Cycle Time'과 연관됩니다. 확보 방법 Adyen Notification Webhook: eventCode 'PAYOUT_THIRD_PARTY' 또는 Payout Report를 통해 확인합니다. 기록 Payout Report의 배치 ID를 Transaction ID와 연결 이벤트 유형 inferred
	차지백 알림 접수	Adyen이 카드 네트워크로부터 분쟁 알림을 받은 상태입니다. 분쟁 워크플로가 시작됩니다.
중요한 이유 규정 준수 및 위험을 나타내는 주요 지표입니다. 'Compliance Incident Rate'에 반영되며 즉시 수동 조치가 필요합니다. 확보 방법 Adyen Notification Webhook: eventCode 'CHARGEBACK' 또는 'NOTIFICATION_OF_CHARGEBACK'. 기록 CHARGEBACK 웹훅 수신 시 기록 이벤트 유형 explicit
	차지백 이의 제기	차지백에 이의를 제기하기 위해 Adyen에 증빙 자료를 제출한 상태입니다. 분쟁 흐름에서 재작업 또는 수동 활동에 해당합니다.
중요한 이유 매출 보호에 투입된 노력을 추적합니다. 'Payment Rework Rate'를 계산하는 데 중요합니다. 확보 방법 증빙 자료 제출 내역이 표시된 Adyen Disputes API 또는 Case Management 로그입니다. 기록 상태가 'Defense Supplied'로 변경된 경우 수행된 것으로 판단 이벤트 유형 inferred
	차지백 취소	분쟁에서 승소해 자금이 판매자에게 반환된 상태입니다. 예외가 성공적으로 해결된 사례입니다.
중요한 이유 위험 관리에 긍정적인 결과입니다. 최초 차지백으로 발생한 재무 영향을 상쇄합니다. 확보 방법 Adyen Notification Webhook: eventCode 'CHARGEBACK_REVERSED'. 기록 CHARGEBACK_REVERSED 웹훅 수신 시 기록 이벤트 유형 explicit
	환불 시작	구매자에게 자금을 반환하는 요청이 시작된 상태입니다. 역방향 프로세스 흐름이 시작됩니다.
중요한 이유 정산 후 발생한 예외를 나타냅니다. 환불률이 높으면 앞선 단계의 품질 문제를 의미할 수 있습니다. 확보 방법 Adyen Notification Webhook: eventCode 'REFUND'. 기록 REFUND 웹훅이 발생할 때 기록 이벤트 유형 explicit
	환불 정산 완료	환불이 재무 처리되어 판매자 계정에서 차감된 상태입니다. Settlement Detail Report에서 확인합니다.
중요한 이유 환불 프로세스를 마무리하는 단계입니다. 오류로 인한 환불이라면 'Average Error Resolution Time'을 계산하는 데 중요합니다. 확보 방법 Adyen Settlement Detail Report의 레코드 유형 'Refunded' 또는 'RefundedReversed'. 기록 환불이 Settlement Report에 표시될 때 기록 이벤트 유형 explicit

권장 선택 사항

데이터 추출 안내

Adyen에서 데이터 가져오기

단계

Merchant Report 역할이 있는 사용자 계정으로 Adyen Customer Area에 로그인합니다.
Reports로 이동한 다음 메뉴에서 Settlement details를 선택합니다.
Automatic generation 설정을 찾거나, 한 번만 내보내려면 Generate report를 선택합니다.
설정 패널에서 Format이 CSV(쉼표로 구분된 값)로 지정되어 있는지 확인합니다.
Include columns에서 All을 선택하거나 다음 항목을 직접 선택합니다: Company Account, Merchant Account, Psp Reference, Merchant Reference, Payment Method, Creation Date, TimeZone, Type, Modification Reference, Gross Currency, Gross Debit, Gross Credit, Exchange Rate, Net Currency, Net Debit, Net Credit, Commission, Markup, Scheme Fees, Interchange.
중요: 전체 재무 흐름을 파악할 수 있도록 보고서 범위에 모든 Journal Types(Settled, Refunded, Chargeback, PaidOut 등)가 포함되어 있는지 확인합니다.
원하는 기간(예: 최근 90일)을 지정해 보고서를 생성합니다. 정산 보고서는 거래일이 아니라 정산 배치 날짜를 기준으로 생성됩니다.
생성된 CSV 파일을 로컬 데이터 추출 환경에 다운로드합니다.
아래에 제공된 변환 스크립트를 실행해 열 중심의 'Wide' CSV 원장을 ProcessMind에 필요한 행 중심의 'Long' 이벤트 로그 형식으로 변환합니다.
스크립트는 Creation Date를 피벗 해제해 'Payment Request Received' 이벤트를 만들고, Type 열을 특정 재무 활동에 매핑합니다.
출력 CSV에 다음 헤더가 있는지 확인합니다: PspReference, EventCode, EventDate, SourceSystem.
변환된 CSV 파일을 ProcessMind에 업로드합니다.

구성

보고서 유형: Settlement Detail Report(금융 원장)
파일 형식: CSV(표준 쉼표 구분)
세분성: 거래 단위(금융 분개 항목당 한 행)
시간대: UTC(다른 시스템과 추출 데이터를 맞추려면 권장)
날짜 범위: 거래 생성일이 아니라 정산 배치(Batch Closed Date)를 기준으로 합니다. 증분 추출 시 날짜 범위가 겹치도록 설정합니다.
필수 열: Psp Reference(키), 유형(활동), Creation Date, Booking Date(이벤트 타임스탬프), Merchant Account.
필터 설정: 프로세스 전체를 포함하도록 'Chargeback' 또는 'Refund' 유형을 제외하는 필터가 없는지 확인합니다.

샘플 쿼리 python

import pandas as pd
from datetime import datetime

class=class="hl-string">"hl-comment"># CONFIGURATION
INPUT_FILE = class="hl-string">'settlement_detail_report.csv'
OUTPUT_FILE = class="hl-string">'adyen_event_log.csv'
SOURCE_SYSTEM = class="hl-string">'Adyen'

class=class="hl-string">"hl-comment"># Load the Adyen Settlement Detail Report
class=class="hl-string">"hl-comment"># Skip standard Adyen header rows if present (often reports start on row 1 or have metadata on top)
df = pd.read_csv(INPUT_FILE, keep_default_na=False)

class=class="hl-string">"hl-comment"># Define the output list
event_log = []

class=class="hl-string">"hl-comment"># Helper function to append events
def add_event(psp_ref, activity, timestamp, attributes):
    if not timestamp or str(timestamp).strip() == class="hl-string">'':
        return
    base_event = {
        class="hl-string">'PspReference': psp_ref,
        class="hl-string">'EventCode': activity,
        class="hl-string">'EventDate': timestamp,
        class="hl-string">'SourceSystem': SOURCE_SYSTEM,
        class="hl-string">'LastDataUpdate': datetime.utcnow().isoformat(),
        class="hl-string">'MerchantAccount': attributes.get(class="hl-string">'Merchant Account', class="hl-string">''),
        class="hl-string">'PaymentMethod': attributes.get(class="hl-string">'Payment Method', class="hl-string">''),
        class="hl-string">'PaymentAmount': attributes.get(class="hl-string">'Gross Credit', 0) if attributes.get(class="hl-string">'Gross Credit') else attributes.get(class="hl-string">'Gross Debit', 0) * -1
    }
    class=class="hl-string">"hl-comment"># Merge optional attributes
    base_event.update(attributes)
    event_log.append(base_event)

class=class="hl-string">"hl-comment"># Iterate through the ledger rows
for index, row in df.iterrows():
    psp_ref = row.get(class="hl-string">'Psp Reference')
    journal_type = row.get(class="hl-string">'Type')
    creation_date = row.get(class="hl-string">'Creation Date') class=class="hl-string">"hl-comment"># Used for Auth/Request
    booking_date = row.get(class="hl-string">'Booking Date')   class=class="hl-string">"hl-comment"># Used for Settlement/Financials
    
    class=class="hl-string">"hl-comment"># Common attributes for this row
    row_attrs = {
        class="hl-string">'MerchantAccount': row.get(class="hl-string">'Merchant Account'),
        class="hl-string">'PaymentMethod': row.get(class="hl-string">'Payment Method'),
        class="hl-string">'RefusalReason': row.get(class="hl-string">'Refusal Reason', class="hl-string">''),
        class="hl-string">'PaymentStatus': journal_type
    }

    class=class="hl-string">"hl-comment"># --- 1. DERIVED UPSTREAM ACTIVITIES ---
    class=class="hl-string">"hl-comment"># Since this is a settlement report, we infer the Request/Auth from the Creation Date
    class=class="hl-string">"hl-comment"># of the first record we see for this PSP Reference. 
    class=class="hl-string">"hl-comment"># Logic: If Creation Date exists, implies Request and Auth occurred.
    
    if creation_date:
        class=class="hl-string">"hl-comment"># Activity: Payment Request Received
        add_event(psp_ref, class="hl-string">'Payment Request Received', creation_date, row_attrs)
        
        class=class="hl-string">"hl-comment"># Activity: Risk Screening Performed (Inferred from existence of transaction)
        class=class="hl-string">"hl-comment"># Note: True risk score requires class="hl-string">'Payments Accounting Report', inferred here for process continuity
        add_event(psp_ref, class="hl-string">'Risk Screening Performed', creation_date, row_attrs)
        
        class=class="hl-string">"hl-comment"># Activity: Payment Authorised
        class=class="hl-string">"hl-comment"># Typically happens immediately after request for successful settled items
        add_event(psp_ref, class="hl-string">'Payment Authorised', creation_date, row_attrs)

    class=class="hl-string">"hl-comment"># --- 2. MAPPED FINANCIAL ACTIVITIES ---
    class=class="hl-string">"hl-comment"># Map Adyen Ledger Types to Process Activities using Booking Date
    
    if journal_type == class="hl-string">'Settled':
        add_event(psp_ref, class="hl-string">'Payment Settled', booking_date, row_attrs)
        
        class=class="hl-string">"hl-comment"># Activity: Payment Sent for Settlement
        class=class="hl-string">"hl-comment"># Inferred: Occurs shortly before settlement. 
        class=class="hl-string">"hl-comment"># Using Creation Date if Booking Date is distinct, or defaulting to Booking Date.
        sent_date = creation_date if creation_date else booking_date
        add_event(psp_ref, class="hl-string">'Payment Sent for Settlement', sent_date, row_attrs)

    elif journal_type == class="hl-string">'Refunded':
        add_event(psp_ref, class="hl-string">'Refund Initiated', creation_date, row_attrs)
        add_event(psp_ref, class="hl-string">'Refund Settled', booking_date, row_attrs)

    elif journal_type == class="hl-string">'Chargeback':
        add_event(psp_ref, class="hl-string">'Chargeback Notification Received', booking_date, row_attrs)

    elif journal_type == class="hl-string">'ChargebackRetried':
        add_event(psp_ref, class="hl-string">'Chargeback Defended', booking_date, {class="hl-string">'IsRework': class="hl-string">'True'})

    elif journal_type == class="hl-string">'ChargebackReversed':
        add_event(psp_ref, class="hl-string">'Chargeback Reversed', booking_date, row_attrs)

    elif journal_type == class="hl-string">'PaidOut':
        class=class="hl-string">"hl-comment"># Payouts often group many transactions. 
        class=class="hl-string">"hl-comment"># If the report is at transaction level, this row represents the batch payout.
        add_event(psp_ref, class="hl-string">'Payout Confirmed', booking_date, row_attrs)

    elif journal_type == class="hl-string">'CaptureFailed':
        add_event(psp_ref, class="hl-string">'Capture Failed', booking_date, {class="hl-string">'IsRework': class="hl-string">'True'})

    class=class="hl-string">"hl-comment"># --- 3. EXCEPTION HANDLING ---
    class=class="hl-string">"hl-comment"># These statuses often appear in class="hl-string">'Received payment details' reports but rarely in Settlement
    class=class="hl-string">"hl-comment"># unless fees were applied.
    
    elif journal_type == class="hl-string">'Refused': 
        add_event(psp_ref, class="hl-string">'Payment Refused', creation_date, row_attrs)
        
    elif journal_type == class="hl-string">'Cancelled':
        add_event(psp_ref, class="hl-string">'Payment Cancelled', creation_date, row_attrs)

    elif journal_type == class="hl-string">'Error':
        add_event(psp_ref, class="hl-string">'Technical Error Logged', booking_date, {class="hl-string">'IsRework': class="hl-string">'True'})

class=class="hl-string">"hl-comment"># Convert to DataFrame
events_df = pd.DataFrame(event_log)

class=class="hl-string">"hl-comment"># Deduping: Adyen reports may have multiple lines for partial settlements.
class=class="hl-string">"hl-comment"># We sort by date and keep unique Activity per PSP Reference if timestamps match exactly.
events_df.drop_duplicates(subset=[class="hl-string">'PspReference', class="hl-string">'EventCode', class="hl-string">'EventDate'], inplace=True)

class=class="hl-string">"hl-comment"># Output
events_df.to_csv(OUTPUT_FILE, index=False)
print(fclass="hl-string">'Successfully extracted {len(events_df)} events to {OUTPUT_FILE}')

단계

사전 환경 설정: Merchant Report 역할이 활성화된 Adyen Report 사용자를 준비합니다. Customer Area의 Developers > API Credentials에서 API Key를 발급받습니다.
필요한 보고서 확인: 이 추출 방식은 Adyen에서 생성하는 두 가지 주요 CSV 보고서를 사용합니다. 정산, 차지백, 환불과 같은 금융 이벤트에는 Settlement Detail Report를, 요청, 거절, 승인과 같은 운영 이벤트에는 Received Payment Detail Report를 사용합니다.
Python 환경 설정: pip를 사용해 pandas, requests, numpy 라이브러리를 설치합니다. API 통신과 데이터 변환에 사용합니다.
API 연결 구현: 아래에 제공된 Python 스크립트에서 https://management-test.adyen.com 또는 https://management-live.adyen.com 엔드포인트에 인증하도록 설정합니다. Report API를 사용해 지정한 날짜 범위의 보고서를 조회하고 다운로드 URL을 가져옵니다.
데이터 수집: 스크립트가 원본 CSV 데이터를 pandas DataFrame으로 읽어옵니다. Adyen 보고서는 일반적으로 거래당 한 행에 여러 상태 열이 있는 'Wide' 형식이므로 변환이 필요합니다.
운영 활동 매핑: Received Payment Detail Report를 처리합니다. CreationDate를 결제 요청 접수에 매핑합니다. 상태 열(예: Authorised, Refused, Error)을 확인해 결제 승인, 결제 거절, 기술 오류 기록 이벤트를 생성합니다.
금융 활동 매핑: Settlement Detail Report를 처리합니다. 이 보고서에는 JournalType 열이 있습니다. Settled는 결제 정산, Refunded는 환불 시작, Chargeback은 차지백 통지 접수에 매핑합니다.
복합 활동 추론:
- 위험 심사 수행: FraudScore 열에 값이 있고 -1보다 큰지 확인합니다.
- 지급 확인: BatchNumber를 사용해 거래를 정산 보고서의 지급 항목과 연결합니다.
- 차지백 이의 제기: SecondChargeback 또는 Defense 분개 유형을 확인합니다.
데이터 변환: pandas에서 'melt' 또는 'stack' 작업을 적용해 Wide 데이터 세트를 Long 형식의 이벤트 로그로 변환합니다. 각 활동은 별도의 행으로 구성합니다.
속성 표준화: 열 이름을 대상 스키마에 맞게 변경합니다: PspReference, EventCode, EventDate, SourceSystem('Adyen'으로 고정), PaymentAmount. 날짜는 ISO 8601 형식으로 파싱합니다.
필터링: 유형 필터를 사용해 프로세스 단계가 아닌 내부 대사 행(예: 헤더 행 또는 잔액 이월)을 제외합니다.
최종 내보내기: 처리된 DataFrame을 adyen_event_log.csv라는 CSV 파일로 내보냅니다. 이 파일을 ProcessMind에 업로드할 수 있습니다.

구성

API 환경: 배포 단계에 따라 Adyen Test(management-test.adyen.com)와 Live(management-live.adyen.com) 엔드포인트를 선택합니다.
인증: 헤더에 x-api-key를 사용합니다. Management API에는 Basic Auth를 사용하지 않습니다.
보고서 유형:
- settlement_detail_report: 재무 흐름 이벤트를 분석하는 데 필요합니다.
- received_payment_detail_report: 최초 요청 및 승인 로직을 분석하는 데 필요합니다.
날짜 범위: Adyen 보고서는 배치 마감일을 기준으로 생성됩니다. 지연 정산을 포함하려면 관심 있는 CreationDate에 이후 7일을 더한 기간까지 보고서를 요청하도록 스크립트를 설정합니다.
Merchant Account 범위: Merchant Account가 여러 개라면 계정 목록을 순회하거나, 사용 가능한 경우 Company Account 수준의 보고서를 사용합니다.
Pandas 설정: 거래량이 100k행을 초과하는 CSV를 읽을 때 유형 추론 오류를 방지하려면 low_memory=False를 설정합니다.

샘플 쿼리 python

import pandas as pd
import requests
import io
import numpy as np
from datetime import datetime

class=class="hl-string">"hl-comment"># Configuration
API_KEY = class="hl-string">'YOUR_ADYEN_API_KEY'
MERCHANT_ACCOUNT = class="hl-string">'YOUR_MERCHANT_ACCOUNT'
BASE_URL = class="hl-string">'https://management-live.adyen.com/v1'
HEADERS = {class="hl-string">'x-api-key': API_KEY, class="hl-string">'Content-Type': class="hl-string">'application/json'}

class=class="hl-string">"hl-comment"># Placeholder for fetching report URLs via API
class=class="hl-string">"hl-comment"># In production, use GET /companies/{companyId}/reports or /merchants/{merchantId}/reports
class=class="hl-string">"hl-comment"># For this script, we assume the CSV content is loaded into DataFrames

def transform_adyen_data(received_payments_csv_path, settlement_details_csv_path):
    
    class=class="hl-string">"hl-comment"># 1. Load Data
    print(class="hl-string">'Loading reports...')
    df_received = pd.read_csv(received_payments_csv_path)
    df_settled = pd.read_csv(settlement_details_csv_path)

    events = []

    class=class="hl-string">"hl-comment"># 2. Process Received Payment Detail Report (Operational Events)
    class=class="hl-string">"hl-comment"># This report covers: Request, Auth, Refusal, Risk, Capture, Errors
    
    for _, row in df_received.iterrows():
        psp = str(row.get(class="hl-string">'PspReference', class="hl-string">''))
        created_date = pd.to_datetime(row.get(class="hl-string">'CreationDate'))
        amount = row.get(class="hl-string">'Amount', 0)
        status = row.get(class="hl-string">'Status', class="hl-string">'')
        fraud_score = row.get(class="hl-string">'FraudScore', None)
        refusal_reason = row.get(class="hl-string">'RefusalReason', class="hl-string">'')
        
        class=class="hl-string">"hl-comment"># Activity: Payment Request Received
        events.append({
            class="hl-string">'PspReference': psp,
            class="hl-string">'EventCode': class="hl-string">'Payment Request Received',
            class="hl-string">'EventDate': created_date,
            class="hl-string">'PaymentAmount': amount,
            class="hl-string">'PaymentMethod': row.get(class="hl-string">'PaymentMethod', class="hl-string">''),
            class="hl-string">'RefusalReason': None,
            class="hl-string">'SourceSystem': class="hl-string">'Adyen'
        })

        class=class="hl-string">"hl-comment"># Activity: Risk Screening Performed
        class=class="hl-string">"hl-comment"># Inferred if a fraud score was calculated
        if pd.notna(fraud_score):
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Risk Screening Performed',
                class="hl-string">'EventDate': created_date + pd.Timedelta(seconds=1), class=class="hl-string">"hl-comment"># Slight offset
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })

        class=class="hl-string">"hl-comment"># Activity: Payment Authorised / Refused / Error
        if status == class="hl-string">'Authorised':
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Payment Authorised',
                class="hl-string">'EventDate': created_date + pd.Timedelta(seconds=2),
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })
        elif status == class="hl-string">'Refused':
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Payment Refused',
                class="hl-string">'EventDate': created_date + pd.Timedelta(seconds=2),
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'RefusalReason': refusal_reason,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })
        elif status == class="hl-string">'Error':
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Technical Error Logged',
                class="hl-string">'EventDate': created_date + pd.Timedelta(seconds=2),
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'RefusalReason': row.get(class="hl-string">'AcquirerResponse', class="hl-string">'Technical Error'),
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })
        elif status == class="hl-string">'Cancelled':
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Payment Cancelled',
                class="hl-string">'EventDate': created_date + pd.Timedelta(seconds=5),
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })

    class=class="hl-string">"hl-comment"># 3. Process Settlement Detail Report (Financial Events)
    class=class="hl-string">"hl-comment"># This report covers: Capture, Settlement, Refunds, Chargebacks, Payouts
    
    for _, row in df_settled.iterrows():
        psp = str(row.get(class="hl-string">'PspReference', class="hl-string">''))
        journal_type = row.get(class="hl-string">'JournalType', class="hl-string">'')
        process_date = pd.to_datetime(row.get(class="hl-string">'CreationDate')) class=class="hl-string">"hl-comment"># Or ProcessingDate
        amount = row.get(class="hl-string">'NetCredit', 0) if pd.notna(row.get(class="hl-string">'NetCredit')) else row.get(class="hl-string">'GrossCredit', 0)
        
        class=class="hl-string">"hl-comment"># Map JournalType to Activities
        activity_name = None
        
        if journal_type == class="hl-string">'SentForSettlement':
            activity_name = class="hl-string">'Payment Sent for Settlement'
        elif journal_type == class="hl-string">'Settled':
            activity_name = class="hl-string">'Payment Settled'
        elif journal_type == class="hl-string">'SentForRefund' or journal_type == class="hl-string">'Refunded':
            activity_name = class="hl-string">'Refund Initiated'
        elif journal_type == class="hl-string">'SettledRefund':
            activity_name = class="hl-string">'Refund Settled'
        elif journal_type == class="hl-string">'Chargeback':
            activity_name = class="hl-string">'Chargeback Notification Received'
        elif journal_type == class="hl-string">'SecondChargeback' or journal_type == class="hl-string">'Defense':
            activity_name = class="hl-string">'Chargeback Defended'
        elif journal_type == class="hl-string">'ChargebackReversed':
            activity_name = class="hl-string">'Chargeback Reversed'
        elif journal_type == class="hl-string">'CaptureFailed':
            activity_name = class="hl-string">'Capture Failed'
        elif journal_type == class="hl-string">'PaidOut':
            class=class="hl-string">"hl-comment"># PaidOut is usually batch level, if psp is present, map it
            activity_name = class="hl-string">'Payout Confirmed'
        
        class=class="hl-string">"hl-comment"># Logic for class="hl-string">'Payment Captured' 
        class=class="hl-string">"hl-comment"># Adyen often auto-captures. If we see Settled, we assume Captured occurred prior if not explicitly logged.
        class=class="hl-string">"hl-comment"># Here we rely on class="hl-string">'SentForSettlement' as the trigger for Capture success in many flows.
        if journal_type == class="hl-string">'SentForSettlement':
             events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': class="hl-string">'Payment Captured',
                class="hl-string">'EventDate': process_date - pd.Timedelta(seconds=1),
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen'
            })

        if activity_name:
            events.append({
                class="hl-string">'PspReference': psp,
                class="hl-string">'EventCode': activity_name,
                class="hl-string">'EventDate': process_date,
                class="hl-string">'PaymentAmount': amount,
                class="hl-string">'SourceSystem': class="hl-string">'Adyen',
                class="hl-string">'MerchantAccount': row.get(class="hl-string">'MerchantAccount', MERCHANT_ACCOUNT),
                class="hl-string">'PaymentMethod': row.get(class="hl-string">'PaymentMethod', class="hl-string">'')
            })

    class=class="hl-string">"hl-comment"># 4. Create DataFrame
    df_events = pd.DataFrame(events)
    
    class=class="hl-string">"hl-comment"># 5. Post-Processing & Cleanup
    if not df_events.empty:
        class=class="hl-string">"hl-comment"># Ensure standard columns
        df_events[class="hl-string">'LastDataUpdate'] = datetime.now().isoformat()
        df_events[class="hl-string">'TotalCycleTime'] = None class=class="hl-string">"hl-comment"># Calculated in ProcessMind
        df_events[class="hl-string">'IsRework'] = df_events[class="hl-string">'EventCode'].apply(lambda x: 1 if class="hl-string">'Chargeback' in x or class="hl-string">'Refused' in x else 0)
        df_events[class="hl-string">'PaymentStatus'] = df_events.sort_values(class="hl-string">'EventDate').groupby(class="hl-string">'PspReference')[class="hl-string">'EventCode'].transform(class="hl-string">'last')
        
        class=class="hl-string">"hl-comment"># Filter invalid rows (empty PspReference)
        df_events = df_events[df_events[class="hl-string">'PspReference'] != class="hl-string">'nan']
        df_events = df_events[df_events[class="hl-string">'PspReference'] != class="hl-string">'']

        class=class="hl-string">"hl-comment"># Sort
        df_events = df_events.sort_values([class="hl-string">'PspReference', class="hl-string">'EventDate'])
        
    return df_events

class=class="hl-string">"hl-comment"># Execution Entry Point
class=class="hl-string">"hl-comment"># Replace paths with actual file locations or API download streams
if __name__ == class="hl-string">'__main__':
    class=class="hl-string">"hl-comment"># Example usage
    df_log = transform_adyen_data(class="hl-string">'received_payment_detail_report.csv', class="hl-string">'settlement_detail_report.csv')
    
    class=class="hl-string">"hl-comment"># Export
    df_log.to_csv(class="hl-string">'ProcessMind_Adyen_Log.csv', index=False, date_format=class="hl-string">'%Y-%m-%d %H:%M:%S')
    print(fclass="hl-string">'Extraction Complete. Generated {len(df_log)} events.')

시작할 준비가 되셨나요?

이 템플릿으로 데이터 수집을 간소화하고 Adyen 결제 처리 최적화를 시작하세요. 재무 운영의 효율을 높이고 더 깊이 있는 인사이트를 얻을 수 있습니다.

개선 가이드로 돌아가기

템플릿 다운로드

지금 Adyen 결제 처리를 원활하게 개선하세요.

결제 예외를 없애고 98%의 자동 처리율을 달성하세요.

무료 체험 시작하기

신용카드가 필요하지 않습니다. 지금 바로 최적화를 시작하세요.

결제 처리 데이터 템플릿

결제 처리 데이터 템플릿

결제 처리 속성

결제 처리 활동

데이터 추출 안내

Adyen 정산 상세 보고서 내보내기

단계

구성

샘플 쿼리 python

Reporting API를 통한 Python 추출

단계

구성

샘플 쿼리 python

시작할 준비가 되셨나요?

지금 Adyen 결제 처리를 원활하게 개선하세요.