메인 콘텐츠로 건너뛰기

SDK

MarkdownChatGPTClaude

웹 사용의 경우, 다음과 같은 이유로 Unico SDK를 사용하는 것이 권장되는 방식입니다:

  • 더 높은 보안성;
  • 귀사의 흐름과 통합된 경험;
  • SDK 사용 시 더 높은 전환율;
  • 더 쉬운 구현.
경고

이 문서에서 정한 표준을 준수하지 않는 통합을 사용하면 시스템 기능에 예기치 않은 장애가 발생할 수 있으며, 이는 비대면 카드 검증이 지원하거나 보증하지 않습니다.

예: 웹뷰 내에서 Unico by iFrame을 구현하거나, HTML 태그를 통해 iFrame을 구현하는 경우 등.

일반 지침​

운영 성능을 최적화하고 전환율을 개선하며 더 부드러운 사용자 경험을 제공하려면, 애플리케이션에서 Unico SDK를 전체 화면 모드로 구현하는 것이 필수입니다.

시작하는 방법​

비대면 카드 검증 SDK를 통해 비대면 카드 검증을 사용하려면, 첫 번째 단계는 사용자 여정 경험을 표시할 호스트로 사용될 도메인을 등록하는 것입니다.

위험

이 설정을 진행하려면 통합 프로젝트 담당자 또는 Unico 지원팀에 알리세요.

SDK 사용을 시작하려면, 먼저 Unico 웹 SDK 설치부터 진행해야 합니다:

npm install idpay-b2b-sdk
팁

Unico SDK 패키지를 설치할 때, 사용 중인 버전을 명시하지 않고 배포하여 의존성 관리자가 항상 마이너 및 패치 버전을 최신으로 업데이트하도록 하세요.

이전 버전을 확인하려면 npmjs.com/package/idpay-b2b-sdk로 이동하세요.

사용 가능한 메서드​

init(options)​

이 메서드는 거래 ID와 관계없이 SDK를 초기화할 수 있게 하여 최종 사용자 경험을 더 부드럽게 만듭니다. 이는 거래 ID와 토큰이 사용 가능해질 때, 애플리케이션이 이 메서드를 통해 이미 사전 로드되어 있기 때문입니다. 애플리케이션에서 이 메서드를 직접 호출하지 않으면, SDK가 처음 열릴 때 최종 사용자는 긴 로딩 시간을 경험하게 됩니다.

매개변수:

  • options — 설정 속성을 담은 객체를 받습니다:
    • type — 초기화할 흐름의 유형입니다. 현재 저희는 IFRAME 유형을 제공합니다. 새로운 애플리케이션의 경우 IFRAME 유형을 사용하는 것을 권장합니다. 이는 체크아웃 화면을 벗어날 필요가 없고 경험을 사전 로드할 수 있어, 최종 사용자 경험을 훨씬 더 부드럽고 마찰 없이 만들어 줍니다.
import { IDPaySDK } from "idpay-b2b-sdk";

IDPaySDK.init({
  type: 'IFRAME',
  env: 'uat' // Only needed for the test environment.
});

open({ transactionId, token, onFinish? })​

이 메서드는 이전에 초기화 함수에서 선택한 흐름 유형에 따라 비대면 카드 검증 경험을 엽니다. REDIRECT 흐름의 경우, 이 함수는 비대면 카드 검증 캡처 흐름 라우트로 단순 리다이렉트를 수행합니다. IFRAME 흐름의 경우, 이 함수는 사전 로드된 iframe을 표시하고 고객 페이지와 비대면 카드 검증 경험 간의 메시징 흐름을 시작합니다.

매개변수:

  • options — 설정 속성을 담은 객체를 받습니다:
    • transactionId — 생성된 거래의 ID를 받습니다. 이 ID는 거래 세부 정보를 얻고 흐름을 올바르게 완료하는 데 중요합니다(API를 통한 거래 생성 시 얻을 수 있습니다).
    • token — 생성된 거래의 토큰을 받습니다. 이 토큰은 거래를 인증하고 승인된 도메인만 사용할 수 있도록 보장하는 데 중요합니다(API를 통한 거래 생성 시 얻을 수 있습니다).
    • onFinish(transaction, type)(선택 사항) — 비대면 카드 검증 캡처 흐름이 종료될 때 실행되는 콜백 함수를 받으며, 두 개의 인자를 전달합니다: 거래 객체({ captureConcluded, concluded, id })와 응답 유형 — 흐름이 성공적으로 완료된 경우 FINISH, 오류로 인해 흐름이 중단된 경우 ERROR입니다. 흐름에서 오류가 발생한 경우, 거래 상태는 변경되지 않으며, 설정된 경우에도 웹훅을 통한 콜백이 트리거되지 않습니다.
const transactionId = '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf';
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c';

const transaction = {
  id: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  concluded: true,
  captureConcluded: true
};

const onFinish = (transaction, type) => {
  console.log('response', transaction, type);
}

IDPaySDK.open({
  transactionId,
  token,
  onFinish
});

// You can also close the SDK explicitly using the method below
IDPaySDK.close();

보안​

필요 사항과 과제를 신중히 분석한 후, 저희는 콘텐츠 보안 정책(Content Security Policy, CSP)을 구현하는 대신 인증 토큰을 사용하는 iFrame 기반 솔루션을 채택하기로 결정했습니다. 이 결정은 보안과 고객의 요구를 충족하는 데 필요한 유연성과 관련된 여러 고려 사항에 따른 것입니다.

CSP의 배경과 과제​

**콘텐츠 보안 정책(Content Security Policy, CSP)**은 **크로스 사이트 스크립팅(Cross-Site Scripting, XSS)**과 코드 삽입과 같은 다양한 유형의 공격으로부터 웹 애플리케이션을 보호하는 강력한 도구입니다. 하지만 CSP 정책을 설정할 때는 신뢰할 수 있는 도메인의 엄격한 목록을 정의해야 합니다. 이 접근 방식은 도메인이 고정되어 있고 예측 가능한 경우에는 잘 작동합니다. 하지만 동적이고 가변적인 도메인을 자주 사용하는 저희 고객들에게는 이러한 엄격한 설정이 상당한 어려움을 초래합니다.

동적 도메인의 취약점​

동적 도메인은 CSP를 사용할 때 상당한 보안 위험을 초래합니다. 고객의 도메인이 자주 변경되거나 동적으로 생성되는 경우, 이러한 새 도메인을 포함하도록 CSP 정책을 지속적으로 업데이트해야 합니다. 이는 유지보수 부담을 늘릴 뿐만 아니라 CSP 정책이 적용되는 도메인을 노출시킵니다. CSP 정책에 추가된 각 도메인은 제대로 관리되지 않을 경우 잠재적인 취약점이 될 수 있습니다.

iFrame과 인증 토큰을 사용한 해결책​

이러한 위험을 완화하고 고객이 필요로 하는 유연성을 충족하기 위해, 저희는 인증 토큰과 결합된 iFrame을 사용하기로 결정했습니다. 이 솔루션은 추가적인 보안 계층을 제공하며, 광범위하고 동적인 도메인 목록을 노출하거나 관리할 필요를 없애줍니다.

작동 방식​

  • 안전한 인증: 각 iframe은 거래마다 고유한 인증 토큰과 함께 로드되어, 승인된 사용자만 콘텐츠에 접근할 수 있도록 보장합니다. 이 토큰은 실시간으로 검증되어 추가적인 보안 및 제어 계층을 제공합니다.
  • 콘텐츠 격리: iFrame을 사용하면 콘텐츠를 별도의 컨텍스트에서 격리할 수 있어, 서로 다른 출처 간의 간섭 위험을 줄이고 잠재적인 공격을 완화합니다.
  • 동적 도메인에 대한 유연성: 정적인 CSP 정책에 의존하지 않음으로써, 저희 솔루션은 보안 정책을 지속적으로 업데이트할 필요 없이 고객의 동적 도메인에 쉽게 적응합니다.
마지막 업데이트 에