빌링키로 결제 승인

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

API 정보

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

* 현재 빌링 결제가 가능한 결제수단(paymentsMethod)은 'CARD' 입니다.

요청 파라미터

파라미터	타입	필수	최대길이	설명
method	string	O		사용자가 인증을 완료한 결제수단을 입력합니다. 결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 결제수단이 전달됩니다. 카드 : CARD
billingKey	string	O	50 byte	빌링키 발급요청을 통해 응답으로 받은 빌링키를 입력합니다.
userId	string	O	60 byte	고객 식별 키를 입력합니다. 일부 결제 수단의 원천사 설정에 따라 값이 잘릴 수 있으므로 20byte 이하 사용을 권장드립니다.
amount	number	O	결제수단별 상이	결제 금액을 입력합니다. 카드 : CARD (7자)
orderName	string	O	100 byte	승인될 상품명을 입력합니다.
orderId	string	O	50 byte	고객 주문번호를 입력합니다. 고객 결제 건을 식별하기 위해 사용하는 거래별 고유값을 넣어주세요. 중복되지 않게 생성하셔야 하며 저장 및 관리해주시기 바랍니다.(예: 년월일시-일련번호)

응답 파라미터

파라미터	타입	필수	최대길이	설명
code	string	O		결과 코드 요청 처리 결과를 나타내는 코드입니다. SUCCESS인 경우 정상적으로 빌링키가 발급되었음을 의미해요.
message	string	O		결과 메시지 요청 처리 결과에 대한 설명 메시지입니다.
transactionId	string		18 byte	거래 ID 다날에서 생성한 거래 식별 값으로, 결제취소를 위해 사용됩니다.
amount	string			결제 금액 가맹점이 요청한 금액입니다.
orderId	string		50 byte	가맹점 주문번호 카드 등록 요청 시 전달한 가맹점의 주문번호입니다.
transactionDateTime	string		14 byte	승인 일시 카드 인증이 승인된 일시를 나타냅니다. 형식은 yyyyMMddHHmmss 입니다.

요청 예시

curl -X POST \
https://one-api.danalpay.com/billing/confirm \
-H "Authorization: Basic dGVzdF9zZWNyZXRfa2V5Og==" \
-H "Content-Type: application/json" \
-d '{
  "method": "CARD",
  "billingKey": "20260101102210DA789",
  "userId": "user@example.com",
  "amount": 10000,
  "orderName": "정기결제 상품",
  "orderId": "ORDER-20260101-0001"
}'

응답 예시

{
  "code" : "SUCCESS",
  "message" : "성공",
  "transactionId" : "04290001234567890",
  "amount" : "10000",
  "transactionDateTime" : "20260101102315",
  "orderId" : "ORDER-20260101-0001"
}

💡다음 단계

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

← 이전 단계로 이동