samsung-wallet-cdata

🇰🇷 한국어 | 🇺🇸 English

> ⚠️ Unofficial - 이 패키지는 Samsung의 공식 라이브러리가 아닙니다.
> Samsung Wallet API 연동을 위한 커뮤니티 오픈소스 라이브러리입니다.

Samsung Wallet CDATA(JWT) 생성 라이브러리 for Node.js

Samsung Wallet API 연동을 위한 CDATA를 쉽게 생성할 수 있습니다.

왜 이 패키지가 필요한가?

Samsung은 공식적으로 Java 샘플 코드만 제공합니다:
- 공식 CDATA Generation Sample Code (Java)

Node.js 개발자를 위한 공식 라이브러리가 없어서 이 패키지를 만들었습니다.

Samsung 공식 Java 코드 cdata_generation_sample_code_v1.1.2를 Node.js로 포팅했습니다.

설치

``bash
npm install samsung-wallet-cdata
`

빠른 시작

`javascript
const { SamsungWallet } = require('samsung-wallet-cdata');
const fs = require('fs');

// 1. 인스턴스 생성 (설정 한번만)
const wallet = new SamsungWallet({
partnerId: 'YOUR_PARTNER_ID',
certificateId: 'YOUR_CERT_ID',
samsungCert: fs.readFileSync('samsung.crt', 'utf-8'),
partnerKey: fs.readFileSync('partner.key', 'utf-8'),
});

// 2. 티켓 CDATA 생성 (한 줄!)
const cdata = await wallet.createTicket({
title: '콘서트 입장권',
holderName: '홍길동',
startDate: new Date('2026-03-15T19:00:00'),
location: '올림픽 체조경기장',
barcode: 'TICKET-12345',
});

console.log('CDATA:', cdata);
`

카드 타입별 사용법

$3

콘서트, 전시회, 스포츠 경기 등의 입장권

`javascript
const cdata = await wallet.createTicket({
// 필수
title: '뮤지컬 캣츠',

// 선택 (추천)
holderName: '홍길동',
startDate: new Date('2026-03-15T19:00:00'),
endDate: new Date('2026-03-15T22:00:00'),
location: '블루스퀘어 신한카드홀',
barcode: 'TICKET-12345-ABCD',

// 브랜딩
providerName: 'TicketLink',
logoImage: 'https://example.com/logo.png',
mainImage: 'https://example.com/main.png',
bgColor: '#1428A0',

// 좌석 정보
seatClass: 'VIP석',
seatNumber: 'A열 15번',
});
`

$3

회원권, 포인트 카드, 멤버십 카드

`javascript
const cdata = await wallet.createMembership({
title: 'VIP 멤버십',
memberName: '홍길동',
memberId: 'M-2026-12345',
tier: 'Gold',
points: 15000,
expiryDate: new Date('2027-12-31'),
providerName: 'My Store',
bgColor: '#FFD700',
barcode: 'MEMBER-12345',
});
`

$3

할인 쿠폰, 기프트 카드

`javascript
const cdata = await wallet.createCoupon({
title: '20% 할인 쿠폰',
description: '전 품목 적용 가능',
discount: '20% OFF',
expiryDate: new Date('2026-12-31'),
providerName: 'My Store',
bgColor: '#FF6B35',
barcode: 'COUPON-2026-SAVE20',
terms: [
'다른 쿠폰과 중복 사용 불가',
'최소 주문금액 30,000원 이상',
],
});
`

$3

항공권, 버스/기차 티켓

`javascript
const cdata = await wallet.createBoardingPass({
title: 'KE123',
user: 'HONG/GILDONG',
vehicleNumber: 'KE123',
departCode: 'ICN',
arriveCode: 'NRT',
departName: '인천국제공항',
arriveName: '나리타국제공항',
estimatedOrActualStartDate: new Date('2026-03-15T10:30:00'),
departGate: 'A12',
seatNumber: '23A',
seatClass: 'Economy',
providerName: 'Korean Air',
barcodeValue: 'BCBP-DATA-HERE',
});
`

$3

상품권, 기프트 카드, 스토어 크레딧

`javascript
const cdata = await wallet.createGiftCard({
title: '커피숍 기프트카드',
providerName: '스타벅스',
cardNumber: 'GC-2026-12345',
pin: '1234',
balance: '50000',
balanceCurrency: 'KRW',
expiryDate: new Date('2027-12-31'),
user: '홍길동',
senderName: '김철수',
message: '생일 축하해요!',
'barcode.value': 'GC-2026-12345',
});
`

$3

사원증, 학생증, 출입증

`javascript
const cdata = await wallet.createDigitalId({
title: '사원증',
providerName: '삼성전자',
subType: 'employee',
user: '홍길동',
idNumber: 'EMP-2026-12345',
department: '개발팀',
position: '시니어 개발자',
issueDate: new Date('2026-01-01'),
expiryDate: new Date('2027-12-31'),
'barcode.value': 'EMP-2026-12345',
});
`

$3

교통카드, 선불 통신요금, 유틸리티 페이먼트

`javascript
const cdata = await wallet.createPayAsYouGo({
title: '지하철 교통카드',
providerName: '서울교통공사',
subType: 'transit',
accountId: 'METRO-2026-12345',
balance: '25500',
balanceCurrency: 'KRW',
user: '홍길동',
'barcode.value': 'METRO-2026-12345',
});
`

$3

위 타입에 해당하지 않는 범용 카드

`javascript
const cdata = await wallet.createGeneric({
title: '주차권',
providerName: '시티파킹',
subtitle: '월간 주차 허가증',
user: '홍길동',
cardNumber: 'PARK-2026-12345',
header1: 'A구역',
body1: 'A구역 종일 주차 가능',
issueDate: new Date('2026-01-01'),
expiryDate: new Date('2026-12-31'),
'barcode.value': 'PARK-2026-12345',
});
`

커스텀 카드 데이터

템플릿을 사용하지 않고 직접 카드 데이터를 구성할 수도 있습니다:

`javascript
const cardData = {
card: {
type: 'ticket',
subType: 'entrances',
data: [{
refId: 'my-unique-ref-id',
createdAt: Date.now(),
updatedAt: Date.now(),
language: 'en',
attributes: {
title: 'My Custom Ticket',
// ... 기타 속성
},
}],
},
};

const cdata = await wallet.generateCdata(cardData);
`

Add to Samsung Wallet URL 생성

$3

CDATA에 전체 카드 데이터를 포함하는 방식입니다.

`javascript
const cdata = await wallet.createTicket({ ... });

// Samsung Wallet 추가 버튼 URL 생성
// 형식: https://a.swallet.link/atw/v3/{cardId}#Clip?cdata={cdata}
const addUrl = wallet.getAddToWalletUrl(cdata, 'YOUR_CARD_ID', {
rdClickUrl: 'https://your-tracking.com/click',
});

console.log('Add to Wallet URL:', addUrl);
`

$3

민감한 데이터가 있거나 정적 링크가 필요할 때 사용합니다.
이 방식은 refId만 전달하고, Samsung 서버가 파트너 서버에 Get Card Data API를 호출하여 데이터를 가져옵니다.

`javascript
// Data Fetch Link URL 생성
// 형식: https://a.swallet.link/atw/v3/{certificateId}/{cardId}#Clip?pdata={refId}
const fetchUrl = wallet.getDataFetchUrl('TICKET-12345', 'YOUR_CARD_ID');

console.log('Data Fetch URL:', fetchUrl);
`

> ⚠️ 주의: Data Fetch Link 사용 시 파트너 서버에서 Get Card Data API를 구현해야 합니다.

Samsung Server API (카드 상태 관리)

Samsung Wallet에 등록된 카드의 상태를 관리할 수 있습니다.

$3

카드 정보가 변경되었을 때 Samsung에 알림을 보냅니다.

`javascript
// Send Card State에서 받은 callbackUrl 사용
const callbackUrl = 'https://kr.swallet.link/wltex/cards/YOUR_CARD_ID';

const result = await wallet.sendUpdateNotification(
callbackUrl,
'ticket', // 카드 타입
[{ refId: 'TICKET-12345' }]
);

console.log('Update 결과:', result.ok);
`

$3

공연/이벤트 취소 시 Samsung Wallet 카드도 만료 처리합니다.

`javascript
const result = await wallet.sendCancelNotification(
callbackUrl,
'ticket',
[{
refId: 'TICKET-12345',
eventId: 'EVENT-001',
estimatedOrActualStartDate: Date.now(),
}]
);

console.log('Cancel 결과:', result.ok);
`

$3

Samsung Server API 호출 시 필요한 인증 토큰을 생성합니다.

`javascript
const authToken = await wallet.generateAuthToken();
console.log('Auth Token:', authToken);
`

상수 사용

패키지에서 제공하는 상수를 사용하면 타입 안정성을 높일 수 있습니다:

`javascript
const {
SamsungWallet,
CardType,
CardState,
BarcodeType,
TicketSubType
} = require('samsung-wallet-cdata');

// 카드 타입 확인
console.log(CardType.TICKET); // 'ticket'
console.log(CardType.COUPON); // 'coupon'

// 카드 상태
console.log(CardState.CANCELED); // 'CANCELED'

// 바코드 타입
console.log(BarcodeType.QRCODE); // 'QRCODE'

// 티켓 서브타입
console.log(TicketSubType.CONCERTS); // 'concerts'
`

$3

| 상수 | 설명 |
|------|------|
| CardType | 카드 타입 (TICKET, COUPON, LOYALTY, BOARDING_PASS, GIFT_CARD, DIGITAL_ID, PAY_AS_YOU_GO, GENERIC) |
| CardState | 카드 상태 (ACTIVE, EXPIRED, CANCELED, DELETED, REDEEMED, SUSPENDED) |
| BarcodeType | 바코드 타입 (QRCODE, BARCODE, SERIAL) |
| BarcodeFormat | 바코드 형식 (QRCODE_SERIAL, QRCODE_URL, BARCODE_SERIAL) |
| BarcodeSubFormat | 바코드 세부 형식 (QR_CODE, CODE_128, CODE_39, EAN_13 등) |
| TicketSubType | 티켓 서브타입 (ENTRANCES, CONCERTS, SPORTS, MOVIES, TRANSIT, OTHERS) |
| BoardingPassSubType | 보딩패스 서브타입 (AIRLINES, TRAINS, BUSES, OTHERS) |
| DigitalIdSubType | 디지털ID 서브타입 (EMPLOYEE, STUDENT, ACCESS, OTHERS) |
| PayAsYouGoSubType | 선불카드 서브타입 (TRANSIT, TELECOM, UTILITY, OTHERS) |

저수준 API (고급 사용자)

직접 암호화/서명 로직을 사용할 수 있습니다:

`javascript
const {
generateCdata,
readCertificate,
readPrivateKey
} = require('samsung-wallet-cdata');

// 키 로드
const samsungPublicKey = await readCertificate(samsungCertPem);
const partnerPrivateKey = await readPrivateKey(partnerKeyPem);

// CDATA 생성
const cdata = await generateCdata(
partnerId,
certificateId,
samsungPublicKey,
partnerPrivateKey,
JSON.stringify(cardData)
);
`

설정

$3

Samsung Wallet API를 사용하려면 파트너 등록 후 인증서를 발급받아야 합니다.

#### Step 1: 파트너 등록

1. Samsung Wallet Partner Portal 접속
2. "Sign Up" 클릭하여 계정 생성
3. 파트너 신청서 작성
4. 승인 대기 (보통 1-3 영업일)

#### Step 2: Wallet Card 생성

1. Partner Portal 로그인
2. "Wallet Cards" → "Create Card" 메뉴로 이동
3. 카드 타입 선택 (Ticket, Membership, Coupon 등)
4. 카드 디자인 및 필드 설정
5. 저장 후 Card ID 메모

#### Step 3: 인증서 생성

1. Partner Portal에서 "Certificates" 메뉴로 이동
2. CSR (Certificate Signing Request) 생성:
`bash
# 개인키 생성
openssl genrsa -out partner.key 2048

# CSR 생성
openssl req -new -key partner.key -out partner.csr
`
3. partner.csr을 Partner Portal에 업로드
4. 서명된 인증서와 Samsung 공개 인증서 다운로드

#### Step 4: 발급받은 정보 정리

승인 후 다음 정보들을 확보하게 됩니다:

| 항목 | 확인 위치 | 파일/값 |
|------|----------|---------|
| Partner ID | Partner Portal → Profile | 1234567890 |
| Certificate ID | Partner Portal → Certificates | cert-xxxxx |
| Card ID | Partner Portal → Wallet Cards | card-xxxxx |
| Samsung 인증서 | Partner Portal → 다운로드 | samsung.crt |
| 파트너 개인키 | 로컬 (Step 3에서 생성) | partner.key |

#### 파일 구조 예시

`
your-project/
├── certs/
│ ├── samsung.crt # Samsung 공개 인증서
│ └── partner.key # 파트너 개인키 (비밀 유지!)
├── .env
└── ...
`

> ⚠️ 보안 주의: partner.key는 절대 버전 관리(Git)에 커밋하지 마세요!

$3

`env
SAMSUNG_WALLET_PARTNER_ID=your-partner-id
SAMSUNG_WALLET_CERTIFICATE_ID=your-cert-id
SAMSUNG_WALLET_CARD_ID=your-card-id
`

TypeScript 지원

TypeScript 타입 정의가 포함되어 있습니다:

`typescript
import { SamsungWallet, TicketOptions } from 'samsung-wallet-cdata';

const wallet = new SamsungWallet({
partnerId: 'xxx',
certificateId: 'xxx',
samsungCert: '...',
partnerKey: '...',
});

const options: TicketOptions = {
title: 'Concert',
barcode: '12345',
};

const cdata = await wallet.createTicket(options);
`

API 참조

$3

| 메서드 | 설명 | 공식 스펙 |
|--------|------|----------|
| constructor(config) | 인스턴스 생성 | - |
| generateCdata(cardData) | 범용 CDATA 생성 | - |
| createTicket(options) | 티켓 CDATA 생성 | Event Ticket |
| createMembership(options) | 멤버십 CDATA 생성 | Loyalty |
| createCoupon(options) | 쿠폰 CDATA 생성 | Coupon |
| createBoardingPass(options) | 보딩패스 CDATA 생성 | Boarding Pass |
| createGiftCard(options) | 기프트카드 CDATA 생성 | Gift Card |
| createDigitalId(options) | 디지털ID CDATA 생성 | Digital IDs |
| createPayAsYouGo(options) | 선불카드 CDATA 생성 | Pay As You Go |
| createGeneric(options) | 일반카드 CDATA 생성 | Generic Card |
| getAddToWalletUrl(cdata, cardId, options) | Data Transmit Link URL 생성 | API Guidelines |
| getDataFetchUrl(refId, cardId, options) | Data Fetch Link URL 생성 | API Guidelines |
| generateAuthToken() | Samsung Server API 인증 토큰 생성 | Security |
| sendUpdateNotification(callbackUrl, cardType, cardDataList) | 카드 업데이트 알림 | API Guidelines |
| sendCancelNotification(callbackUrl, cardType, cancelDataList)` | 카드 취소 알림 | API Guidelines |

$3

Samsung Wallet API 스펙에 따라:
- JWE: RSA1_5 + A128GCM
- JWS: RS256

라이선스

MIT

참고 자료

- Samsung Wallet Developer Portal
- Samsung Wallet Partner Portal
- Wallet Card Specs
- CDATA Generation (공식 Java 코드)