JSPM

@openmkt/payment-sdk

1.0.0
    • ESM via JSPM
    • ES Module Entrypoint
    • Export Map
    • Keywords
    • License
    • Repository URL
    • TypeScript Types
    • README
    • Created
    • Published
    • Downloads 11
    • Score
      100M100P100Q71269F
    • License MIT

    PortOne V2 기반 서버사이드 결제 SDK — 결제·취소·조회·빌링키·본인인증

    Package Exports

    • @openmkt/payment-sdk

    Readme

    @cafeblanc/payment-sdk

    PortOne V2 기반 서버사이드 결제 SDK.
    HMAC-SHA256 서명·멱등성·재시도를 자동 처리합니다.

    설치

    npm install @cafeblanc/payment-sdk

    초기화

    import { PaymentSDK } from '@cafeblanc/payment-sdk';
    
    const sdk = new PaymentSDK({
      apiKey:        process.env.SDK_API_KEY!,
      signingSecret: process.env.SDK_SIGNING_SECRET!,
      baseUrl:       process.env.PAYMENT_SERVER_URL!, // e.g. https://api.yourplatform.com
    });

    사용법

    결제 생성 (checkout)

    const result = await sdk.checkout({
      provider:      'portone',
      pgProvider:    'KAKAOPAY',   // SMARTRO_V2 | INICIS | KAKAOPAY | KCP | TOSSPAYMENTS
      orderId:       'order_001',
      amount:        15000,
      currency:      'KRW',
      customerEmail: 'buyer@example.com',
      returnUrl:     'https://yourshop.com/success',
    });
    // result.channelKey → 프론트 PortOne 브라우저 SDK에 전달
    // result.merchantOrderRef → 결제 검증 시 사용

    결제 검증 (verify)

    const result = await sdk.verify({
      provider:          'portone',
      orderId:           'order_001',
      providerPaymentId: 'payment_abc123',
      amount:            15000,
      currency:          'KRW',
    });
    // result.status === 'PAID' → 결제 완료

    결제 취소 (cancel)

    // 전액 취소
    await sdk.cancel({ provider: 'portone', paymentId: 'payment_abc123', reason: '고객 요청' });
    
    // 부분 취소
    await sdk.cancel({ provider: 'portone', paymentId: 'payment_abc123', reason: '부분 환불', amount: 5000 });

    결제 조회 (getPayment)

    const payment = await sdk.getPayment({ provider: 'portone', paymentId: 'payment_abc123' });

    빌링키 발급 (정기결제 카드 등록)

    const { billingKey } = await sdk.issueBillingKey({
      provider:   'portone',
      storeId:    'store-xxxx',
      channelKey: 'channel-key-xxxx',
      customer:   { email: 'user@example.com' },
    });

    빌링키 결제

    await sdk.payWithBillingKey({
      provider:   'portone',
      paymentId:  `pay_${Date.now()}`,
      billingKey: 'billing-key-xxxx',
      orderName:  '월정액 구독',
      amount:     9900,
      currency:   'KRW',
    });

    본인인증

    // 방법 A: 프론트 PortOne 브라우저 SDK 완료 후 서버 조회
    const result = await sdk.getIdentityVerification({ identityVerificationId: 'iv_001' });
    
    // 방법 B: 서버 주도 OTP 방식
    await sdk.sendIdentityVerification({
      identityVerificationId: 'iv_001',
      customer: { name: '홍길동', phoneNumber: '01012345678' },
    });
    const verified = await sdk.confirmIdentityVerification({ identityVerificationId: 'iv_001', otp: '123456' });
    // verified.status === 'VERIFIED'
    // verified.name, verified.phone, verified.birthdate, verified.gender, verified.ci

    에러 처리

    import { SdkError } from '@cafeblanc/payment-sdk';
    
    try {
      await sdk.verify({ ... });
    } catch (err) {
      if (err instanceof SdkError) {
        console.error(err.code, err.status, err.requestId);
      }
    }

    지원 PG사

    PgProvider PG사
    SMARTRO_V2 스마트로
    INICIS KG이니시스
    KAKAOPAY 카카오페이
    KCP KCP
    TOSSPAYMENTS 토스페이먼츠

    빌드

    npm run build   # dist/ 생성 (CJS + ESM + .d.ts)
    npm run typecheck