Skip to Content
레퍼런스결제창 SDK

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

const candypay = Candypay("test_ck_CANDYwX7K8mYw1lj05m8yQxzvNPG");

파라미터

/**
 * 캔디페이에서 발급하는 클라이언트 키입니다. 개발자센터의 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
 
  /**
   * 결제 요청이 성공하면 리다이렉트되는 URL입니다.
   * https://www.example.com/success와 같이 오리진을 포함한 형태로 설정해주세요.
   * 리다이렉트되면 URL의 쿼리 파라미터로 amount, orderId, intentKey가 추가돼요.
   */
  successUrl: string
 
  /**
   * 결제 요청이 실패하면 리다이렉트되는 URL입니다.
   * https://www.example.com/fail와 같이 오리진을 포함한 형태로 설정해주세요.
   * 리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.
   */
  failUrl: string
}

응답

결제 요청이 성공하면 파라미터로 설정한 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}
Last updated on
코어 API기관 코드 일람