# WooCommerce

> WooCommerce용 결제 수단: 비트코인과 USDC/USDT를 내 지갑으로 바로, 서명된 웹훅이 주문을 결제 완료로 표시합니다.

Perly Pay 플러그인이 클래식 결제 화면과 결제 블록에 암호화폐를 더합니다. 주문마다 Perly Pay 청구서가 되고, 구매자는 상점 위나 별도 페이지에서 결제하며, 서명된 웹훅이 주문을 결제 완료로 표시합니다. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. 서버에 설치할 것은 없습니다: [PHP SDK](https://pay.perly.io/docs/sdks.md)가 이미 들어 있습니다.

> **참고:** 청구서는 USD나 EUR로 발행됩니다. 다른 통화를 쓰는 상점에서는 이 결제 수단이 숨겨지고, 설정 화면에 이유가 나옵니다.

## 설치

1. **zip 받기** — 플러그인은 WordPress.org에 올라가는 중입니다. 그때까지는 [문의](https://pay.perly.io/ko/contact)로 `perly-pay-woocommerce.zip`을 요청하세요.
2. **설치** — WordPress에서: 플러그인 → 새로 추가 → 플러그인 업로드, zip을 고르고 활성화하세요. WooCommerce가 활성화되어 있어야 합니다.
3. **설정 열기** — WooCommerce → 설정 → 결제 → **Perly Pay**.

## 설정

| Setting(설정) | 넣을 것 |
| --- | --- |
| Secret key(비밀 키) | Dashboard → Developers → API keys. [테스트 모드](https://pay.perly.io/docs/test-mode.md)는 `sk_test_…`, 실제 돈은 `sk_live_…`. 설정 화면에 현재 모드가 나옵니다. |
| Webhook signing secret(웹훅 서명 비밀 값) | `whsec_…`. **Set up webhook**(웹훅 설정)이 자동으로 채웁니다. |
| Payment page(결제 페이지) | **Overlay**(오버레이)는 상점 위에 결제창을 엽니다(pay.js). **Redirect**(이동)는 구매자를 결제 페이지로 보냅니다. 휴대폰에서는 항상 페이지가 열립니다. |
| Status when paid(결제 후 상태) | WooCommerce가 정하는 대로(처리중, 다운로드 상품은 완료됨), 항상 처리중, 또는 항상 완료됨. |
| Title, Description(이름, 설명) | 구매자가 결제 화면에서 보는 것. |
| Debug log(디버그 로그) | WooCommerce → 상태 → 로그의 이벤트와 오류. 키, 비밀 값, 구매자 정보는 절대 남기지 않습니다. |

1. **키 붙여 넣기** — 그리고 **Test connection**(연결 확인)을 누르세요: 키가 작동하는지, 모드, 그리고 이 상점의 웹훅이 Perly Pay에 있는지 보여 줍니다.
2. **웹훅 설정** — **Set up webhook**을 누르세요. 상점 URL(버튼 위에 있는 `…/wp-json/perly-pay/v1/webhook`)을 Perly Pay에 추가하고 비밀 값을 저장합니다. 또는 Developers → Webhooks에서 직접 추가하고 비밀 값을 붙여 넣으세요.
3. **오버레이 허용** — Dashboard → Settings의 **Sites that may embed the checkout**에 상점 주소를 추가하세요. 그러지 않으면 오버레이가 새 탭에서 결제를 열라고 제안합니다.
4. **켜기** — **Take crypto with Perly Pay**(Perly Pay로 암호화폐 받기)에 체크하고 저장하세요.

## 테스트

`sk_test_…` 키로 내 상점에서 주문하고 Perly Pay를 고르세요. 주문은 **결제 대기 중**으로 기다립니다. 테스트 코인으로, 또는 API로 청구서를 결제하세요 — ID는 주문 메모에 있습니다:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

몇 초 안에 주문이 **처리중**이 되고 메모가 붙습니다: 네트워크, 금액, 트랜잭션 링크. 청구서 페이지에서 코인을 고른 뒤라면 `{"outcome":"short"}`와 `{"outcome":"over"}`로 다른 경우를 테스트할 수 있습니다.

## 주문이 결제를 따라가는 방식

| Perly Pay에서 | 주문 |
| --- | --- |
| 결제됨, 송금자 검사 완료(`invoice.fulfilled`) | 결제 완료: 선택한 상태, 재고 차감, 구매자에게 이메일. 송금과 트랜잭션마다 메모. |
| 감지됨, 일부 결제, 결제됐지만 아직 검사 중 | 메모. 계속 대기. |
| [검토](https://pay.perly.io/docs/screening.md)를 위해 보류 | 보류중, 이유와 함께. Perly Pay에서 결정하세요. |
| 만료 또는 취소, 결제 없음 | 취소됨. |
| 만료, 일부 결제 | 보류중: Perly Pay에서 환불하거나 수락하세요. |
| 환불됨 | 전액 환불됨, 또는 일부에 대한 메모. |

모든 이벤트는 그것이 만들어진 주문에 한 번만 적용되며, 늦게 온 '만료'가 결제를 취소하는 일은 없습니다. 구매자가 웹훅보다 먼저 감사 페이지로 돌아오면 플러그인이 API에 물어 주문을 바로 업데이트합니다.

## 환불

주문 페이지에서 평소처럼 환불하세요: 플러그인이 결제한 코인으로 Perly Pay에 [환불](https://pay.perly.io/docs/refunds.md)을 엽니다(부분 환불이면 그 부분만). Perly Pay가 이메일로 구매자에게 주소를 받아 검사하고, 주문 메모에 무엇을 어디로 보낼지 나옵니다. 내 지갑에서 보내고 Perly Pay에 트랜잭션 ID를 붙여 넣으세요 — Perly Pay는 돈을 절대 보관하지 않습니다.

## 출시

- Perly Pay에서 라이브 모드를 켜고 지갑의 공개 키를 연결하세요.
- `sk_live_…` 키를 붙여 넣으세요. 라이브 키와 웹훅은 테스트와 별개입니다: **Set up webhook**을 다시 누르세요.
- 라이브 모드의 **Sites that may embed the checkout**에 실제 상점의 https 주소를 추가하세요.
- 작은 실제 주문 하나를 하고 환불해 보세요.