클라이언트 연동breadcrumbSDK 연동

SDK 연동 가이드

SDK를 이용한 클라이언트 연동 방법을 설명해요.

SDK란?

다날 결제 SDK는 결제 연동을 보다 빠르고 간편하게 구현할 수 있도록 도와주는 도구예요.
SDK를 통해 결제창 호출 및 사용자 인증 흐름을 쉽게 구현할 수 있어요.

1. SDK 불러오기

다날 결제 SDK는 아래 두 가지 방식 중 하나를 선택하여 설치할 수 있어요.
프로젝트 환경에 따라 편하신 방법을 선택해 주세요.

다날 결제 SDK를 연동하는 두 가지 방식
1. HTML <script> 태그를 사용하기
간단한 HTML 기반 페이지에서 빠르게 연동할 때 이 방식을 사용하면 좋아요.
2. npm 모듈을 사용하기
React.js 등 Frontend Framework와 함께 사용하는 프로젝트에 추천드려요.

HTML 파일의 <head> 또는 <body> 태그 안에 아래 코드를 추가해 주세요.

<script src="https://static.danalpay.com/d1/sdk/index.js"></script>

이 스크립트를 추가하면, 브라우저의 window 전역 객체에 DanalPayments라는 생성자가 등록돼요.
이 객체를 통해 이후 결제 기능을 사용할 수 있어요.

2. SDK 초기화

결제를 요청하기 전에 SDK를 초기화하는 과정이 필요해요.
사전에 발급받은 Client Key를 사용해서 DanalPayments 인스턴스를 만들어요.

import {  loadDanalPaymentsSDK  } from "@danalpay/javascript-sdk";

// Promise
loadDanalPaymentsSDK({ clientKey: "CL_TEST_I4d8FWYSSKl-42F7y3o9g_7iexSCyHbL8qthpZxPnpY=" })
.then((danalPayments) => {
danalPayments.requestPayment({
// ...params
});
})

// async/await
const danalPayments = await loadDanalPaymentsSDK({ clientKey: "CL_TEST_I4d8FWYSSKl-42F7y3o9g_7iexSCyHbL8qthpZxPnpY=" })
danalPayments.requestPayment({
// ...params
});

Client Key가 없으신가요? 테스트 단계라면 샌드박스에서 테스트 키를 제공해요.
테스트와 계약 체결까지 모두 완료하셨다면 영업 담당자를 통해 연동에 필요한 키를 받을 수 있어요.

3. 결제창 호출하기

SDK 초기화가 끝났다면, 결제를 요청할 수 있어요.
초기화된 danalPayments 객체에서 .requestPayment()함수를 실행하면 결제가 시작돼요.

열리는 결제창은 paymentsMethod 값에 따라 결정돼요.

  • 단일 결제수단만 제공하려면 paymentsMethod에 해당 수단 코드를 그대로 넣어주세요.
    예를 들어 "CARD"를 넣으면 신용카드 결제창이, "MOBILE"을 넣으면 휴대폰결제 창이 열려요.
  • 여러 결제수단을 한 화면에서 제공하고 싶다면 paymentsMethod를 "INTEGRATED"로 넣어주세요.
    • 고객에게 제공할 결제수단 목록은 methods 파라미터에 JSON 형식으로 전달해야 해요.
    • 특정 결제수단이 노출되길 원한다면 설정 값이 없더라도 해당 결제수단 코드를 반드시 JSON에 포함시켜야 합니다.
      (예: "CARD": {}처럼 빈 객체라도 꼭 포함)

결제수단별로 필요한 추가 파라미터는 요청 파라미터표에서 확인해주세요.
📲 결제가 시작되면
  • PC 환경에서는 결제창이 현재 페이지 안에 iframe으로 표시되고,
  • 모바일 환경에서는 새로운 페이지로 이동하는 redirect 방식으로 표시돼요.

요청 파라미터

결제 요청 시 본문은 아래 두 영역으로 구성되어있어요.

  • 공통 파라미터: 모든 결제수단에서 사용되는 필수 항목
  • 결제수단별 추가 파라미터: 각 결제수단에서 요구하는 별도 항목 (예: CARD, MOBILE, KAKAO 등)

공통 파라미터

파라미터타입필수길이설명
orderNamestringO100 byte
결제 상품명을 입력합니다.
일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 80byte 이하 사용을 권장드립니다.
orderIdstringO50 byte
고객 주문번호를 입력합니다.
고객 결제 건을 식별하기 위해 사용하는 거래별 고유값으로 반드시 중복되지 않도록 생성하여
저장 및 관리해주시기 바랍니다.(예: 년월일시-일련번호)
userIdstringO60 byte
고객 식별 키를 입력합니다.
일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 20byte 이하 사용을 권장드립니다.
amountnumberO결제수단별 상이
결제 금액을 입력합니다.
결제 수단마다 최소 및 최대 결제 가능 금액이 다르며,
입력한 금액이 해당 수단의 최소 금액 기준에 미달할 경우, 해당 결제 수단은 결제창에 노출되지 않습니다.

아래 표를 참고하여 사용 가능한 결제 수단별 금액 조건을 확인해 주세요.

결제서비스최소 결제 요청 금액금액 입력 최대 자릿수
휴대폰결제301원7자
신용카드100원10자
네이버페이100원10자
카카오페이100원10자
페이코100원10자
계좌이체150원9자
가상계좌1원9자
컬쳐랜드상품권1원7자
도서문화상품권1원7자
successUrlstringO200 byte
결제 성공 후 이동 URL을 입력합니다.
반드시 HTTPS 주소로 입력해야 하며, 외부 접근이 가능한 페이지를 지정해주시기 바랍니다.
failUrlstringO200 byte
결제 실패 또는 사용자가 결제를 취소했을 때 이동할 URL을 입력합니다.
실패 사유 안내를 포함한 가맹점 전용 안내 페이지로 연결해주시기 바랍니다.
merchantIdstringO20 byte
계약 완료 후 발급 받은 CPID를 입력합니다.
다날 통합결제창, ONE API 결제 연동 시 사용되는 ID입니다.
userEmailstring64 byte
결제 완료 후 결과 안내 메일을 수신 받을 이메일 주소를 입력합니다.
사용자 이메일, 결제 완료 후 결제 결과에 대한 메일을 발송 하기 위해 사용됩니다.

결제수단별 추가 파라미터

파라미터타입필수길이설명
paymentsMethodstringO20 byte
통합결제창을 열기 위한 결제 수단 코드 INTEGRATED를 입력합니다.
통합결제창을 호출하면, 고객이 결제창 내에서 원하는 결제 수단을 직접 선택하고 결제를 진행할 수 있습니다.
methodsjson
paymentsMethod가 "INTEGRATED"일 때 입력합니다.
통합결제창에서 함께 제공하고자 하는 결제수단을 JSON 객체 형태로 전달해 주세요.
  1. 각 결제수단별 필수 입력 값이 있으니 결제수단별 탭을 참고하여 필수 값을 포함해 주세요.
  2. 특정 결제수단을 노출하고자 할 경우,
    설정할 값이 없더라도 해당 결제수단 코드를 빈 객체 형태로 반드시 포함해야 합니다.
    예: "CARD": {}, "NAVER": {}, "KAKAO": {} ...
  3. 각 결제수단 내부에 중복되는 paymentMethod 파라미터는 생략하셔도 됩니다.

통합결제창 결제를 요청하는 예시 코드는 아래와 같아요.

const danalPayments = DanalPayments("CL_TEST_I4d8FWYSSKl-42F7y3o9g_7iexSCyHbL8qthpZxPnpY=");
const baseParams = {
  orderName: '상품명',
  amount: 10000,
  merchantId: '9810030930',
  orderId: '123123',
  userId: 'user@example.com',
  successUrl: 'https://successUrl.com',
  failUrl: 'https://failUrl.com',
};

danalPayments.requestPayment({
  ...baseParams,
  paymentsMethod: 'INTEGRATED',
          mobile: {
          itemCode: '1270000000',
          itemType: '1',
        },
        virtualAccount: {
          notiUrl: 'https://notiUrl.com',
        },
        card: {},
        naverPay: {},
        kakaoPay: {},
        payco: {},
        transfer: {},
        cultureland: {},
        bookAndLife: {},
});

주의사항

  • 테스트 환경과 실제 환경의 클라이언트 키는 다릅니다. 실제 서비스 시에는 발급받은 실제 클라이언트 키를 사용해야 합니다.
  • 결제 요청 시 orderId는 고유한 값이어야 합니다. 중복된 orderId로 결제 요청 시 오류가 발생할 수 있습니다.
  • successUrl, failUrl은 결제 완료 후 리다이렉트 될 URL입니다. 실제 서비스에 맞게 설정해야 합니다.
  • 모바일 환경에서는 리다이렉트 방식으로 결제창이 열리므로, 결제 완료 후 원래 페이지로 돌아오기 위한 처리가 필요할 수 있습니다.
  • 가상계좌 결제의 경우, 입금 통보를 받기 위한 notiUrl 설정이 필요합니다.

💡다음 단계: 사용자 인증 결과 처리

  • 결제창을 성공적으로 호출하면, 사용자가 결제창에서 결제를 위한 인증을 진행할 차례에요
  • 사용자는 선택한 결제수단으로 결제를 완료하기 위해 아래 인증 단계를 거쳐야 해요.
    • 휴대폰결제: 본인인증(SMS, VACS, ACS, 삼성페이 인증 등)
    • 신용카드: 카드사 인증(앱카드, 비밀번호 등)
    • 간편결제: 간편결제사 인증
    • 계좌이체: 은행 계좌 인증
  • 자세한 내용은 요청 사용자 인증 결과 처리 가이드를 확인해 주세요.
맨 위로