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