필요한 것
| 필드 | 하는 일 |
|---|---|
| Access token | Square를 호출해 결제 링크를 만들게 합니다. 비밀. |
| Webhook signature key | 웹훅이 정말 Square에서 왔는지 확인합니다. 비밀. |
| Location ID | 결제를 받는 Square 위치. 통화를 설정합니다. |
| Success URL / Cancel URL | 구매자가 결제 후 또는 빠져나간 뒤 도착하는 곳. |
각 필드를 요청하는 이유
Access token
결제 링크 생성을 승인해, 청구가 당신의 계정을 통해 실행됩니다.
Webhook signature key
들어오는 웹훅이 진짜 Square에서 온 것임을 증명해, 아무도 "결제됨" 이벤트를 위조할 수 없게 합니다. access token과는 별개의 값입니다.
Location ID
Square에 어느 위치가 돈을 받는지 알려주고, 결제 통화를 설정합니다. 비밀이 아닙니다.
Success and Cancel URL
단순한 설정: 구매자가 결제 후 또는 빠져나간 뒤 도착하는 곳. 비밀이 아닙니다.
설정
- Square 개발자 대시보드 열기
developer.squareup.com에 로그인하세요. 각 애플리케이션에는 고유한 자격 정보가 있으며, 테스트용 무료 샌드박스가 함께 생성됩니다. 이 가이드는 샌드박스 기준으로 설명합니다. 라이브 흐름도 동일하며, Sandbox / Production 토글만 전환하고 프로덕션 자격 정보를 사용하면 됩니다. 새 앱을 만들려면 애플리케이션 화면에서 + 타일을 클릭하세요.
Square Developer → 애플리케이션 - 애플리케이션 이름 지정하기
알아보기 쉬운 이름(예: "Coin Moebius")을 입력하고 다음을 클릭하세요.
Square → 애플리케이션 이름 지정 - Access token 복사하기
앱을 열고 Credentials로 이동하세요. 상단의 Sandbox / Production 토글이 설정 중인 환경과 일치하는지 확인하세요. Access token 옆의 복사 아이콘을 클릭해 저장하세요.
Square → Credentials Access token은 비밀이며 비밀번호처럼 취급하세요. Sandbox와 Production은 별도의 토큰을 가지므로 혼용하지 마세요.
- Location ID 복사하기
왼쪽 메뉴에서 Locations를 여세요. 결제를 받을 위치의 Location ID를 복사하세요. 결제 통화를 설정하므로, 청구할 통화의 위치를 선택하세요.
Square → Locations - Webhooks → Subscriptions 열기
Square에서는 웹훅 엔드포인트를 "구독"이라고 합니다. 왼쪽 메뉴에서 Webhooks를 펼치고, Subscriptions를 열고, 구독 추가를 클릭하세요.
Square → Webhooks → Subscriptions → 구독 추가 - 구독 추가 및 이벤트 선택하기
이름(예: "coin-moebius")을 입력하세요. 알림 URL에 프로젝트의 Square 웹훅 주소(아래)를 붙여넣으세요. 그런 다음 Events에서 Coin Moebius가 수신하는 이벤트를 검색해 체크하고 저장을 클릭하세요.
- 일회성 결제: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- 구독(구독 판매 시만 해당): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. 정기 결제를 사용하지 않으면 건너뛰세요.
https://api.coinmoebius.com/webhook/square/<your project id>Square → 웹훅 구독 추가 프로젝트 ID는 Coin Moebius 대시보드의 프로젝트 이름 아래에 있습니다. 위 주소에 입력하세요. 추가 이벤트는 무해하며, 사용하지 않는 것은 무시합니다. 연결된 제공업체 카드(마지막 단계)에도 같은 URL이 표시됩니다.
- 방금 만든 구독 열기
Square가 구독을 저장하고 Webhooks 아래에 활성화됨 상태로 목록에 표시합니다. 이름을 클릭해 서명 키가 있는 세부 패널을 여세요.
Square → Webhooks → 내 구독 (활성화됨) - Signature key 복사하기
구독의 속성 패널에서 Signature key 옆의 복사 아이콘을 클릭하세요. 이 값으로 Coin Moebius가 각 웹훅이 실제로 Square에서 온 것임을 확인합니다. 구독이 생성된 후에만 이 값이 존재하기 때문에 연결 단계보다 웹훅이 먼저입니다.
Square → 내 구독 → Signature key - Coin Moebius로 돌아와 제공업체 추가 → Square
프로젝트에서 제공업체 탭을 열고, 제공업체 추가를 클릭하고, 서비스 연결을 선택한 뒤 Square를 고르세요. Success URL과 Cancel URL을 설정하세요. Live 탭에서 Access token, Webhook signature key, Location ID를 붙여넣은 뒤 저장을 클릭하세요. 먼저 샌드박스 자격 정보로 설정하시나요? 대신 Test 탭에 붙여넣고, 나중에 편집에서 라이브 자격 정보를 추가하세요.
Coin Moebius → 제공업체 추가 → Square - 연결 완료
이제 제공업체 탭에 Square가 연결 날짜와 함께 표시됩니다. 카드에는 Square에 붙여넣은 것과 동일한 웹훅 URL과 편집 및 연결 해제 버튼이 있습니다. 테스트 모드 토글을 사용해 라이브 전환 전에 샌드박스 주문을 처음부터 끝까지 실행하세요.
Coin Moebius → 제공업체 → Square (연결됨) 샌드박스 카드는 실제 카드를 청구하지 않습니다. 카드 번호 4111 1111 1111 1111, CVV 111, 미래의 만료일, 유효한 우편번호(예: 94103)를 사용하세요.
연결한 후
정식 오픈 전에 테스트 결제를 한 번 실행하세요:
- 상품을 만들고 Environment를 Testing으로 설정하세요. 그러면 상품이 당신의 샌드박스 자격 정보로 실행되어, 돈을 움직이지 않고 전체 주문을 넣을 수 있습니다. (샌드박스 세트를 건너뛰었다면 Testing 상품이 라이브로 폴백되니, 먼저 추가하세요.)
- 당신의 프로젝트를 가리키는 페이지(로컬 HTML 파일도 됩니다)에 구매 버튼을 두세요.
- 위의 샌드박스 테스트 카드로 결제를 완료하세요.
- 거래 탭을 여세요. Testing 태그가 붙은 새 행이 나타납니다. 상태가 succeeded에 도달하면, 당신의 자격 정보와 웹훅이 둘 다 처음부터 끝까지 작동하는 것입니다.
실제 결제 준비가 되면 상품 Environment를 Live로 전환하세요.
문제 해결
Verify로 시작하세요. 대시보드에서 Verify(또는 Verify test credentials)를 클릭해 access token과 위치를 확인하세요.
Verify가 실패합니다.
access token과 Location ID를 다시 복사하세요. Production과 Sandbox는 별도의 토큰을 가지므로 섞지 마세요.
서명 검증이 실패하거나 주문이 대기 상태로 남습니다.
Square는 정확한 알림 URL과 본문에 대해 서명합니다. Square에 등록하는 URL은 당신의 웹훅 URL과 글자 하나하나까지, 끝의 슬래시 없이 추가 쿼리 문자열 없이 일치해야 합니다. 그런 다음 같은 엔드포인트에서 signature key를 다시 복사하세요.
처음부터 끝까지 확인하기.
Square Developer Console → Webhooks → your subscription → Send Test Event, 그런 다음 주문이 업데이트되는 것을 지켜보세요.
알아두면 좋은 것
통화는 위치를 따릅니다. 결제는 당신이 제공하는 id의 위치 통화로 청구됩니다.
시크릿 교체. access token이나 signature key를 언제든 갱신한 뒤 새 값을 붙여넣으세요. 비밀 필드는 편집 시 비어 있습니다.
질문이 있으신가요? Join our Discord