정산/대사 파일 연동 규격서
센트비와 고객사간의 정산/대사 파일 연동 Spec 에 대해 설명합니다.
정산/대사 파일 연동 규격서
1. 정산 대사 기본 정책 (General Policy)
- 정산 기준 시간 (Cut-off Time): 한국 표준시(KST) 기준 전일자
00:00:00 ~ 23:59:59내에 상태가 완료된 결제 및 환불 거래. - 파일 생성 및 제공 시점: 매일 새벽
02:00 (KST)에 전일자 정산 파일이 생성되어 지정된 SFTP 서버로 업로드됩니다. - 파일 포맷:
UTF-8인코딩이 적용된CSV(Comma-Separated Values) 파일. - 통신 방식: 센트비에서 제공하는 s3 Pre-Signed URL 을 사용하여 정산 파일을 다운로드
- s3 파일 다운로드를 위한 임시 url 요청 및 획득
- 호출 방향 : 고객사 → 센트비즈 API 서버
- 프라이빗 s3 파일에 접근할수 있는 임시 url 제공 (5분후 만료)
- 위에서 취득한 url 로 해당 일자 정산 파일 다운로드
- 호출 방향 : 고객사 → 센트비즈 s3 서버
- s3 파일 다운로드를 위한 임시 url 요청 및 획득
2. 파일 명명 규칙 (File Naming Convention)
파일은 요약(마스터) 파일과 상세 파일 2종으로 분리하여 제공됩니다.
파일명에는 다음 정보가 포함됩니다.
CHANNEL_NO: 고객사 채널 넘버 (별도 제공)CURRENCY_CODE: 정산 통화REVERSION: 정산 데이터 추출 회차 (정산 데이터를 여러번 추출할 경우를 대비한 버전 관리)
아래는 파일명 형식 및 예시입니다.- 요약(Summary) 파일:
SETTLEMENT_SUMMARY_[CHANNEL_NO]_[CURRENCY_CODE]_YYYYMMDD_[REVERSION].csv- (예: SETTLEMENT_SUMMARY_CH240529000516_KRW_20260324_1.csv)
- 상세(Detail) 파일:
SETTLEMENT_DETAIL_[CHANNEL_NO]_[CURRENCY_CODE]_YYYYMMDD_[REVERSION].csv- (예: SETTLEMENT_DETAIL_CH240529000516_KRW_20260324_1.csv)
3. 데이터 레이아웃 (Data Layout)
3-1. 요약(Summary) 파일 규격
해당일 기준 고객사에게 정산될(고객사 은행 계좌로 실제 송금될) 총액(Summary) 정보입니다.
| No | 항목명 (Header) | 데이터 타입 | 필수 | 설명 | 비고 (예시) |
|---|---|---|---|---|---|
| 1 | target_date | String | Y | 거래 완료 일자 (KST) | 2026-03-24 |
| 2 | expected_paid_date | String | Y | 지급(입금) 예정일 (계약 정책에 따름) | 2026-03-27 |
| 3 | total_count | Number | Y | 전체 거래 건수 (결제+환불) | 7 |
| 4 | total_payment_amount | Number | Y | 총 결제 금액 | 50000000.00 |
| 5 | total_payment_currency | String | Y | 총 결제 금액 통화 | KRW |
| 6 | total_refund_amount | Number | Y | 총 환불 금액 | 2000000.00 |
| 7 | total_refund_currency | String | Y | 총 환불 금액 통화 | KRW |
| 8 | total_fee_amount | Number | Y | 총 수수료 금액 | 10000.00 |
| 9 | total_fee_currency | String | Y | 총 수수료 금액 통화 | KRW |
| 10 | total_settlement_amount | Number | Y | 최종 실지급액 | 47990000.00 |
| 11 | total_settlement_currency | String | Y | 최종 실지급액 통화 | KRW |
3-2. 상세(Detail) 파일 규격
Summary 에 대한 거래(결제/환불) 상세 내역입니다.
| No | 항목명 (Header) | 데이터 타입 | 필수 | 설명 | 비고 (예시) |
|---|---|---|---|---|---|
| 1 | id | String | Y | 정산 상세 명세 고유 식별자 (PK) | (임의 식별 String) |
| 2 | transaction_date | String | Y | 실제 거래 완료 일시 (KST) | 2026-03-24 14:30:15 |
| 3 | transaction_payment_id | String | 결제 거래 아이디 (transaction_type = PAYMENT 일때 필수) | PMT-20250929-74 | |
| 4 | transaction_refund_id | String | 환불 거래 아이디 (transaction_type = REFUND 일때 필수) | RFD-20250929-88 | |
| 5 | client_merchant_id | String | 고객사 상점아이디 | MERCHANT-001 | |
| 6 | client_order_id | String | Y | 고객사 주문 번호 | ORDER-20260324-001 |
| 7 | transaction_type | String | Y | 거래 유형(PAYMENT, REFUND) | PAYMENT 또는 REFUND |
| 8 | transaction_amount | Number | Y | 고객 원 거래 금액 (고객 원 거래 금액 통화) | 100000.00 |
| 9 | transaction_currency | String | Y | 고객 원 거래 금액 통화 | KRW |
| 10 | fee_amount | Number | Y | 센트비 부과 수수료액 (센트비 부과 수수료 통화) | 15.00 |
| 11 | fee_currency | String | Y | 센트비 부과 수수료 통화 | KRW |
| 12 | settlement_amount | Number | Y | 실제 고객사 정산 지급액 (고객사 정산 지급액 통화) | 100000.00 |
| 13 | settlement_currency | String | Y | 고객사 정산 지급액 통화 | KRW |
| 14 | fx_rate | Number | Y | 정산통화 - USD 환율 | 1500.00 |
4. 샘플 데이터 (CSV Example)
📄 SETTLEMENT_SUMMARY_CH240529000516_KRW_20260324_1.csv
target_date,expected_paid_date,total_count,total_payment_amount,total_payment_currency,total_refund_amount,total_refund_currency,total_fee_amount,total_fee_currency,total_settlement_amount,total_settlement_currency
2026-03-24,2026-03-27,7,548000.00,KRW,165000.00,KRW,0.00,KRW,383000.00,KRW📄 SETTLEMENT_DETAIL_CH240529000516_KRW_20260324_1.csv
id,transaction_date,transaction_payment_id,transaction_refund_id,client_merchant_id,client_order_id,transaction_type,transaction_amount,transaction_currency,fee_amount,fee_currency,settlement_amount,settlement_currency,fx_rate
uuid1,2026-03-24 09:12:33,PMT-20260324-0001,,MERCHANT-001,ORDER-LM-20260324-001,PAYMENT,85000.00,KRW,0.00,KRW,85000.00,KRW,1500.00
uuid2,2026-03-24 10:45:11,PMT-20260324-0002,,MERCHANT-001,ORDER-LM-20260324-002,PAYMENT,120000.00,KRW,0.00,KRW,120000.00,KRW,1500.00
uuid3,2026-03-24 11:30:55,PMT-20260324-0003,,MERCHANT-002,ORDER-LM-20260324-003,PAYMENT,45000.00,KRW,0.00,KRW,45000.00,KRW,1500.00
uuid4,2026-03-24 13:22:08,PMT-20260324-0004,,MERCHANT-001,ORDER-LM-20260324-004,PAYMENT,230000.00,KRW,0.00,KRW,230000.00,KRW,1500.00
uuid5,2026-03-24 15:08:47,PMT-20260324-0005,,MERCHANT-002,ORDER-LM-20260324-005,PAYMENT,68000.00,KRW,0.00,KRW,68000.00,KRW,1500.00
uuid6,2026-03-24 11:55:30,,RFD-20260324-0001,MERCHANT-001,ORDER-LM-20260324-002,REFUND,-120000.00,KRW,0.00,KRW,-120000.00,KRW,1500.00
uuid7,2026-03-24 14:10:19,,RFD-20260324-0002,MERCHANT-002,ORDER-LM-20260324-003,REFUND,-45000.00,KRW,0.00,KRW,-45000.00,KRW,1500.00Updated 3 months ago
Did this page help you?