링크페이

링크페이는 상점 서버에서 주문 정보와 결제 금액으로 결제 링크를 생성하고, 구매자에게 전달해 캔디페이 결제창에서 결제를 진행하는 기능입니다.

별도의 상품 등록이나 상품별 상세 내역 없이 이용할 수 있습니다. 주문번호(orderId), 주문명(orderName), 결제 금액(amount) 등 아래 요청 필드는 필요합니다. 생성된 링크는 상점이 관리하는 앱 푸시, 문자, 메신저 등의 채널로 전달합니다.

결제 링크 응답 객체

결제 링크 생성에 성공하면 결제 세션의 식별자, 결제 링크와 만료 시각을 반환합니다.

interface CreatePaymentSessionResponse {
  /** 결제 세션 식별자입니다. */
  token: string

  /** 구매자가 열 결제 링크입니다. 이 값을 그대로 전달하세요. */
  checkoutUrl: string

  /** 결제 링크가 만료되는 ISO 8601 형식의 시각입니다. */
  expiresAt: string
}

결제 링크 생성

주문에 대한 결제 세션을 생성하고 구매자에게 전달할 결제 링크를 반환합니다. 링크를 열면 Web SDK와 동일한 캔디페이 결제창에서 결제를 진행합니다.

Request

POST https://api.candypay.co.kr/px/payfront/sessions
Content-Type: application/json

상점 서버에서 시크릿 키로 요청을 인증합니다. 시크릿 키 뒤에 :을 붙인 값을 Base64로 인코딩하고 Basic 인증 헤더에 넣으세요. 시크릿 키는 브라우저나 앱에 노출하면 안 됩니다. 자세한 내용은 API 키 문서를 참고하세요.

Authorization: Basic base64("{API_SECRET_KEY}:")

요청 본문

?가 붙은 필드는 선택 사항이며, 나머지 필드는 필수입니다.

interface CreatePaymentSessionBody {
  /**
   * 구매자를 식별하는 추측 불가능한 상점 고객 ID입니다.
   * 이메일, 전화번호, 자동 증가 번호처럼 유추할 수 있는 값을 사용하면 안 됩니다.
   * 비회원 결제에는 "ANONYMOUS"를 사용할 수 있습니다.
   *
   * @minLength 2
   * @maxLength 50
   * @pattern ^[a-zA-Z0-9-_=\.@]{2,50}$
   */
  customerId: string

  /**
   * 상점에서 만든 고유 주문번호입니다.
   * 영문 대소문자, 숫자와 특수문자 -, _만 사용할 수 있습니다
   *
   * @minLength 16
   * @maxLength 50
   */
  orderId: string

  /**
   * 구매자에게 표시할 주문 이름입니다. 상품을 등록하지 않아도 지정해야 합니다.
   *
   * @maxLength 100
   */
  orderName: string

  /**
   * 결제 금액입니다.
   */
  amount: {
    /** @minimum 0 */
    value: number
  }

  /**
   * 결제와 함께 저장할 1차원 키-값 객체입니다.
   * 최대 5개이며 JSON 직렬화 결과가 2,000자를 넘을 수 없습니다.
   */
  metadata?: Record<string, string | number | boolean | null>

  /**
   * 결제자 본인인증(KYC) 정보입니다.
   * 사전에 캔디페이와 협의한 가맹점만 사용할 수 있습니다.
   */
  kyc?: {
    name: string
    registNo: string
    phoneNumber?: string | null
  }

  /**
   * 결제수단 인증에 성공한 뒤 이동할 URL입니다.
   */
  successUrl: string

  /**
   * 결제수단 인증에 실패한 뒤 이동할 URL입니다.
   */
  failUrl: string
}

요청 예제

curl --request POST \
  --url https://api.candypay.co.kr/px/payfront/sessions \
  --user '{API_SECRET_KEY}:' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "p_1Gq3nudQxklUWpOUkj9",
    "orderId": "bUjILtZPrmCluBhMOiqCs",
    "orderName": "상담 서비스 이용료",
    "amount": {
      "value": 50000
    },
    "metadata": {
      "campaign": "summer"
    },
    "successUrl": "https://merchant.example/success",
    "failUrl": "https://merchant.example/fail"
  }'

Response

성공

HTTP 201 Created와 함께 결제 링크 응답 객체가 반환됩니다.

{
  "token": "kM0Qx9r2V7nP",
  "checkoutUrl": "https://payfront.candypay.co.kr/px/checkout?token=kM0Qx9r2V7nP",
  "expiresAt": "2026-09-21T01:23:45.678Z"
}

token으로 링크를 직접 조합하지 말고 응답의 checkoutUrl을 그대로 구매자에게 전달하세요.

실패

요청이 실패하면 HTTP 상태 코드와 함께 에러 객체를 받습니다. 코드별 의미는 에러 코드 문서를 참고하세요.

링크 유효기간과 재발급

결제 링크의 기본 유효기간은 생성 시점부터 7일입니다. 응답의 expiresAt을 기준으로 만료 여부를 확인하고, 만료된 링크는 전달하지 마세요.

같은 orderId로 세션을 다시 만드는 데 성공하면 이전 결제 링크는 즉시 무효화됩니다. 동일한 요청을 반복해도 같은 링크가 반환되는 것은 아닙니다. 세션 생성 요청을 자동으로 재시도하지 말고, 다시 생성한 경우에는 가장 최근에 생성된 checkoutUrl만 구매자에게 전달하세요.

이미 결제가 완료됐거나 결제자가 귀속된 주문 등은 재발급이 거절될 수 있습니다.

결제 결과 처리

결제 링크 생성은 결제 승인이 아닙니다. 구매자의 결제수단 인증이 성공하면 successUrl로 이동합니다. 상점 서버에서 전달받은 주문번호와 금액을 저장된 주문 정보와 대조한 뒤 결제 승인 API를 호출해야 결제가 완료됩니다.

리다이렉트 파라미터와 결과 처리 방법은 결제창 연동 가이드를 참고하세요.

링크 결제도 생성 요청의 orderId를 사용하고, 승인 후에는 동일한 결제 조회·취소 API와 결제 상태 변경 웹훅을 사용합니다. 문자·알림톡 등으로 링크를 전달하더라도 승인 처리와 웹훅 검증은 상점 서버에서 구현해야 합니다.