Billing(자동결제)breadcrumb빌링키 발급

빌링키 발급

사용자가 Billing 등록창에서 인증을 성공하면, successUrl로 전달된 transactionId를 이용해 빌링키 발급 요청할 수 있어요.
인증 방식에 대한 자세한 내용은 [다날 개발자센터 인증 방식 가이드]를 참고해주세요.

API 정보

항목값
HTTP MethodPOST
Endpointhttps://one-api.danalpay.com/v1/billing/{paymentsMethod}/issue-key
인증 방식Basic Auth
Request Content-Typeapplication/json
Response Content-Typeapplication/json
* 현재 빌링키 발급을 지원하고 있는 결제수단(paymentsMethod)은 'CARD' 입니다.

요청 파라미터

파라미터타입필수최대길이설명
transactionIdstringO20 byte
다날 거래 ID
등록창에서 고객 인증 완료 시 수신한 거래 ID(transactionId)를 입력합니다.
merchantIdstringO20 byte
계약 완료 후 발급 받은 CPID를 입력합니다.

응답 파라미터

파라미터타입필수최대길이설명
codestringO
결과 코드
요청 처리 결과를 나타내는 코드입니다.
SUCCESS인 경우 정상적으로 빌링키가 발급되었음을 의미해요.
messagestringO
결과 메시지
요청 처리 결과에 대한 설명 메시지입니다.
transactionIdstring18 byte
거래 ID
다날에서 생성한 거래 식별 값으로, 결제취소를 위해 사용됩니다.
amountstring6 byte
결제 금액
가맹점이 요청한 금액입니다.
transactionDateTimestring14 byte
승인 일시
카드 인증이 승인된 일시를 나타냅니다.
형식은 yyyyMMddHHmmss 입니다.
authOnlyboolean
인증 사용 여부
카드 등록 요청 시 전달한 authOnly입니다.
true인 경우, 100원 결제 후 자동취소 됩니다.
userNamestring20 byte
고객이름
카드 등록 요청 시 전달한 고객이름입니다.
userPhoneNumberstring20 byte
고객 휴대폰번호
카드 등록 요청 시 전달한 고객 휴대폰번호입니다.
billingKeystring20 byte
빌링키
카드 정보를 대체하는 값으로,
이후 빌링 결제(정기결제, 자동결제), 빌링키 해지에 사용됩니다.
cardInfoobject20 byte
카드 정보
등록된 카드 정보로, authOnly=false일 때 응답으로 반환됩니다.
  • cardCode : 카드 코드
  • cardName : 카드사명
  • cardNumber : 카드번호(마스킹)
  • installmentMonth : 할부개월 수
  • approvalNumber : 카드 승인번호

요청 예시

curl -X POST \
    <https://one-api.danalpay.com/v1/billing/{paymentsMethod}/issue-key> \
    -H "Authorization: Basic dGVzdF9zZWNyZXRfa2V5Og==" \
    -H "Content-Type: application/json" \
    -d '{
      "transactionId": "202404290001234567890",
      "merchantId": "A010084434",
    }'

응답 예시

{
          "code": "SUCCESS",
          "message": "성공",
          "transactionId": "202404290001234567",
          "amount": "10000",
          "transactionDateTime": "20260101102315",
          "orderId": "ORDER-202601231-0001",
          "authOnly": false,
          "userName": "홍길동",
          "userPhoneNumber": "01012345678",
          "billingKey": "20260101102210DA789",
          "cardInfo": {
              "cardCode": "0907",
              "cardName": "BC카드",
              "cardNumber": "1234-****-****-5678",
              "installmentMonth": "00",
              "approvalNumber": "12345678"
          }
}

주의사항

  • 빌링키(billingkey)는 한 번 발급하면 계속 사용할 수 있지만, 사용자 정보가 변경되면 다시 등록해야 해요.
  • 발급된 빌링키(billingkey)는 이후 결제와 해지 등에 필요한 중요한 값이에요. 외부에 노출되지 않게 주의해주세요

💡다음 단계: 빌링키로 결제 승인

빌링키 발급이 완료되었다면, 발급된 빌링키로 실제 결제를 발생시킬 수 있어요.
이제 서버로 빌링키를 포함하여, [결제 승인 요청]을 보낼 차례예요.

← 이전 단계로 이동

맨 위로