코어 API

interface PaymentIntent {
  /**
   * @minLength 21
   * @maxLength 21
   * 결제의 키값입니다. 캔디페이에서 각 결제별로 자동으로 생성해주는 문자열입니다.
   * 각 결제를 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다.
   * 결제 상태가 변해도 값이 유지됩니다.
   * 결제 승인, 결제 조회, 결제 취소 API에 사용합니다.
   */
  intentKey: string
 
  /**
   * @minLength 16
   * @maxLength 50
   * 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 16자 이상 50자 이하의 문자열입니다.
   * 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다.
   * 결제 상태가 변해도 orderId는 유지됩니다.
   */
  orderId: string
 
  /**
   * @maxLength 100
   * @example '생수 외 1건'
   * 주문의 이름입니다. 가맹점이 직접 값을 지정해줘야 합니다. 구매상품으로 지정하는 것을 권장합니다.
   */
  orderName: string
 
  /**
   * 상점아이디(MID)입니다. 캔디페이에서 발급합니다.
   */
  mId: number
 
  /**
   * 총 결제 금액입니다. 결제가 취소되는 등 결제 상태가 변해도 최초에 결제된 결제 금액으로 유지됩니다
   */
  totalAmount: number
 
  /**
   * 작성중 FIXME
   */
  status: string
 
  /**
   * @pattern yyyy-MM-dd'T'HH:mm:ss±hh:mm
   * @example '2022-01-01T00:00:00+09:00'
   * 결제를 요청한 날짜와 시간 정보입니다. ISO 8601 형식입니다.
   */
  requestedAt: string
 
  /**
   * @pattern yyyy-MM-dd'T'HH:mm:ss±hh:mm
   * @example '2022-01-01T00:00:00+09:00'
   * 결제 승인이 일어난 날짜와 시간 정보입니다. ISO 8601 형식입니다.
   */
  approvedAt?: string
 
  /**
   * 결제가 취소된 상태면 이 필드에 값이 채워집니다.
   */
  cancel?: PaymentCancel
 
  methods: PaymentIntentMethod[]
 
  /**
   * 결제 요청 시 SDK에서 직접 추가할 수 있는 결제 관련 정보입니다. 최대 5개의 키-값(key-value) 쌍입니다.
   * JSON으로 직렬화했을 때 2000자를 넘을 수 없습니다.
   */
  metadata?: Jsonifiable
 
  /**
   * 발행된 영수증 정보입니다.
   */
  reciept?: {
    /**
     * 결제금액에 대한 캔디페이 통합 영수증입니다. 사용을 권장하지 않습니다.
     */
    candyUrl: string
    /**
     * 구매자에게 제공할 수 있는 결제수단별 영수증입니다. 카드 결제는 매출전표가 제공됩니다.
     */
    perMethodUrls: string[]
  }
 
  /**
   * 결제창 관련 정보입니다. 결제창 SDK에서 사용합니다.
   */
  checkout?: {
    /**
     * 결제창이 열리는 주소입니다.
     */
    url: string
  }
 
  /**
   * 결제가 실패 상태이면 (주로 승인 실패) 여기에 에러 객체를 담아 보내줍니다.
   */
  failure?: {
    code: string
    message: string
    detail?: string
  }
}
 
interface PaymentCancel {
  /**
   * @pattern yyyy-MM-dd'T'HH:mm:ss±hh:mm
   * @example '2022-01-01T00:00:00+09:00'
   * 결제 취소가 일어난 날짜와 시간 정보입니다. ISO 8601 형식입니다.
   */
  canceledAt?: string
}
 
interface PaymentIntentMethod {
  /**
   * 결제수단 종류입니다. 현재는 카드키인결제만 지원하므로 'KEYIN'만 반환합니다.
   */
  method: 'KEYIN'
 
  /**
   * 결제수단별 결제 금액입니다.
   */
  amount: number
 
  /**
   * 카드로 결제하면 제공되는 키인결제 관련 정보입니다.
   */
  keyin?: {
    /**
     * 카드번호입니다. 번호의 일부는 마스킹 되어 있습니다. 최대 길이는 20자입니다.
     */
    number: string
    /**
     * 할부 개월 수입니다. 일시불이면 0입니다.
     */
    installmentPlanMonths: number
    /**
     * 카드 발급사 두 자리 코드입니다. 기관 코드를 참고하세요.
     */
    issuerCode: string
  }
}

POST https://api.candypay.co.kr/px/intents/confirm
Content-Type: application/json
 
{
  "intentKey": "string",
  "orderId": "string",
  "amount": 10000
}

GET https://api.candypay.co.kr/px/intents/{intentKey}

POST https://api.candypay.co.kr/px/intents/{intentKey}/cancel
Content-Type: application/json
 
{
  "cancelReason": "string (maxLength: 200)"
}