결제창 SDK

SDK 설치

HTML 페이지에 스크립트 태그로 결제창 SDK 파일을 추가합니다. 스크립트가 로드되면 전역 객체(window)에 생기는 초기화 함수를 호출하세요.


<head>
    <meta charset="utf-8" />
    <!-- SDK 추가 -->
    <script src="https://js.candypay.co.kr/payments-sdk/v1"></script>
</head>

SDK 초기화

Candypay.createSDK() 메서드로 SDK를 초기화해주세요. 반환되는 객체로 캔디페이 SDK의 모든 결제 서비스를 이용할 수 있어요. 내 상점의 클라이언트 키를 파라미터로 넣으면 캔디페이 SDK에서 상점의 정보를 확인할 수 있어요. 사용하고 싶은 제품에 따라 필요한 클라이언트 키 종류가 다른데요. 키 종류, 테스트 및 라이브 키 정보는 API 키 가이드에서 자세히 확인하세요.


const candypay = Candypay.createSDK("test_ck_8gmPHt6FgfAkzbRrysrZaJfb460J");

파라미터


/**
 * 캔디페이에서 발급하는 클라이언트 키입니다. 개발자센터의 API 키 메뉴에서 확인할 수 있어요.
 */
type ClientKey = string;

candypay.payment()

결제창을 초기화합니다.


const payment = candypay.payment({ customerId });

파라미터


interface Parameter {
 /**
  * 구매자를 식별하는 고유 아이디입니다.
  * 이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값을 넣으면 안 됩니다.
  * UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요.
  * 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다
  */
  customerId: string
}

payment.requestPayment()

결제창을 띄웁니다.

파라미터로 설정한 successUrl 또는 failUrl로 결제 요청의 결과를 확인할 수 있어요.


const url = await payment.requestPayment({
  amount: {
    value: 50000,
  },
  orderId: "bUjILtZPrmCluBhMOiqCs", // 고유 주문번호
  orderName: "캔디 사탕 외 2건",
  successUrl: window.location.origin + "/success", // 결제 요청이 성공하면 리다이렉트되는 URL
  failUrl: window.location.origin + "/fail" // 결제 요청이 실패하면 리다이렉트되는 URL
});
 
console.log(url.toString()); // url.toString() 주소로 자동 리다이렉트

파라미터


interface Parameter {
  /**
   * @minLength 16
   * @maxLength 50
   * 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 16자 이상 50자 이하의 문자열입니다.
   * 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다.
   * 결제 상태가 변해도 orderId는 유지됩니다.
   */
  orderId: string
 
  /**
   * @maxLength 100
   * @example '생수 외 1건'
   * 주문의 이름입니다. 상점이 직접 값을 지정해줘야 합니다. 구매상품으로 지정하는 것을 권장합니다.
   */
  orderName: string
 
  amount: {
    value: number
  }
 
  /**
   * 결제 요청 시 SDK에서 직접 추가할 수 있는 결제 관련 정보입니다. 최대 5개의 키-값(key-value) 쌍입니다.
   * JSON으로 직렬화했을 때 2000자를 넘을 수 없습니다.
   */
  metadata?: Jsonifiable
 
  /**
   * 결제자 본인인증(KYC) 정보입니다. 사전에 캔디페이가 허용한 가맹점만 사용할 수 있습니다.
   * 비로그인 결제에서 SMS 본인인증을 대체하며, 로그인 사용자는 전달한 값 대신 계정 본인인증 정보를 사용합니다.
   * 함께결제의 대표결제자가 아닌 참가자에게는 적용되지 않습니다.
   */
  kyc?: {
    name: string
    registNo: string
    phoneNumber?: string | null
  }
 
  /**
   * 결제 요청이 성공하면 리다이렉트되는 URL입니다.
   * https://www.example.com/success와 같이 오리진을 포함한 형태로 설정해주세요.
   * 리다이렉트되면 URL의 쿼리 파라미터로 amount, orderId, intentKey가 추가돼요.
   */
  successUrl: string
 
  /**
   * 결제 요청이 실패하면 리다이렉트되는 URL입니다.
   * https://www.example.com/fail와 같이 오리진을 포함한 형태로 설정해주세요.
   * 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
   */
  failUrl: string
}

결제자 본인인증 정보 전달

사전에 캔디페이가 허용한 가맹점은 kyc로 결제자 본인인증 정보를 함께 전달할 수 있어요. 비로그인 결제에서는 SMS 본인인증을 대체합니다. 로그인 사용자가 결제하는 경우에는 전달한 kyc 값이 아니라 로그인 계정의 본인인증 정보를 사용해요.


await payment.requestPayment({
  amount: { value: 50000 },
  orderId: "bUjILtZPrmCluBhMOiqCs",
  orderName: "캔디 사탕 외 2건",
  kyc: {
    name: "홍길동",
    registNo: "900101",
    phoneNumber: "01012345678"
  },
  successUrl: window.location.origin + "/success",
  failUrl: window.location.origin + "/fail"
});

kyc는 권한이 없는 가맹점이 전달하면 요청이 거절됩니다. 함께결제에서는 대표결제자가 아닌 참가자에게 이 정보가 적용되지 않아요.

응답

결제 요청이 성공하면 파라미터로 설정한 successUrl로 이동해요. 쿼리 파라미터의 amount 값이 메서드 파라미터로 설정한 amount와 같은지 반드시 확인하고 결제 승인 API를 호출해서 결제를 완료하세요.


{successUrl}?amount={AMOUNT}&orderId={ORDER_ID}&intentKey={INTENT_KEY}

결제 요청이 실패하면 파라미터로 설정한 failUrl로 이동해요. 쿼리 파라미터로 에러 코드와 메시지를 확인하세요. details 값은 반드시 오지는 않습니다.


{failUrl}?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}&details={DETAILS}