Skip to Content
가이드결제창 연동하기

결제창 연동하기

캔디페이 결제창을 연동하는 방법이에요. 구매자가 결제창에서 직접 결제수단 인증을 진행해요.

API 키 준비하기

개발자센터의 API 키 메뉴(현재 개발중)에서 API 개별 연동 키를 확인하세요. 클라이언트 키와 시크릿 키가 모두 필요해요.

테스트 키와 라이브 키의 차이점도 확인하고 연동을 시작하세요.

로그인하지 않아도 문서 테스트 키로 테스트 연동할 수 있어요.

1. 결제창 띄우기

먼저 주문서 페이지에 결제창을 연동할게요. 아래 코드는 주문서 페이지의 예시에요.

스크립트 태그 또는 패키지 매니저로 캔디페이 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, payment() 메서드로 결제창 인스턴스를 생성하세요. 아래 코드에서는 payment라는 인스턴스를 생성했어요.

그럼 이제 결제창을 띄울 준비가 됐어요. payment.requestPayment() 메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요. 메서드의 파라미터로 주문번호, 결제금액, successUrl, failUrl 등 필요한 정보를 전달하세요. 그리고 주문서의 ‘결제하기’ 버튼에 결제 요청 메서드를 이벤트로 등록해주세요.

모바일 환경에서는 iframe이나 frame 위에서 결제창을 호출하면 안 돼요. 모바일 환경에서 결제창을 호출하면 페이지가 항상 이동하기 때문입니다.

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="utf-8" />
    <!-- SDK 추가 -->
    <script src="https://js.candypay.co.kr/payments-sdk/v1"></script>
  </head>
  <body>
    <!-- 결제하기 버튼 -->
    <button class="button" style="margin-top: 30px" onclick="requestPayment()">결제하기</button>
    <script>
      // ------  SDK 초기화 ------
      const clientKey = "test_ck_CANDYwX7K8mYw1lj05m8yQxzvNPG";
      const customerId = "p_1Gq3nudQxklUWpOUkj9"; // 매장 고객키. 자유롭게 설정 가능. 비회원 경우에는 `Candypay.ANONYMOUS` 변수 활용 권장.
      const candypay = Candypay(clientKey);
      const payment = candypay.payment({ customerId });
      // ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
      async function requestPayment() {
        // 결제를 요청하기 전에 orderId, amount를 서버에 저장하세요.
        // 결제 과정에서 악의적으로 결제 금액이 바뀌는 것을 확인하는 용도입니다.
        await payment.requestPayment({
          amount: {
            value: 50000,
          },
          orderId: "bUjILtZPrmCluBhMOiqCs", // 고유 주문번호
          orderName: "캔디 사탕 외 2건",
          successUrl: window.location.origin + "/success", // 결제 요청이 성공하면 리다이렉트되는 URL
          failUrl: window.location.origin + "/fail", // 결제 요청이 실패하면 리다이렉트되는 URL
        });
      }
    </script>
  </body>
</html>

위 코드를 실행한 다음에 ‘결제하기’ 버튼을 누르면 아래와 같은 결제창이 열려요. 테스트하고 싶은 결제수단을 선택하고 결제 정보를 입력하세요. 테스트 클라이언트 키를 사용했다면 실제로 결제되지 않으니 안심하세요.

FIXME 표준결제창 예제 이미지 삽입

2. 리다이렉트 URL로 이동하기

결제창에서 구매자의 결제수단을 인증해요. 인증 결과는 리다이렉트 URL로 확인할 수 있어요. 결제 인증이 성공했다면 성공 리다이렉트 URL(successUrl)의 쿼리 파라미터로 결제 정보를 확인하고 검증해주세요. 인증이 실패했다면 이동한 실패 리다이렉트 URL(failUrl)의 쿼리 파라미터로 에러를 확인해주세요.

결제 인증이 성공했어요

결제 정보가 모두 인증됐다면, successUrl로 이동해요. 해당 URL에 아래 세 가지 쿼리 파라미터가 추가돼요.

/success?orderId={ORDER_ID}&intentKey={INTENT_KEY}&amount={AMOUNT}

  1. 쿼리 파라미터의 amount 값과 결제 요청 시 보낸 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.

  2. 서버에 orderId, intentKey, amount, 값을 저장하세요. 결제 승인, 취소, 조회 등에 사용되기 때문에 꼭 저장해주세요.

결제 인증이 실패했어요

만약에 결제 정보가 틀려서 결제 인증이 실패했다면, failUrl로 이동해요. 해당 URL에는 아래 세 가지 쿼리 파라미터가 추가돼요. 에러 코드와 메시지를 확인해서 구매자에게 적절한 안내 메시지를 보여주세요.

/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&intentKey={INTENT_KEY}

자주 발생하는 에러

  • PAY_PROCESS_CANCELED: 구매자에 의해 결제가 취소되면 발생합니다. 결제 과정이 중단된 것이라서 failUrl로 orderId가 전달되지 않아요.
  • REJECT_CARD_COMPANY: 구매자가 입력한 카드 정보에 문제가 있으면 발생합니다. 오류 메시지를 확인하고 구매자에게 안내해주세요.
  • PAY_PROCESS_ABORTED: 기타 이유로 승인이 실패하면 발생합니다. 오류 메시지를 확인하세요. 계약 관련 오류는 캔디페이 고객센터로 문의해주세요.

3. 결제 승인하기

마지막 단계로 결제 승인 API를 호출하세요. API 키 준비하기 단계에서 확인한 시크릿 키를 사용해요.

시크릿 키와 :을 base64로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다. 시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.

Basic base64("{API_SECRET_KEY}:")

결제 승인 API의 헤더에 인코딩한 시크릿 키 인증 헤더를 추가하세요. 요청 본문 파라미터에는 앞 단계에서 리다이렉트 URL로 받은 intentKey, orderId, amount 를 넣어주세요.

curl --request POST \
  --url https://api.candypay.co.kr/px/intents/confirm \
  --header 'Authorization: Basic dGVzdF9za19HS05iZE92azVya21MMWxCRE1xM24wN3hsem1qOg==' \
  --header 'Content-Type: application/json' \
  --data '{"orderId":"{ORDER_ID}","amount":100,"intentKey":"{intentKey}"}'

4. 응답 확인하기

결제 승인이 성공했어요

결제 승인 API의 결과로 HTTP 200 OK와 함께 PaymentIntent 객체가 돌아오면 결제가 정상적으로 완료됐어요.

응답으로 받은 PaymentIntent 객체가 아래 예시와 다르다면 API 버전을 확인하세요.

{
    "approvedAt": "2025-11-01T13:00:00+09:00",
    "cancel": {
        "canceledAt": "2025-11-01T14:00:00+09:00"
    },
    "intentKey": "6u5a0nGOpdhTm1bay2R5I",
    "orderId": "demo_order_1761873673489",
    "orderName": "데모 결제",
    "mId": 10023,
    "totalAmount": 100,
    "methods": [
        {
            "card": {
                "number": "53275011****9704",
                "installmentPlanMonths": 0
            },
            "type": "KEYIN",
            "amount": 100
        }
    ],
    "status": "CANCELED",
    "requestedAt": "2025-10-31T10:30:00+09:00"
}

결제 승인이 실패했어요

결제 승인에 실패하면 HTTP 4XX 또는 5XX 코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요. 테스트 환경에서 결제 승인 실패를 재현해보고 싶다면 캔디페이 API 테스트 헤더를 사용해보세요.

Last updated on
환경 설정하기