자동결제(빌링)

자동결제는 다른 이름으로 빌링, 또는 정기결제로 불리는 결제 방식이에요. 구매자가 카드를 한 번만 등록하고 나면, 별도의 인증 없이 간편하게 결제를 요청할 수 있어요.

자동결제 내역을 조회하는 방법은 intentkey로 결제 조회와 동일해요.

빌링키 발급

Request

POST https://api.candypay.co.kr/px/billing/billkeys/issue
Content-Type: application/json

{
  "customerId": "string",
  "number": "string",
  "expirationYY": "string",
  "expirationMM": "string",
  "cvc": "string",
  "passwordFront2": "string",
  "ownerName": "string",
  "registNo": "string",
  "ownerPhoneNumber": "string"
}

customerId는 구매자를 식별하는 고유 아이디입니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
number에는 빌키를 발급할 카드번호를 입력해주세요.
expirationYY, expirationMM에는 카드 유효기간의 연도 뒤 두 자리와 월 두 자리를 입력해주세요.
ownerName에는 카드 소유자 성함을 정확하게 입력해주세요. 법인카드일 경우에는 회사명을 입력해주세요.
registNo에는 카드 소유자의 생년월일 6자리를 정확하게 입력해주세요. 법인카드일 경우에는 사업자번호 10자리를 입력해주세요.
ownerPhoneNumber에는 카드 소유자의 전화번호 11자리를 정확하게 입력해주세요. 법인카드일 경우에는 01000000000을 입력해주세요.

Response

성공

201 응답과 함께 생성된 빌키 정보가 내려갑니다.

{
  "billkey": "string"
}

실패

빌링키 발급에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

빌링키 삭제

Request

DELETE https://api.candypay.co.kr/px/billing/billkeys/{billkey}

billkey에는 캔디페이에서 발급한 폐기할 빌키를 정확히 입력해주세요.

Response

성공

200 응답과 함께 삭제된 빌키 정보가 내려갑니다.

{
  "billkey": "string"
}

실패

빌링키 삭제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

자동결제 승인

Request

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

{
  "customerId": "string"
  /**
   * 주문번호
   * 매 주문을 식별할 수 있는 unique한 값으로 설정해주세요
   * @minLength 16
   * @maxLength 50
   */
  "orderId": "string"
  /**
   * 주문명
   * @maxLength 100
   */
  "orderName": "string"
  "totalAmount": number
  /**
   * 결제금액 중 면세해당액
   * 캔디페이 운영팀과 협의 후 사용할 수 있습니다
   * @minimum 0
   * @default 0
   */
  "taxFreeAmount"?: number
  "instruments": {
    "billing": "string"
    "amount": number
    /**
     * 할부개월수
     * @minimum 0
     * @maximum 3
     * @default 0
     */
    "installmentPlanMonths"?: number
  }[]
}

customerId에는 빌링키 발급시 입력했던 customerId여야 해요. customerId가 일치하지 않으면 결제가 진행되지 않아요.
orderId는 해당 결제의 고유 주문번호를 입력해주세요. 직접 생성한 영어 대소문자, 숫자, 특수문자 -, _로 이루어진 16자 이상 50자 이하 문자열이어야 해요. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 해요. 결제상태가 변해도 orderId는 변하지 않아요.
orderName은 해당 결제의 주문 이름으로 상점이 직접 지정해줘야해요. 구매상품명으로 지정하는 것을 권장해요.
totalAmount는 해당 결제의 총 결제금액이에요.
taxFreeAmount는 총 결제금액 중 면세해당액이에요. 캔디페이 운영팀과 협의 후 사용할 수 있어요.
instruments는 분할결제를 진행할 결제수단들의 정보에요. 각 결제수단의 빌키, 금액, 할부 개월을 입력해주면 돼요. totalAmount와 각 결제수단의 amount를 합한 값이 일치하지 않을 경우 결제가 진행되지 않아요.
taxFreeAmount와 instruments[].installmentPlanMonths는 선택 사항이며 기본값은 0이에요. 할부 개월은 0부터 24까지 입력할 수 있고, 실제 이용 가능한 할부는 카드사와 가맹점 계약에 따라 달라져요.

Response

성공

자동결제에 성공하면 PaymentIntent 객체가 돌아옵니다. 필드에 값이 제대로 들어왔는지 확인하세요.

실패

결제 승인에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.