클라이언트 연동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 {  loadDanalPayemntsSDK  } from "@danalpay/danal-oneapi-sdk";

// Promise
loadDanalPayemntsSDK({ clientKey: "test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq" })
.then((danalPayments) => {
  danalPayments.requestPayment({
    // ...params
  });
})

// async/await
const danalPayments = await loadDanalPayemntsSDK({ clientKey: "test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq" })
danalPayments.requestPayment({
 // ...params
});

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

3. 결제창 호출하기

SDK 초기화가 끝났다면, 이제 결제를 요청할 수 있어요.
초기화된 danalPayments 인스턴스 에서 .requestPayment() 메소드를 호출하면 결제가 시작돼요.

* 결제 수단에 따라 필요한 파라미터는 아래 요청 파라미터를 확인해 주세요.
* 결제가 시작되면 PC 환경에서는 iframe 방식으로, 모바일 환경에서는 redirect 방식으로 결제창이 열려요.

결제가 시작된 후에는 무엇을 해야 하나요?
모바일 에서는 사용자가 결제 후 돌아올 수 있도록 callback U RL처리 로직을 함께 구현해요.
callback URL에서는 결제 승인 API 를 호출해 결제를 요청할 수 있어요.

요청 파라미터

결제 요청 시에는 공통 파라미터와 함께, 결제 수단에 따라 추가 파라미터가 필요해요.

공통

파라미터타입필수길이설명
orderNamestringO250자상품명
orderIdstringO255자가맹점 주문번호
userIdstringO50자가맹점 측 사용자 ID
amountnumberO10자금액
merchantIdstringO10자상점 아이디(계약 시 발급 받은 CPID를 입력해주세요.)
successUrlstringO200자인증 성공 시 이동 할 가맹점 측 URL
failUrlstringO200자인증 실패/취소 시 이동 할 가맹점 측 URL

* orderId는 매 번 고유한 값으로 생성해야 해요.

카드

파라미터타입필수길이설명
paymentsMethodstringO결제 수단 (CARD)
taxAmountnumber세금(가맹점 특수)
cardCodestring4자카드코드
installmentMonthsstring2자할부 개월 수
easyPayProviderstring5자간편결제제휴사(KAKAO/NAVER/PAYCO)
notiUrlstring200자결제통지 받을 가맹점 측 URL

예제 코드

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

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

danalPayments.requestPayment({
  ...baseParams,
  paymentsMethod: 'CARD',
  merchantId: 'M0001',
});

주의사항

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