Billing(자동결제)breadcrumb등록창 호출

등록창 호출 가이드

Billing 서비스가 생소하다면 [Billing 서비스]를 먼저 읽어보시면 좋아요
등록창 호출하기에 앞서, [SDK 연동 가이드]를 먼저 진행해주세요

등록창 호출

SDK 연동이 끝났다면, danalPayments 객체에서 .requestBilling() 함수를 호출하면 Billing 등록창이 열리고, 서비스 이용을 위한 사용자 인증과 함께 Billing 등록이 시작돼요.
.requestBilling 함수의 파라미터는 아래 표를 참고해주세요.

요청 파라미터

결제 요청 시 본문은 아래 두 영역으로 구성되어있어요.

  • 공통 파라미터: 모든 결제수단에서 공통으로 사용되는 필수 항목
  • 결제수단별 추가 파라미터: 각 결제수단에서 요구하는 별도 항목

공통 파라미터

파라미터타입필수최대길이설명
amountnumberO10자
결제 금액을 입력합니다.
orderNamestringO100 byte
결제 상품명을 입력합니다.
일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 80byte 이하 사용을 권장드립니다.
orderIdstringO50 byte
고객 주문번호를 입력합니다.
고객 결제 건을 식별하기 위해 사용하는 거래별 고유값으로 반드시 중복되지 않도록 생성하여
저장 및 관리해주시기 바랍니다.(예: 년월일시-일련번호)
userIdstringO60 byte
고객 식별 키를 입력합니다.
일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 20byte 이하 사용을 권장드립니다.
successUrlstringO200 byte
결제 성공 후 이동 URL을 입력합니다.
반드시 HTTPS 주소로 입력해야 하며, 외부 접근이 가능한 페이지를 지정해주시기 바랍니다.
failUrlstringO200 byte
결제 실패 또는 사용자가 결제를 취소했을 때 이동할 URL을 입력합니다.
실패 사유 안내를 포함한 가맹점 전용 안내 페이지로 연결해주시기 바랍니다.
merchantIdstringO20 byte
계약 완료 후 발급 받은 CPID를 입력합니다.
다날 통합결제창, ONE API 결제 연동 시 사용되는 ID입니다.
userEmailstring64 byte
결제 완료 후 결과 안내 메일을 수신 받을 이메일 주소를 입력합니다.
사용자 이메일, 결제 완료 후 결제 결과에 대한 메일을 발송 하기 위해 사용됩니다.
userNamestring20 byte
결제 완료 후 표기되는 사용자 이름을 입력합니다.
가상 계좌: 입금 완료 시 사용자에게 발송되는 메일에 표기되는 이름입니다.
카드: 매출 전표에 표기되는 이름입니다.
userPhoneNumberstring11 byte
결제자 휴대폰 번호를 입력합니다.
빌링 등록창의 입력필드에서 기본값으로 사용됩니다.
숫자만 입력하며 하이픈(-)은 제외합니다.
예: "01012345678"
hideAmountboolean
카드 등록 화면에서 결제 금액 노출 여부를 설정합니다.
  • true : 결제 금액 미노출(default)
  • false : 결제 금액 노출

hideAmount=true는 authOnly=true일 때만 사용할 수 있습니다.
titlestring
정기결제 등록 화면 상단 문구 타입을 설정합니다.
  • '00' : 정기결제를 등록합니다 (기본 값)
  • '01' : 간편결제를 등록합니다
  • '02' : 자동결제를 등록합니다

미지정 시 기본 문구('00')가 노출됩니다.

결제수단별 추가 파라미터

파라미터타입필수최대길이설명
paymentsMethodstringO20 byte
카드 등록창을 열기 위한 결제 수단 코드로 CARD를 입력합니다.
카드 등록창을 호출하면, 고객이 등록창 내에서 카드정보를 입력하고 필요에 따라 본인인증을 진행합니다.
offerPeriodstring
혜택 또는 결제 조건 기간을 입력합니다.
서비스 제공 기간이나 자동결제 조건 등을 사용자에게 안내하기 위한 문자열입니다.
예:
  • "2026.12.01 - 2027.12.31"
  • "30일 무료 체험 후 자동결제"
  • "익월 10일 자동결제"
authOnlyboolean
카드 등록과 동시에 인증(결제) 수행 여부를 설정합니다.
  • true : 인증(결제) 후 카드 등록
    (100원 결제 후 자동취소)

  • false : 인증(결제) 없이 카드 등록 (default)
cardOwnerobject
카드 소유주 정보입니다.
카드 등록창의 입력필드에서 기본값으로 사용됩니다.
카드 소유주 유형에 따라 입력 형식이 아래와 같이 달라집니다.
  • type : 카드 소유주 유형
    • PERSONAL : 개인카드
    • BUSINESS : 법인카드
  • value : 카드 소유주 식별 값
    • PERSONAL : 주민등록번호 앞 6자리
    • BUSINESS : 사업자등록번호 10자리

카드 Billing 등록창을 열기위해 호출하는 함수의예시 코드는 아래와 같아요.

const danalPayments = DanalPayments("CL_TEST_I4d8FWYSSKl-42F7y3o9g_7iexSCyHbL8qthpZxPnpY=");
const baseParams = {
  orderName: '상품명',
  amount: 10000,
  merchantId: 'A010084434',
  orderId: '123123',
  userId: 'user@example.com',
  successUrl: 'https://successUrl.com',
  failUrl: 'https://failUrl.com',
};

danalPayments.requestBilling({
  ...baseParams,
  paymentsMethod: 'CARD',
  "title": "01",
  "offerPeriod": "2026.12.31 ~ 2027.12.31",
  "userPhoneNumber": "01012341234",
  "cardOwner": {
    "type": "BUSINESS",
    "value": "1230012345"
  }
});

인증 결과 처리

사용자가 카드 등록창에서 카드 등록을 완료하면, 카드 등록창을 호출한 시점에 전달한 successUrl 또는 failUrl로 인증 결과값을 전달해요.
successUrl로 전달된 인증 결과값은 빌링키 발급에 필요한 값이에요

결제창은 사용자의 User-Agent를 기준으로 모바일/PC 환경을 구분하며,

  • 모바일 환경일 때는 GET 방식
  • PC 환경일 때는 POST 방식

사용자 브라우저에서 가맹점 서버로 직접 전송(form submit)돼요.

전송되는 정보는 아래 예시 코드를 참고해주세요.

{
  "code": "SUCCESS",
  "message": "성공",
  "transactionId": "202504290001234567890",
  "orderId": "ORDER-20250429-0001",
  "method": "CARD",
  "amount": 10000,
}

주의사항

  • 카드 등록 및 Billing 서비스는 테스트 환경과 실제 환경의 설정값이 다르므로, 실제 서비스 적용 시 반드시 운영용 설정값을 사용해야 합니다.
  • authOnly=true로 설정할 경우, 카드 등록과 동시에 100원 결제(인증)이 수행되므로, 실제 결제가 발생 후 취소됨을 유의해야 합니다.
  • hideAmount=true 설정은 authOnly=true인 경우에만 사용할 수 있으며, 결제 금액이 사용자에게 노출되지 않습니다.
  • 카드 소유주 정보(cardOwner)는 카드 유형에 맞는 형식으로 정확히 입력해야 하며, 형식이 맞지 않을 경우 카드 등록이 실패할 수 있습니다.

💡다음 단계: 빌링키 발급

  • 결제 진행을 위한 인증이 성공했다면, 이제 서버로 빌링키 [발급 요청]을 보낼 차례예요.
  • 서버로 요청을 보낼 때는 정상적인 인증과 처리를 위해 요청 헤더를 반드시 포함해야 해요.
  • 자세한 내용은 요청 [헤더 설정 가이드]를 확인해 주세요.
맨 위로