VibeFox Peach Payments for WooCommerce — 도움말

요구 사항

WordPress: 6.2 이상.

WooCommerce: 8.0 이상이 설치되고 활성화되어 있어야 합니다. 없으면 플러그인을 활성화할 수 없습니다.

PHP: 8.0 이상.

Currency: 쇼핑몰 통화는 ZAR, KES 또는 MUR여야 합니다. 다른 통화에서는 결제 수단이 숨겨지고 설정 페이지에 안내됩니다.

Peach Payments account: Peach Payments 계정의 Card API 자격 증명인 Entity ID와 Access Token이 필요합니다. 테스트 자격 증명은 Peach Payments 샌드박스 대시보드에서, 운영 자격 증명은 Peach Payments 대시보드에서 가져오며 서로 다릅니다. 웹훅에는 Peach Payments가 쇼핑몰의 Card 웹훅을 활성화할 때 보내는 복호화 키도 필요합니다(설정 참조). 웹훅을 받으려면 사이트에 인터넷으로 접근할 수 있어야 합니다.

VibeFox license key: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 작동합니다.

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택하고 Install Now를 클릭합니다. FTP로 wcp_peach_pay 폴더를 /wp-content/plugins/에 업로드해도 됩니다.

2. Activate를 클릭합니다.

3. 설정 WooCommerce > Settings > Payments > Peach Payments > Manage을 열거나 플러그인 페이지에서 플러그인 이름 아래 Settings를 클릭합니다.

4. 페이지 상단 라이선스 영역에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. Peach Payments 샌드박스 대시보드의 테스트 Entity ID와 Access Token을 입력하고, 설정에 표시된 웹훅 URL에 Card 웹훅을 활성화하도록 Peach Payments에 요청합니다(설정 참조).

6. Enable/Disable를 켜고 저장합니다. Test mode를 켠 상태로 Peach Payments 샌드박스 테스트 카드로 결제합니다. 그런 다음 Test mode를 해제하고 운영 자격 증명과 운영 웹훅 키를 입력하여 저장합니다.

업데이트 후 버전 1.0 설정은 새 필드로 자동 이전됩니다.

설정

모든 설정은 WooCommerce > Settings > Payments > Peach Payments 페이지에 있습니다. 필드 위에는 Test mode is on: payments go to the Peach Payments sandbox and no real money is charged., 현재 모드의 Entity ID 또는 Access Token 누락 안내(입력 전까지 체크아웃에 결제 수단이 표시되지 않음), 현재 모드의 웹훅 복호화 키 누락 안내(고객이 돌아올 때만 결제 확인), 지원되지 않는 통화 안내가 표시됩니다. 결제 수단 목록에서 Peach Payments는 현재 모드에 Entity ID와 Access Token이 있을 때까지 설정 필요로 표시됩니다. 저장 시 자격 증명의 공백이 제거되며, 웹훅 키가 64자의 16진수 값이 아니면 오류가 표시됩니다.

Enable/Disable: Enable Peach Payments는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

Title: 체크아웃에서 고객에게 표시되는 결제 수단 이름입니다. 기본값: Credit / Debit Card (Peach Payments).

Description: 체크아웃의 결제 수단 아래 표시되는 설명입니다. 기본값: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API 자격 증명

Card API의 Access Token과 Entity ID는 Peach Payments 대시보드에 표시됩니다(테스트 자격 증명은 샌드박스 대시보드). 이 섹션에는 두 대시보드와 Peach Payments 개발자 문서 링크가 있습니다.

Test mode: Enable test mode는 테스트 자격 증명으로 새 결제를 Peach Payments 샌드박스에 보내며 실제로 청구하지 않습니다. 해제하면 운영 자격 증명으로 실제 결제를 받습니다. 한 모드에서 시작된 결제는 모드를 전환해도 항상 시작한 모드에서 확인합니다. 기본값: 켜짐.

Test Entity ID: 샌드박스 계정의 Entity ID(3-D Secure 채널).

Test Access Token: 샌드박스 계정의 bearer 액세스 토큰.

Test Webhook Decryption Key: 샌드박스 Card 웹훅을 복호화하는 64자의 16진수 키.

Live Entity ID: 운영 계정의 Entity ID(3-D Secure 채널).

Live Access Token: 운영 계정의 bearer 액세스 토큰.

Live Webhook Decryption Key: 운영 계정 Card 웹훅을 복호화하는 64자의 16진수 키.

웹훅

웹훅은 고객이 돌아오기 전에 브라우저를 닫아도 결제를 확인합니다. 이 섹션에는 https://your-site/wp-json/peach-pay/v1/webhook 형태의 쇼핑몰 웹훅 URL이 표시됩니다. 설정에 나온 그대로 복사하세요. Peach Payments(support@peachpayments.com)에 해당 URL로 계정의 Card 웹훅을 활성화하도록 요청한 뒤, 받은 복호화 키를 같은 모드의 Webhook Decryption Key 필드에 입력합니다.

Peach Payments는 모든 웹훅을 암호화합니다(AES-256-GCM). 테스트 또는 운영 키로 복호화할 수 없는 웹훅은 거부되므로 Peach Payments만 주문을 변경할 수 있습니다. 한 모드의 키로 복호화한 웹훅은 그 모드에서 시작한 결제에만 적용됩니다. 플러그인은 다음 결제 알림을 사용합니다.

Debit payment (DB): 주문의 카드 결제 결과입니다. 주문을 결제 완료, 보류 중 또는 실패로 표시합니다(주문 참조).

Refund (RF), reversal (RV), chargeback (CB): Peach Payments 대시보드의 환불 또는 취소, 혹은 보고된 차지백입니다. 주문 메모로 추가되며 주문 상태는 바뀌지 않습니다.

웹훅 활성화 시 전송되는 테스트 알림 등 다른 알림에는 OK로 응답하고 무시합니다. 웹훅 키가 없으면 결제 후 고객이 쇼핑몰로 돌아올 때만 주문을 확인합니다.

결제 양식

Card brands: Peach Payments 양식에 표시할 브랜드: Visa, Mastercard, American Express, Diners Club. Entity ID에 활성화된 브랜드만 선택하세요. 기본값: Visa와 Mastercard.

고급

Logging: Log API requests and payment results는 디버그 정보를 WooCommerce > Status > Logs의 wcp_peach_pay 소스에 기록합니다. 오류와 경고는 항상 기록합니다. 로그에 카드 데이터, 키, 고객 데이터를 포함하지 않습니다. 기본값: 꺼짐.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. 플러그인 비활성화는 아무것도 삭제하지 않습니다. 주문에 저장된 Peach Payments 데이터는 유지됩니다. 기본값: 꺼짐.

체크아웃

고객은 결제 수단(기본값 Credit / Debit Card (Peach Payments))을 선택하고 Continue to payment를 클릭합니다. 쇼핑몰의 Pay for order 페이지로 이동하면 플러그인이 주문 총액과 통화로 Peach Payments 체크아웃을 준비하고 선택한 브랜드의 Peach Payments 카드 양식을 표시합니다. Peach Payments가 지원하면 사이트 언어를 사용합니다. 테스트 모드에서는 Test mode: use a Peach Payments test card, no real payment will be made.가 표시됩니다. 카드 정보는 Peach Payments 양식에 입력하며 스크립트는 Subresource Integrity 해시와 함께 로드됩니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. Peach Payments 확인 후에만 주문이 결제 완료로 표시됩니다. 쇼핑몰은 Peach Payments API에서 해당 주문의 체크아웃 결과를 생성 당시 모드로 조회하여 결제가 해당 주문에 속하는지 확인합니다. 웹훅도 독립적으로 같은 작업을 수행하므로 먼저 도착한 쪽이 결과를 적용하고 다른 쪽은 변경하지 않습니다. 결제한 고객은 Order received 페이지를 봅니다.

결제가 완료되지 않으면 고객은 Pay for order 페이지로 돌아와 메시지를 보고 다시 시도할 수 있습니다. Payment failed: 뒤에 Peach Payments 사유와 Please try again or use another card. 또는 The payment was not completed. Please try again.가 표시됩니다. 결과를 아직 확인할 수 없다면(예: Peach Payments 응답 없음 또는 웹훅이 같은 주문 처리 중) We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.가 표시됩니다. 모드에 웹훅 키가 없으면 대신 주문 번호와 함께 쇼핑몰에 연락하도록 안내합니다.

양식을 준비할 수 없으면 고객은 짧은 메시지와 Try again 버튼을 봅니다. The payment form is not available right now (payment configuration error). Please contact us or choose another payment method.(잘못된 자격 증명), 결제 제공업체가 일부 청구 정보를 거부했다는 메시지 또는 The payment form could not be loaded. Please try again in a moment.입니다. 주문에는 Peach Payments 코드와 설명이 담긴 메모가 추가됩니다.

결제 수단은 클래식 체크아웃, 체크아웃 블록 및 Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다.

플러그인은 체크아웃 페이지 자체의 카드 양식, 저장된 카드, 구독, 사전 승인 및 캡처, EFT, BNPL, QR 등 카드 이외의 수단을 지원하지 않습니다.

주문

주문 상태

Pending payment: 고객이 아직 결제하지 않았거나 결제가 완료되지 않았습니다. 같은 주문을 다시 결제할 수 있습니다.

Processing: 결제가 확인되었고 금액과 통화가 주문과 일치합니다. 메모에는 Peach Payments 결과 코드, 설명 및 결제 ID가 표시되며 결제 ID가 주문의 거래 ID입니다. Peach Payments가 수동 검토 대상으로 표시했다면 배송 전에 Peach Payments 대시보드에서 확인하도록 메모에 안내합니다.

On hold: 결제가 Peach Payments 확인을 기다리는 중(웹훅이 나중에 완료 또는 실패 처리)이거나, 결제 금액 또는 통화가 다르거나(메모 amount/currency mismatch — manual review required), 주문 취소 후 결제가 도착한 경우입니다. 메모에 확인할 사항이 설명됩니다.

Failed: Peach Payments가 결제 대기 중 주문의 결제 또는 보류 중 주문이 기다리던 결제를 거부했습니다. 거부된 시도는 결제 완료, 다른 사유의 보류 또는 취소된 주문을 변경하지 않습니다. 고객은 다시 결제할 수 있습니다.

이미 결제한 주문의 두 번째 결제가 성공해도 주문은 바뀌지 않습니다. 메모에 중복 결제임을 표시하고 Peach Payments 대시보드에서 환불하도록 요청합니다. 환불된 주문에 도착한 결제는 메모만 남깁니다.

환불

WooCommerce 주문 화면의 환불은 지원하지 않습니다. Peach Payments 대시보드에서 환불하고 WooCommerce에 수동 환불을 기록하세요. 웹훅이 설정되어 있으면 Peach Payments의 환불, 취소, 차지백을 금액과 ID가 포함된 주문 메모로 추가하며 주문 상태는 바꾸지 않습니다.

라이선스 키

플러그인은 vibefox.net의 VibeFox 라이선스 키로 작동합니다. 라이선스 영역은 WooCommerce > Settings > Payments > Peach Payments 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 영역에는 라이선스 유효 기간과 도메인 등의 상태가 표시됩니다. Check now로 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 작동합니다. 사이트에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 해제하세요.

활성 키가 없으면 고객 체크아웃에 Peach Payments가 표시되지 않습니다. 그래도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.를 봅니다. 로그인한 쇼핑몰 관리자는 (unlicensed — visible to admins only) 표시와 함께 결제 수단을 계속 볼 수 있어 키 구매 전에 설정하고 테스트할 수 있습니다. 플러그인 및 WooCommerce 페이지에 알림이 나타납니다. 기존 주문에는 영향이 없으며 시작된 결제는 고객 복귀와 웹훅으로 계속 확인됩니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만 업데이트와 지원에는 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인합니다.

문제 해결

체크아웃에 Peach Payments가 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable가 켜졌는지, 현재 모드의 Entity ID와 Access Token이 입력되었는지(테스트는 Test Entity ID와 Test Access Token, 운영은 Live Entity ID와 Live Access Token), 통화가 ZAR, KES 또는 MUR인지 확인하세요. 설정 상단 알림에 문제가 표시됩니다. 개발자는 peach_p_supported_currencies 필터로 통화 목록을 바꿀 수 있으며 Peach Payments 계정이 처리하는 통화만 추가해야 합니다.

결제했지만 주문이 Pending payment 상태임: 고객이 돌아오지 않았고 웹훅도 도착하지 않았습니다. Peach Payments가 설정의 정확한 URL에 Card 웹훅을 활성화했는지, 결제 모드의 Webhook Decryption Key가 입력되었는지, 유지보수 모드·방화벽·암호 보호가 URL을 막지 않는지 확인하세요. WooCommerce > Status > Logs의 wcp_peach_pay 소스에서 거부된 웹훅을 확인하세요.

웹훅이 Decryption failed 응답: 테스트 또는 운영 키로 복호화하지 못했습니다. 키가 잘못되었거나 다른 계정 또는 모드에 속합니다. 이 URL에 대해 Peach Payments가 보낸 키를 입력하세요.

웹훅이 Webhook key not configured 응답: 두 키 모두 설정되지 않았거나 유효하지 않습니다. 64자 키를 입력하세요. Peach Payments가 나중에 재전송합니다.

웹훅이 Order busy, retry later 응답: 고객 복귀로 인한 주문 업데이트가 동시에 진행 중이었습니다. 변경되지 않았으며 Peach Payments가 다시 보냅니다.

웹훅이 Missing or malformed data 응답: 요청에 암호화 본문 또는 X-Initialization-Vector / X-Authentication-Tag 헤더가 없습니다. 프록시 변경 등이 원인일 수 있습니다. 변경되지 않았습니다.

웹훅이 ignored 응답: 진짜 알림이지만 이 쇼핑몰의 체크아웃에 속하지 않거나(같은 Entity ID의 다른 쇼핑몰, 삭제된 주문) 결제와 다른 모드에서 왔습니다. 변경되지 않았습니다.

고객에게 The payment form is not available right now 표시: 현재 모드의 Access Token 또는 Entity ID가 잘못되었습니다. 자격 증명과 모드를 확인하고 주문 메모의 Peach Payments 코드를 읽으세요.

결제 후 주문이 On hold 상태: 메모를 읽으세요. 금액 또는 통화가 다르거나, 취소 후 결제가 도착했거나, Peach Payments가 아직 확인을 기다립니다. Peach Payments 대시보드에서 결제를 확인한 뒤 주문을 처리하거나 환불하세요.

저장 시 64자의 16진수 웹훅 키를 요구함: 값이 Peach Payments 키가 아닙니다. 수정 전에는 웹훅을 복호화할 수 없습니다.

라이선스 영역에 오류 표시: 메시지를 따르세요. 다른 도메인에서 키를 사용 중이면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭합니다. 사이트 주소가 바뀌었다면 Check now로 새 도메인에 활성화합니다. 라이선스 서버에 연결할 수 없으면 마지막 확인 상태로 작동합니다.

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화하고 삭제하세요. 라이선스 키와 상태는 항상 제거됩니다. 설정과 로그(wcp_peach_pay 소스의 로그 파일 및 데이터베이스 로그 항목)는 Delete data on uninstall가 켜져 있었을 때만 제거됩니다. 그렇지 않으면 재설치를 위해 유지됩니다. 기존 주문의 결제 메모, 거래 ID, Peach Payments 체크아웃 데이터는 유지됩니다.

Peach Payments는 해당 소유자의 상표입니다. 이 플러그인은 Peach Payments와 제휴하거나 승인을 받은 제품이 아닙니다.