결제 서버연동breadcrumb승인

결제 승인 API 연동 가이드

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

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

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


결제 승인 API란?

결제 승인 API는 결제 요청을 확정(승인)하기 위해 가맹점 서버가 호출하는 API예요.
다날 결제 승인까지의 연동 흐름을 정리하면, 아래와 같아요.

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

즉, 인증은 사용자 확인 단계, 결제 승인은 최종적으로 결제를 완료하는 단계예요.

API 정보

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

요청 파라미터

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

파라미터타입필수길이설명
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": "M123456",
      "amount": "10000",
      "orderId": "ORDER-20240429-0001"
    }'

응답 예시

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

주의사항

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