결제 위젯

무통장입금 주문을 받은 뒤 구매자에게 입금할 계좌·금액·보내는 분 이름을 보여 주고, 입금이 확인되면 화면이 바로 바뀌는 안내 페이지입니다. 가맹점은 화면을 만들 필요 없이 주문 응답의 widget_url 로 구매자를 보내거나, 스크립트 한 줄로 쇼핑몰 화면 위에 띄우기만 하면 됩니다.

#언제 쓰나

• 주문 완료 페이지에 계좌 안내를 직접 만들기 번거로울 때
• 구매자가 "입금했는데 확인됐나요?"를 묻지 않게, 확인 결과를 바로 보여 주고 싶을 때
• 문자·메신저로 입금 안내 링크를 보내고 싶을 때

#켜기

1. 콘솔 → 결제 위젯 에서 사용을 켜고 저장합니다. (관리자 이상)
2. 강조색, 화면 테마, 입금자명 안내, 남은 시간 표시, 완료·문의 버튼을 정합니다. 오른쪽 미리보기에 바로 반영됩니다.
3. 쇼핑몰 화면 위에 띄우려면 허용 도메인에 쇼핑몰 주소를 넣습니다(임베드).
4. 테스트 모드에서 테스트 주문으로 위젯 열기를 눌러 실제 화면을 확인합니다.

설정은 조직 하나에 하나이고, 변경 전후는 감사 로그에 남습니다.

#화면 테마

• 강조색은 두 테마에 똑같이 쓰입니다. 버튼 글자색(검정·흰색)은 강조색과의 대비로 정해지고, 강조색이 바탕과 거의 같으면(예: 다크 테마에 검정) 버튼에 경계선이 생깁니다.
• 임베드 창의 바탕·닫기 바도 같은 테마를 따릅니다.
• 콘솔 미리보기에서 '시스템'은 지금 콘솔을 보는 기기의 설정으로 보입니다.

#widget_url

주문 등록·조회·취소·목록 응답의 주문 객체에 widget_url 이 실립니다.

{
  "id": "5f0c9a52-7d1e-4a8b-9c3f-2b6e8d4a1c07",
  "order_number": "ORD-1042",
  "status": "pending",
  "widget_url": "https://www.autotranspay.com/pay/atpw_XwyaUn0eSouc…"
}

• 구매자를 이 주소로 이동시키거나(주문 완료 직후 리다이렉트), 링크로 보내세요.
• 같은 주문을 다시 등록(멱등)하거나 조회하면 늘 같은 주소가 나옵니다.
• 아래 경우에는 null 입니다. 필드는 항상 있고 값만 비어 있습니다.
  • 위젯이 꺼져 있음
  • 운영 모드인데 유료 요금제가 아님
  • 운영 모드인데 보여 줄 수 있는 계좌가 없음 (안전 규칙) — 증명된 계좌가 여러 개인데 콘솔에서 안내 계좌를 고르지 않은 경우도 여기에 들어갑니다
  • 주문을 만든 지 30일이 지남 (테스트 모드는 24시간)

MCP로 연동 중이면 create_order·get_order·list_orders·cancel_order 결과에도 같은 widget_url 이 실립니다. get_account 의 widget 에서 위젯이 켜져 있는지(enabled), 운영 주문에 링크가 나갈 수 있는지(live_ready — 유료 요금제이고 안전 규칙의 계좌를 고를 수 있음), 허용 도메인(allowed_origins), 화면 테마(theme)와 삽입 스크립트 주소(embed_script)를 볼 수 있습니다. 허용 도메인은 콘솔에서 사람이 바꿉니다.

#세 화면

• 화면은 열려 있는 동안 몇 초 간격으로 상태를 확인하고, 은행 앱에서 돌아오는 순간 바로 한 번 더 확인합니다.
• 기한이 지난 뒤에도 입금이 확인될 수 있습니다(기한 직전 송금, 판매자의 직접 확인). 만료 화면은 30분 동안 계속 확인하고 그 뒤에는 화면으로 돌아올 때 확인하며, 확인되면 '입금이 확인됐어요'로 바뀝니다. 입금 확인 뒤 가맹점 서버가 웹훅 첫 전송을 거절해 주문이 취소되면 '취소된 주문이에요'로 바뀝니다.
• 남은 시간은 주문에 expires_at 이 있을 때만 보입니다. 주문 등록 때 expires_at 을 보내지 않으면 조직의 주문 기본 만료로 정해지고, 둘 다 없으면 보이지 않습니다.
• 자동확정이면 '입금 알림을 받고 N초 만에 확인했어요'처럼 실제로 걸린 시간(서버가 입금을 기록한 때부터 확정까지)만 보여 줍니다. 입금이 주문보다 먼저 들어온 경우는 보여 주지 않고, 고정된 홍보 수치는 쓰지 않습니다.
• 완료 버튼 주소는 https:// 만, 문의 버튼 주소는 https:// 또는 tel: 만 저장할 수 있습니다.
• 화면 아래에 '입금 확인: 오토페이'와 문제 신고 연락처가 표시됩니다.

#쇼핑몰 화면에 띄우기 (임베드)

구매자를 다른 주소로 보내지 않고 쇼핑몰 화면 위에 위젯을 띄울 수 있습니다. 데스크톱은 가운데 창, 휴대폰(640px 미만)은 아래에서 올라오는 시트로 열립니다.

1. 콘솔 → 결제 위젯 → 허용 도메인에 위젯을 띄울 쇼핑몰 주소를 넣고 저장합니다. (관리자 이상, 감사 로그에 남음)
2. 주문 완료 화면에 스크립트를 넣고, 주문 등록 응답의 widget_url 로 엽니다.

<script src="https://www.autotranspay.com/widget/v1.js"></script>
<script>
  // widgetUrl = 주문 등록 응답의 widget_url (서버에서 받아 화면에 넘긴 값)
  AutoTransPay.open(widgetUrl, {
    onState: function (state) {
      // 'pending' · 'completed' · 'expired' · 'closed' · 'unavailable' — 화면 표시용
    },
    onClose: function (reason) {
      // 'user'(닫기·Esc·바깥 클릭) · 'completed'(입금 확인 화면의 완료 버튼) · 'fallback'
    },
  });
</script>

허용 도메인

• https://shop.example.com 처럼 경로 없는 https 주소(origin)만, 최대 5개입니다. 저장할 때 소문자·기본 포트 생략으로 정리됩니다.
• 정확히 같은 주소만 허용됩니다. https://www.shop.example.com 이나 하위 도메인은 따로 넣어야 하고, https://shop.example.com.evil.com 같은 비슷한 이름은 다른 주소입니다. 경로·쿼리·user@ 가 섞인 주소, http:// 는 저장되지 않습니다.
• 위젯 화면은 허용 도메인의 화면에서만 iframe 으로 열립니다(CSP frame-ancestors). 허용 도메인이 비어 있으면 어디에서도 띄울 수 없습니다.
• 테스트 주문은 설정과 관계없이 http://localhost·http://127.0.0.1(포트 무관)에서도 띄울 수 있습니다.
• 허용 도메인이 아닌 화면에서 open 을 부르면 화면이 막혀 4초 안에 응답이 없으므로, 창을 닫고 새 창으로 엽니다(팝업이 막히면 그 주소로 이동). 이때 onClose('fallback') 이 불립니다.

동작

• 위젯 화면은 우리 도메인(www.autotranspay.com) iframe 안에서 그대로 돌아가고, 계좌번호 복사도 됩니다.
• 위젯은 쇼핑몰 화면에 ready·state·close 메시지만 보내며, 허용 도메인으로 확인된 주소에만 보냅니다. 스크립트는 우리 도메인의 그 iframe 에서 온 메시지만 받습니다. ready 에 실린 화면 테마로 창의 바탕·닫기 바 색을 맞춥니다(그 전에는 밝은 바탕).
• 임베드에서는 위젯 안에서 다른 사이트로 이동하지 않습니다. 입금 확인 화면의 완료 버튼은 창을 닫고 onClose('completed') 를 부르며(이동은 쇼핑몰 화면이 정합니다), 문의 버튼은 새 탭으로 엽니다.
• 닫기 버튼·Esc·바깥 클릭으로 닫히고, 열려 있는 동안 뒤 화면 스크롤과 포커스가 위젯에 묶입니다.
• 스크립트는 다른 라이브러리를 쓰지 않고 방문 통계·추적도 하지 않습니다.

#완료 버튼 주소 (return_url)

주문마다 입금 확인 화면의 완료 버튼이 갈 주소를 정할 수 있습니다. 정하지 않으면 콘솔에 저장한 완료 버튼 주소를 씁니다.

{
  "order_number": "ORD-1042",
  "amount": 43500,
  "depositor_name": "홍길동",
  "widget": { "return_url": "https://shop.example.com/orders/ORD-1042" }
}

• https:// 주소이고 그 origin 이 허용 도메인에 있어야 합니다. 아니면 400 return_url_not_allowed(param: widget.return_url)로 주문 등록이 거절됩니다. 테스트 주문은 http://localhost·http://127.0.0.1 주소도 됩니다.
• 주문에 저장된 값만 쓰고 화면 주소의 쿼리로는 바꿀 수 없습니다. 나중에 그 도메인을 허용 도메인에서 지우면 버튼은 설정의 주소로 돌아갑니다.
• 같은 주문을 다시 등록(멱등)해도 처음 저장한 값이 남습니다. 주문 응답에는 싣지 않습니다.
• 테스트 화면의 완료 버튼은 이동하지 않습니다(임베드에서 창 닫기는 됩니다).

#입금자명 알리기

구매자가 주문서와 다른 이름(예: 가족 명의)으로 입금해서 자동 확인이 안 될 때, 위젯의 '입금했는데 확인이 안 되나요?'에서 실제로 입금한 사람의 이름을 판매자에게 알릴 수 있습니다.

• 콘솔 → 결제 위젯 → 입금자명 알리기를 켜야 보입니다. 2026년 10월 14일(개정 개인정보처리방침 시행일)부터 켤 수 있고, 그 전에는 켜 두어도 서버가 받지 않습니다.
• 주문마다 2회까지, 입금 대기 중이고 기한 전인 주문에서만 알릴 수 있습니다. 다시 알리면 마지막 이름으로 바뀝니다. 이름은 한글·영문·숫자·공백·괄호로 1~20자입니다.
• 알린 이름으로는 자동확정하지 않습니다. 같은 금액의 입금이 그 이름으로 들어오면 review(확인 필요, review_reason: reported_name)가 되고, 후보에는 그 주문과 함께 같은 금액의 다른 주문도 남습니다. 링크를 가진 누구나 이름을 알릴 수 있으므로, 다른 고객의 입금을 자기 주문으로 끌어오지 못하게 하기 위해서입니다.
• 다른 주문의 원래 입금자명·대체 입금자명과 맞는 입금은 예전처럼 판정됩니다(알린 이름이 그 판정을 바꾸지 않습니다).
• 알리면 최근 7일 안의 같은 금액 미매칭·확인 필요 입금을 다시 대조합니다(역매칭과 같은 방식).
• 알린 이름은 그 주문에 저장되어 콘솔의 입금 확인(후보 주문)·주문 화면과 텔레그램·디스코드·슬랙 확인 필요 알림에 '구매자가 알린 이름'으로 표시됩니다. 공개 API·웹훅·MCP 응답에는 싣지 않습니다. 주문 정보와 같은 기간 동안 보관하고, 입금 확인 화면의 [개인정보 삭제]가 매칭된 주문의 알린 이름도 지웁니다.
• 결과는 같은 모양으로 돌아옵니다 — 링크가 닫혔거나, 꺼져 있거나, 횟수를 다 썼거나, 대기 중이 아니면 모두 '알릴 수 없음'이고, 알린 이름이 어떤 입금과 맞는지는 구매자 화면에 알려 주지 않습니다.
• 테스트 화면에서도 켜면 쓸 수 있습니다(시행일 뒤). 테스트 주문에만 저장되고 테스트 입금과만 대조됩니다.

#안전 규칙

위젯은 우리 도메인(www.autotranspay.com)에서 열리므로, 확인할 수 없는 계좌로 입금을 안내하는 데 쓰이지 않게 다음 규칙을 지킵니다.

• 운영 위젯은 입금 알림 연결이 증명된 계좌만 보여 줍니다. 지금은 본사 공용번호로 입금 알림을 받는 계좌만 해당합니다. 가맹점 휴대폰(수집기)으로 알림을 받는 계좌는 문자 내용과 발신번호를 가맹점 쪽에서 정할 수 있어 증명으로 보지 않습니다. 연결 상태는 콘솔 → 결제 위젯의 계좌 목록에 표시됩니다.
• 화면을 보는 중에 그 계좌가 멈추거나(일시중지·보관) 증명에서 빠지면 열린 화면도 닫히고 계좌가 사라집니다.
• 보여 줄 계좌는 이 순서로 고릅니다.
  1. 주문에 bank_account_id 가 있으면 그 계좌 (증명되지 않았으면 다른 계좌로 바꾸지 않고 widget_url 이 null)
  2. 콘솔에서 고른 안내 계좌
  3. 증명된 계좌가 하나뿐이면 그 계좌
• 운영 위젯은 유료 요금제에서만 열립니다.
• 테스트 모드 위젯은 실제 계좌를 보여 주지 않습니다. 샘플 계좌(테스트은행 000-0000-0000, 예금주 샘플)와 화면 위에 고정된 '테스트 화면 — 실제로 입금하지 마세요' 띠가 표시되고, 화면 제목에 '테스트'가 붙습니다. 완료·문의 버튼은 이동하지 않고, 링크는 24시간 동안만 열립니다. 테스트 모드는 요금제와 관계없이 켜기만 하면 됩니다.
• 화면은 검색에 노출되지 않고(noindex), 링크가 다른 사이트로 새지 않게 리퍼러를 보내지 않으며, 방문 통계에서도 빠집니다.
• 화면을 다른 사이트에 몰래 겹쳐 띄우는 것(클릭재킹)을 막기 위해, 위젯 화면은 허용 도메인에서만 iframe 으로 열립니다. 허용 도메인 변경은 관리자만 할 수 있고 감사 로그에 남습니다.

#결제 완료 처리는 웹훅으로

#샌드박스에서 시험하기

1. 테스트 키로 주문을 등록하고 응답의 widget_url 을 엽니다(또는 콘솔 → 결제 위젯 → 테스트 주문으로 위젯 열기).
2. 샌드박스 입금으로 그 주문에 가짜 입금을 넣습니다. 콘솔 → 주문의 입금 시뮬레이션도 같습니다.
3. 열어 둔 위젯이 몇 초 안에 '입금이 확인됐어요'로 바뀌고, 웹훅 deposit.matched 가 도착하는지 확인합니다.
4. 주문을 취소하면 화면이 '취소된 주문이에요'로 바뀌고 계좌가 사라지는지 확인합니다.
5. 임베드는 로컬 개발 서버(http://localhost:…)의 화면에서 테스트 주문으로 바로 시험할 수 있습니다. 허용 도메인에 넣은 운영 주소에서도 테스트 주문의 위젯이 열립니다.

#아직 없는 기능

• 알림톡으로 계좌 받기
• 현금영수증 신청
• 콘솔 주문 목록에서 입금 안내 링크 보기·복사 (지금은 주문 API·MCP 응답의 widget_url 로만 받을 수 있습니다)