WooCommerce 플러그인

공식 SoloPay for WooCommerce 플러그인으로 WooCommerce 스토어에서 가스비 없는 비수탁형 스테이블코인 결제를 받을 수 있습니다. 코드가 필요 없고, 대금은 가맹점 지갑으로 직접 정산되며, 고객은 가스비를 내지 않습니다.

제공 기능

• WooCommerce 결제 단계에서 ERC-20 스테이블코인 결제 수용
• 고객 가스비 0원 (SoloPay가 대납)
• 가맹점 지갑으로 즉시 비수탁형 정산
• 데스크톱(팝업) 및 모바일(리디렉션) 지원
• 서버 측 결제 검증 및 주문 자동 완료
• WooCommerce 블록 및 클래식 결제 모두 호환

요구 사항

• WordPress 6.0 이상
• WooCommerce 7.0 이상
• PHP 8.1 이상
• 발급받은 자격 증명이 있는 SoloPay 가맹점 계정

1단계: 자격 증명 준비

SoloPay 가맹점 대시보드에서 플러그인에 입력할 네 가지 값을 확인합니다.

자격 증명	형식	사용 위치
Public Key	pk_live_xxx	결제 페이지에서 위젯 초기화
Webhook Secret	whsec_xxx	수신 웹훅의 HMAC 서명 검증
Merchant API Key	x-api-key	서버 측에서 결제 금액과 상태 검증
Token Address	0x...	수용할 ERC-20 토큰 컨트랙트 주소 (예: USDC)

시크릿 보호

Webhook Secret 과 Merchant API Key 는 시크릿입니다. 플러그인 설정에만 입력하고, 클라이언트 코드나 공개 저장소에 노출하지 마세요.

2단계: 플러그인 설치

1. SoloPay 연동 페이지에서 solopay-woocommerce.zip 을 내려받습니다.
2. WordPress에서 플러그인 → 새로 추가 → 플러그인 업로드 로 이동합니다.
3. 내려받은 ZIP을 선택하고 지금 설치 를 누른 뒤 활성화 합니다.

3단계: SoloPay 활성화 및 설정

1. WooCommerce → 설정 → 결제 로 이동합니다.
2. SoloPay 를 활성화한 뒤 관리(또는 설정)를 누릅니다.

3. 설정 항목을 입력합니다.

항목	설명
사용/미사용	결제 단계에서 SoloPay 결제 수단을 켭니다
제목(Title)	결제 단계에서 고객에게 표시되는 이름 (예: "스테이블코인으로 결제")
설명(Description)	제목 아래에 표시되는 짧은 안내 문구
Public Key	pk_live_xxx 키
Webhook Secret	whsec_xxx 시크릿
Merchant API Key	x-api-key (서버 측 결제 검증에 사용)
Webhook URL	자동 생성, 읽기 전용. 4단계에서 사용하도록 복사
Token Address	수용할 ERC-20 컨트랙트 주소 (필수)
디버그 로그	선택. WooCommerce → 상태 → 로그에 진단 로그를 기록

4. 변경 사항 저장 을 누릅니다.

4단계: 웹훅 설정

웹훅은 온체인에서 결제가 확인되면 SoloPay가 스토어에 안정적으로 알리는 방법으로, 고객이 결제 후 돌아오기 전에 브라우저를 닫아도 동작합니다.

1. 플러그인 설정의 Webhook URL 값을 복사합니다.
2. SoloPay 가맹점 대시보드 → 설정 → Webhooks 를 열어 해당 URL을 붙여넣습니다.
3. 플러그인 설정의 Webhook Secret 과 Merchant API Key 가 대시보드와 일치하는지 확인한 뒤 저장합니다.

웹훅은 외부에서 접근 가능해야 합니다

운영 스토어에서는 웹훅 URL이 외부에서 접근 가능해야 합니다. 로컬 개발 환경에서는 웹훅이 localhost 에 도달하지 못하는 경우가 많으므로, 플러그인은 서명된 리턴 URL 로도 주문을 완료합니다(주문 완료 방식 참고). 로컬에서 웹훅을 받으려면 ngrok, cloudflared 같은 터널로 스토어를 노출하세요.

Webhook URL은 퍼머링크 설정에 따라 달라집니다.

• 예쁜 퍼머링크: https://yourstore.com/wp-json/solopay/v1/webhook
• 기본 퍼머링크: https://yourstore.com/?rest_route=/solopay/v1/webhook

직접 입력하지 말고 항상 플러그인에 표시된 정확한 값을 사용하세요.

5단계: 결제 테스트

1. 상품을 장바구니에 담고 결제 단계로 이동합니다.
2. 결제 수단으로 SoloPay 를 선택하고 주문합니다.

3. 스토어가 SoloPay 결제 페이지로 리디렉션되고 위젯이 열립니다. 지갑으로 결제를 완료합니다.

구매자 측 지갑 흐름(연결, 가스비 대납, 승인, 서명)은 유저 가이드를 참고하세요.

6단계: 주문 완료 확인

온체인에서 결제가 확인되면 주문이 자동으로 처리 중 또는 완료 상태로 전환되고, WooCommerce가 고객에게 기본 주문 이메일을 발송합니다.

주문 완료 방식

주문은 두 가지 검증 경로 중 먼저 도착하는 쪽에서 완료됩니다. 두 경로 모두 Merchant API Key로 동일한 금액 검증을 수행하고 멱등적으로 동작하므로, 주문이 중복 완료되거나 미달 결제로 완료되는 일이 없습니다.

1. 서명된 리턴 URL — 구매자가 성공 페이지로 돌아오면 플러그인이 HMAC 서명을 검증한 뒤, 게이트웨이에서 결제를 다시 조회하여 status === PAID 와 결제 금액이 주문 금액과 일치하는지 확인합니다. 웹훅이 스토어에 도달하지 못해도 동작합니다.
2. 웹훅(신뢰 원천) — SoloPay는 서명된 POST를 웹훅 URL로도 전송하며, 플러그인은 서명을 검증하고 동일한 금액 검증을 수행합니다. 돌아오지 않고 브라우저를 닫은 구매자를 커버합니다.

Merchant API Key가 필요한 이유

두 경로 모두 주문을 완료하기 전에 Merchant API Key로 서버 측에서 결제 금액을 검증합니다. 이 키가 없으면 주문은 대기 중 상태로 남고 자동 완료되지 않습니다.

문제 해결

증상	원인 및 해결
결제 후에도 주문이 대기 중 으로 남음	Merchant API Key 누락/오류이거나 웹훅 URL이 등록되지 않음/접근 불가. 둘 다 확인.
웹훅이 수신되지 않음	스토어가 외부에서 접근 불가하거나, 대시보드 URL이 플러그인 Webhook URL과 불일치.
결제 단계에 결제 수단이 표시되지 않음	SoloPay가 비활성화되었거나 Token Address 가 비어 있음. 둘 다 필수.
로그에 "Amount mismatch"	스토어 통화/가격/토큰이 결제 생성 시점과 다름. 디버그 로그를 켜서 확인.
재시도 시 DUPLICATE_ORDER	자동 처리됨. 재시도마다 플러그인이 새 결제 레퍼런스를 생성.

설정에서 디버그 로그 를 켜고 WooCommerce → 상태 → 로그(소스 solopay)에서 상세 내용을 확인하세요.

테스트넷 결제 받기 (예: Polygon Amoy)

코드 변경이나 재빌드 없이 Polygon Amoy 같은 테스트넷에서 결제를 받을 수 있습니다.

1. SoloPay 가맹점 대시보드에서 가맹점 계정의 체인/네트워크를 테스트넷(예: Polygon Amoy)으로 전환합니다.
2. 해당 네트워크의 토큰 주소를 복사하여 플러그인의 Token Address 설정에 붙여넣고 저장합니다.

이후 게이트웨이가 선택한 테스트넷에서 결제를 처리합니다. 메인넷으로 돌아가려면 체인을 다시 전환하고 Token Address 를 메인넷 토큰으로 업데이트하세요.

다음 단계

• 웹훅 가이드 — 이벤트 페이로드 및 서명 검증
• 유저 가이드 — 구매자 측 지갑 및 결제 흐름
• 빠른 시작 — 플러그인 없이 직접 연동 구축