결제 서버연동breadcrumb승인

결제 승인 API 연동 가이드

사용자가 결제창에서 인증을 마치면, 이제는 결제를 완료할 차례예요.
이 때 호출하는 API가 결제 승인 API에요.

결제 승인 흐름은 아래와 같아요.

결제 서버 인증은 어떻게 하나요?
API 연동에 반드시 필요한 결제서버 인증 방식에 대해 궁금하다면,
결제서버 인증 가이드를 먼저 참고해주세요.


결제 승인 API란?

결제 승인 API는 결제 요청을 최종적으로 확정(승인)하기 위해 가맹점 서버가 호출하는 API예요.
다날 결제 승인까지의 연동 흐름을 정리하면 다음과 같아요.

  1. 사용자가 결제창에서 인증을 완료
  2. 가맹점의 successUrl로 인증 결과가 전달됨
  3. 전달받은 정보를 확인 후 결제 승인 API를 호출 → 결제 승인 완료

✅ 정리하면

  • 결제 승인은 인증 이후, 가맹점이 최종적으로 결제를 완료하는 단계예요.
  • 승인 API를 호출하기 전에 전달받은 결제 정보와 사용자 정보를 반드시 확인해 주세요.

API 정보

항목값
HTTP MethodPOST
Endpointhttps://one-api.danalpay.com/payments/confirm
인증 방식Basic Auth
요청 Formatapplication/json
응답 Formatapplication/json

요청 파라미터

휴대폰, 카드, 계좌이체, 가상계좌는 공통 요청 파라미터만 전송해요.
컬쳐랜드 상품권, 도서문화 상품권의 경우, 추가 파라미터가 요구돼요.

공통 파라미터

파라미터타입필수길이설명
methodstringO100 byte
사용자가 인증을 완료한 결제수단을 입력합니다.
결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 결제수단이 전달됩니다.
  • 휴대폰 : MOBILE
  • 카드 : CARD
  • 계좌이체 : TRANSFER
  • 가상계좌 : VACCOUNT
  • 컬쳐랜드상품권 : CULTURELAND
  • 도서문화상품권 : BOOK_AND_LIFE
transactionId(거래번호)와 method(결제수단)이 일치하지 않으면 취소에 실패합니다.
transactionIdstringO32 byte
다날에서 부여한 거래번호를 입력합니다.
사용자 인증이 완료된 거래에 대해 결제 승인 및 취소 처리를 위해 사용되는 고유값으로
결제창에서 인증 완료 시가맹점 성공 URL로 전달됩니다.
전달된 거래번호로 결제를 발생시키며, 다날과 함께 거래 관리를 위해 가맹점에서 저장해 두시는 것을 권장합니다.
orderIdstringO50 byte
고객 주문번호를 입력합니다.
고객 결제 건을 식별하기 위해 사용하는 거래별 고유값으로 SDK 호출시 생성했던 값을 넣어주세요.
중복되지 않게 생성하셔야 하며 저장 및 관리해주시기 바랍니다.(예: 년월일시-일련번호)
amountnumberO결제수단별 상이
결제 금액을 입력합니다.
SDK 호출시 입력한 금액을 넣어주세요.
앞서 안내한바와 같이 결제 수단마다 최소 및 최대 결제 가능 금액이 다르며,
입력한 금액이 해당 수단의 최소 금액 기준에 미달할 경우, 해당 결제 수단은 결제창에 노출되지 않습니다.
merchantIdstringO20 byte
계약 완료 후 발급 받은 CPID를 입력합니다.
다날 통합결제창, ONE API 결제 연동 시 사용되는 ID입니다.

결제수단별 추가 파라미터

파라미터타입필수길이설명
methodStringO사용자가 인증을 완료한 결제수단입니다.
결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 결제수단이 전달됩니다.
  • 휴대폰 : MOBILE
  • 카드 : CARD
  • 계좌이체 : TRANSFER
  • 가상계좌 : VACCOUNT
  • 컬쳐랜드상품권 : CULTURELAND
  • 도서문화상품권 : BOOK_AND_LIFE

거래번호와 결제수단이 일치하지 않으면 취소에 실패합니다.
transactionIdStringO32자
  • 인증이 완료된 거래번호입니다.
  • 결제창에서 사용자 인증이 완료되면 가맹점 성공 URL로 거래번호가 전달됩니다.
  • 전달된 거래번호로 결제를 발생시킵니다.
merchantIdStringO10자상점 아이디(계약 시 발급 받은 CPID를 입력해주세요.)
amountStringO9자
  • 상품 결제 금액입니다.
  • 처음 사용자 인증 시 요청한 금액과 일치해야 결제됩니다.
orderIdString50byte
  • 가맹점 측 주문번호 입니다.
  • 다날 측 거래ID로 관리하지 않고 가맹점 측 주문번호로 거래 관리하고자 할 때 주로 사용합니다.

* method와 transactionId는 반드시 1:1로 매칭되어야 하며, 일치하지 않으면 결제가 실패해요.

응답 파라미터

파라미터타입설명
codeString결제 요청 결과 응답 코드입니다. (예: SUCCESS — 결제 성공, 실패 시 에러 코드 제공)
messageString결제 요청 결과 응답 메시지입니다. 실패 시 가맹점 창에서 메시지를 노출 할 수 있습니다.
transactionIdStringDanal 고유 거래 ID 입니다. 거래ID로 거래를 구분합니다.

* 응답 code가 SUCCESS가 아닌 경우, message 값을 사용자 또는 관리자 화면에 출력할 수 있어요.

요청 예시

curl -X POST \
<https://one-api.danalpay.com/payments/confirm> \
-H "Authorization: Basic dGVzdF9jbGllbnRfa2V5Og==" \
-H "Content-Type: application/json" \
-d '{
      "method": "CARD",
      "transactionId": "202404290001234567890",
      "merchantId": "9810030930",
      "amount": "10000",
      "orderId": "ORDER-20240429-0001"
    }'

응답 예시

{
"code": "SUCCESS",
"message": "결제가 정상적으로 완료되었습니다.",
"transactionId": "202404290001234567890",
"orderId": "ORDER-20240429-0001"
}

주의사항

  • 테스트 환경과 실제 환경의 클라이언트 키는 다릅니다.
  • transactionId는 고유해야 합니다.
  • successUrl, failUrl 설정에 유의하세요.
  • 가상계좌 입금 통보를 위한 notiUrl이 필요합니다.

💡다음 단계: 결제 취소 요청

  • 결제가 정상적으로 승인된 이후에도, 사용자 요청이나 오류로 인해 결제 취소가 필요한 상황이 자주 발생해요.
  • 운영에 꼭 필요한 기능이니, 결제 취소 API 가이드를 확인하고 사전에 연동을 완료해 주세요.
← 이전 단계로 이동
맨 위로