결제 서버연동breadcrumb가상계좌 NotiUrl 연동

가상계좌 NotiUrl 연동

가맹점 서버가 가상계좌 입금 결과를 안전하게 수신할 수 있도록, NotiUrl 설정 방법과 연동 절차를 안내해요.

NotiUrl이란?

가상계좌 입금이 완료되었을 때 서버 간(Server to Server)로 통보하기 위한 콜백 URL입니다.
사용자 브라우저를 거치지 않고, 다날 → 가맹점 서버로 바로 전송되므로 신뢰성을 보장할 수 있습니다.

  • 사용자가 발급 받은 계좌번호에 입금시 NotiUrl로 입금결과가 통보 됩니다.
  • 다날에서 NotiUrl을 호출하여 넘겨준 결과값을 통해 가맹점은 결제 성공/실패 처리를 합니다.
  • NotiUrl로 받은 orderId, amount 등 결제 거래내용에 대한 검증을 반드시 해야 합니다.

방화벽 설정

  • 150.242.132.116

Noti를 수신하는 가맹점의 서버에서 위 IP의 요청이 허용되어있어야 다날의 서버로부터 가맹점의 NotiUrl로 정상적인 인바운드 요청이 전송됩니다.

요청 정보

항목값
HTTP MethodPOST
Endpoint가상계좌 입금 결과 알림을 받기 위해 가맹점이 등록한 URL
(입금 결과는 가맹점의 NotiUrl에 POST 방식으로 전달됩니다.)
Content-Typeapplication/json

요청 파라미터

파라미터타입필수최대길이설명
codestringO-
응답 코드를 나타냅니다.
요청 처리 결과를 나타내는 코드 값입니다.
messagestringO255 byte
응답 메시지를 나타냅니다.
요청 결과에 대한 상세 메시지 또는 오류 설명이 포함됩니다.
transactionIdstringO24 byte
거래 ID(TID)를 나타냅니다.
결제 건을 식별하기 위한 다날의 고유 거래 식별자입니다.
orderIdstringO255 byte
가맹점 주문번호를 나타냅니다.
가맹점에서 생성한 주문 고유 식별값입니다.
amountstringO9 byte
금액을 나타냅니다.
결제 또는 입금된 금액(숫자형 문자열)입니다.
depositDateTimestring14 byte
입금처리 일시를 나타냅니다.
YYYYMMDDHHMMSS 형식으로 입금이 처리된 시각을 표시합니다.
virtualAccountNumberstring16 byte
가상계좌 번호를 나타냅니다.
입금 시 사용된 가상계좌 번호입니다.
accountHolderstring10 byte
가맹점 명(예금주 명)을 나타냅니다.
가상계좌 예금주명으로 설정된 가맹점 명칭입니다.
depositorNamestring10 byte
입금의뢰인 명을 나타냅니다.
실제 입금자(입금 의뢰인)의 이름입니다.
userIdstring128 byte
가맹점 사용자 ID를 나타냅니다.
가맹점 내부에서 결제 요청한 사용자의 식별 키입니다.
userEmailstring128 byte
가맹점 사용자 이메일을 나타냅니다.
결제 결과 안내 등 메일 발송 시 사용되는 이메일 주소입니다.
orderNamestring255 byte
상품명을 나타냅니다.
결제 대상 상품 또는 서비스의 이름입니다.
expireDateTimestring14 byte
입금 마감 일시를 나타냅니다.
YYYYMMDDHHMMSS 형식으로 입금 가능 마감 시간을 표시합니다.
bankCodestring3 byte
은행 코드를 나타냅니다.
입금 계좌의 은행을 구분하는 코드입니다.
bankNamestring20 byte
은행 명을 나타냅니다.
입금 계좌의 은행 이름입니다.
useCashReceiptstring1 byte
현금영수증 발급 신청 여부를 나타냅니다.
Y: 발급, N: 미발급

요청 예시

{
    "code" : "SUCCESS",
    "message" : "성공",
    "transactionId" : "202510010000123456784578",
    "orderId" : "Order_2025100101",
    "depositDateTime" : "20251002093059",
    "virtualAccountNumber" : "5659874134865135",
    "accountHolder" : "(주)다날",
    "depositorName" : "입금자명",
    "userId" : "test123",
    "userEmail" : "test123@danal.co.kr",
    "orderName" : "상품명",
    "expireDateTime" : "20251002235959",
    "bankCode" : "001",
    "bankName" : "은행명",
    "useCashReceipt" : "Y",
  }

응답 파라미터

파라미터타입필수최대길이설명
codestringO-
응답 코드를 나타냅니다.
요청에대한 응답을 나타내는 코드 값입니다.

응답 예시

{
    "code" : "SUCCESS"
  }

주의 사항

  • 사용자가 발급 받은 계좌번호에 입금 시 NotiUrl로 입금 결과가 통보됩니다.
  • 다날에서 NotiUrl을 호출하여 넘겨준 결과값을 통해 가맹점은 결제 성공/실패 처리를합니다.
  • NotiUrl로 받은 orderId, amount 등 결제 거래내용에 대한 검증을 반드시 해야합니다.
  • 인코딩 방식은 EUC-KR 형식을 기본으로 합니다.

  • 가맹점은 요청에 대한 응답으로 아래와 같이 반환을 해주셔야 합니다.

    • 가맹점 노티 수신 성공 시 → HttpStatus 200, { "code": "SUCCESS" }
    • "SUCCESS" 를 받을 때까지 10분 동안 1분 간격으로 노티를 재전송합니다.
      가맹점 노티 재시도를 원하지 않을 경우 → HttpStatus 200, { "code": "FAIL" }
  • 가맹점은 전달받은 값(transactionId 또는 orderId)의 중복 여부를 반드시 확인한 후 성공/실패 처리를 해야 합니다.
  • 사용자 입금 후 약 5분 뒤 다날에서 가맹점 측으로 입금 정보 노티가 발송됩니다.

  • notiUrl에는 특수문자 (
    & ' " \ < > \n \r\n , +
    ) 사용을 금지합니다.

맨 위로