Skip to Content
가이드서버에서 이용하기

서버에서 이용하기

상점 서버에서 결제 세션을 만들고, 응답으로 받은 결제 링크를 구매자에게 전달하는 방법이에요.

구매자가 웹 주문서의 결제 버튼을 누르는 일반적인 결제에는 Web SDK 연동을 사용하세요. 이 방식은 앱 푸시, 문자, 메신저처럼 상점이 관리하는 채널로 결제 링크를 보내야 할 때 유용합니다.

1. 결제 세션 만들기

상점 서버에서 POST https://api.candypay.co.kr/px/payfront/sessions를 호출하세요. 브라우저나 앱에 노출하면 안 되는 시크릿 키로 요청을 인증합니다.

시크릿 키 뒤에 :을 붙인 값을 Base64로 인코딩하고 Basic 인증 헤더에 넣으세요. 자세한 내용은 API 키 문서를 참고하세요.

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

아래 예시처럼 결제 정보를 JSON 요청 본문으로 전달합니다. customerId에는 이메일, 전화번호, 자동 증가 번호처럼 추측할 수 있는 값을 사용하지 말고 UUID처럼 충분히 무작위적인 상점의 고객 ID를 사용하세요.

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": "캔디 사탕 외 2건",
    "amount": {
      "value": 50000
    },
    "metadata": {
      "campaign": "summer"
    },
    "successUrl": "https://merchant.example/success",
    "failUrl": "https://merchant.example/fail"
  }'

요청 필드

interface CreatePaymentSessionBody {
  /**
   * 구매자를 식별하는 추측 불가능한 상점 고객 ID입니다.
   * 이메일, 전화번호, 자동 증가 번호처럼 유추할 수 있는 값을 사용하면 안 됩니다.
   *
   * @minLength 2
   * @maxLength 50
   * @pattern ^[a-zA-Z0-9-_=\.@]{2,50}$
   */
  customerId: string
 
  /**
   * 상점에서 만든 고유 주문번호입니다.
   * 영문 대소문자, 숫자와 특수문자 -, _만 사용할 수 있습니다
   *
   * @minLength 16
   * @maxLength 50
   */
  orderId: string
 
  /**
   * 구매 상품을 나타내는 주문 이름입니다.
   *
   * @maxLength 100
   */
  orderName: string
 
  /**
   * 결제 금액입니다.
   */
  amount: {
    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
}

2. 결제 링크 전달하기

세션이 만들어지면 HTTP 201 Created와 함께 다음 응답을 받습니다.

{
  "token": "kM0Qx9r2V7nP",
  "checkoutUrl": "https://payfront.candypay.co.kr/px/checkout?token=kM0Qx9r2V7nP",
  "expiresAt": "2026-08-04T01:23:45.678Z"
}
  • checkoutUrl은 구매자가 열 결제 링크입니다. 상점의 앱 푸시, 문자 또는 메시지로 이 값을 그대로 전달하세요.
  • expiresAt은 링크가 만료되는 ISO 8601 시각입니다. 만료된 링크는 전달하지 마세요.
  • token은 세션 식별자입니다. 링크를 직접 조합하지 말고 응답의 checkoutUrl을 사용하세요.

같은 orderId로 세션을 다시 만들면 이전 결제 링크는 즉시 무효화됩니다. 세션 생성 요청을 자동으로 재시도하지 말고, 다시 생성한 경우에는 가장 최근 응답의 checkoutUrl만 구매자에게 전달하세요.

이후 리다이렉트 결과 처리와 결제 승인은 결제창 연동 가이드에서 이어서 확인하세요.

오류 응답

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

Last updated on
결제창 연동하기