빌링키로 결제 승인

빌링키 발급 후, 발급된 빌링키를 이용해 정기결제(자동결제)를 진행합니다.
인증 방식에 대한 자세한 내용은 [다날 개발자센터 인증 방식 가이드]를 참고해주세요.

API 정보

항목	값
HTTP Method	POST
Endpoint	https://one-api.danalpay.com/billing/confirm
인증 방식	Basic Auth
Request Content-Type	application/json
Response Content-Type	application/json

요청 파라미터

파라미터	타입	필수	최대길이	설명
method	string	O		사용자가 인증을 완료한 결제수단을 입력합니다. 결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 결제수단이 전달됩니다. 카드 : CARD 휴대폰 : MOBILE
billingKey	string	O	50 byte	빌링키 발급요청을 통해 응답으로 받은 빌링키를 입력합니다.
userId	string	O	60 byte	고객 식별 키를 입력합니다. 일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 20byte 이하 사용을 권장드립니다.
amount	number	O	결제수단별 상이	결제 금액을 입력합니다. 카드 : CARD (7자) 휴대폰 : MOBILE (7자) — 전월 거래와 동일한 금액이어야 합니다.
orderName	string	O	100 byte	승인될 상품명을 입력합니다.
merchantId	string	O	20 byte	계약 완료 후 발급 받은 CPID를 입력합니다. 다날 통합결제창, ONE API 결제 연동 시 사용되는 ID입니다.
orderId	string	O	50 byte	고객 주문번호를 입력합니다. 고객 결제 건을 식별하기 위해 사용하는 거래별 고유값을 넣어주세요. 중복되지 않게 생성하셔야 하며 저장 및 관리해주시기 바랍니다.(예: 년월일시-일련번호)
lastTransactionId	string	△	24 byte	전월 거래 ID입니다. 휴대폰(MOBILE) 결제 시 필수입니다. 직전 정기결제(또는 1회차 등록)에서 응답받은 transactionId를 입력합니다. 휴대폰 Billing 결제는 전월 거래 기준 ±5일 이내에 동일 금액으로 요청해야만 승인이 가능합니다. 이 조건을 충족하지 않으면 결제 승인이 거절됩니다.
itemCode	string	△	10 byte	결제 대상 상품 코드입니다. 휴대폰(MOBILE) 결제 시 필수입니다. 계약 시 발급된 서비스 연동 정보 안내 메일에 기재된 상품코드를 입력합니다.

응답 파라미터

파라미터	타입	필수	최대길이	설명
code	string	O		결과 코드 요청 처리 결과를 나타내는 코드입니다. SUCCESS인 경우 정상적으로 빌링키가 발급되었음을 의미해요.
message	string	O		결과 메시지 요청 처리 결과에 대한 설명 메시지입니다.
transactionId	string		18 byte	거래 ID 다날에서 생성한 거래 식별 값으로, 결제취소 API의 요청 파라미터인 transactionId의 값으로 사용됩니다. 또한 휴대폰 결제의 경우 다음 달 정기결제의 lastTransactionId파라미터의 값으로도 사용되므로 반드시 저장해야 합니다.
amount	string			결제 금액 가맹점이 요청한 금액입니다.
orderId	string		50 byte	가맹점 주문번호 등록 요청 시 전달한 가맹점의 주문번호입니다.
transactionDateTime	string		14 byte	승인 일시 카드 인증이 승인된 일시를 나타냅니다. 형식은 yyyyMMddHHmmss 입니다.
userPhoneNumber	string			암호화된 고객 휴대폰번호 휴대폰(MOBILE) 결제 시에만 반환됩니다.
carrier	string		3 byte	통신사 코드 휴대폰(MOBILE) 결제 시에만 반환됩니다. (예: SKT, KTF, LGT)

요청 예시

curl -X POST \
https://one-api.danalpay.com/billing/confirm \
-H "Authorization: Basic dGVzdF9zZWNyZXRfa2V5Og==" \
-H "Content-Type: application/json" \
-d '{
  "method": "MOBILE",
  "merchantId": "A010084434",
  "billingKey": "20250101102210DA789",
  "userId": "danari1997",
  "amount": 10000,
  "orderName": "이모티콘 플러스",
  "orderId": "ORDER-20260101-0001",
  "lastTransactionId": "032509305165869422",
  "itemCode": "1270000000"
}'

응답 예시

{
  "code" : "SUCCESS",
  "message" : "성공",
  "transactionId" : "04290001234567890",
  "amount" : "10000",
  "transactionDateTime" : "20260101102315",
  "orderId" : "ORDER-20260101-0001",
  "phoneNumber" : "2Aa0e8TvOQ7cls+PUib9lQ==",
  "carrier" : "KTF"
}

휴대폰 Billing 주의사항

휴대폰 정기결제는 전월에 발생한 거래를 기준으로 결제가 진행됩니다. 전월 거래의 transactionId를 lastTransactionId로 반드시 전달해야 합니다.
결제 금액은 전월 거래와 동일해야 하며, 거래일자는 전월 거래일 기준 ±5일 이내이어야 합니다.
이 API의 응답으로 받은 transactionId는 결제취소 시 원거래 ID로 사용되며, 휴대폰 결제의 경우 다음 달 정기결제의 lastTransactionId로도 사용되므로 반드시 저장하세요.

다음 단계

결제가 정상적으로 승인된 이후에도, 사용자 요청이나 오류로 인해 결제 취소가 필요한 상황이 자주 발생해요.
운영에 꼭 필요한 기능이니, [결제 취소 API 가이드]를 확인하고 사전에 연동을 완료해 주세요.
(빌링키로 발생한 결제 취소의 경우도 일반 결제 취소와 동일한 API를 사용하면 돼요.)
고객의 구독/정기결제 취소가 발생했을 경우, 빌링 서비스 해지를 위해 [빌링 서비스 해지 가이드]를 확인하고 사전에 연동을 완료해 주세요.

← 이전 단계로 이동