VibeFox Square for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

WooCommerce: 7.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

쇼핑몰 통화: Square 위치의 통화: USD, CAD, AUD, JPY, GBP 또는 EUR. 다른 통화에서는 체크아웃에서 결제 방법이 표시되지 않습니다. Square는 미국, 캐나다, 호주, 일본, 영국, 아일랜드, 프랑스, 스페인의 판매자를 지원합니다.

Square 계정: Square Developer Dashboard에 애플리케이션이 있어야 합니다. 여기에서 Application ID와 Access Token(Credentials 페이지), Location ID(Locations 페이지)를 복사합니다. 샌드박스와 운영 환경의 값은 별도입니다. 웹훅은 필요하지 않습니다. 플러그인은 Square의 응답에서 결제 결과를 직접 받습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서만 작동합니다.

설치

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

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Square > Manage, 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

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

5. Sandbox Mode를 켜 둔 상태에서 샌드박스 Application ID, Access Token, Location ID를 입력합니다(설정 항목 참조). 저장하면 플러그인이 Square에서 자격 증명을 확인합니다.

6. Enable/Disable을 켜고 Square 샌드박스 테스트 가이드의 테스트 카드로 결제를 시험합니다. 그다음 Sandbox Mode 체크를 해제하고 운영 환경의 자격 증명을 입력한 뒤 다시 저장합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Square. 샌드박스 모드가 켜져 있는 동안 페이지는 항목 위에 Square Gateway가 현재 SANDBOX 모드입니다. 실제 결제는 이루어지지 않습니다.를 표시합니다. Square가 활성화되어 있지만 선택한 모드의 Application ID, Access Token 또는 Location ID가 없으면(이 경우 체크아웃에서 결제 방법이 숨겨집니다), 그리고 Square가 쇼핑몰 통화를 처리할 수 없으면 경고합니다. 결제 방법 목록에서 샌드박스 모드가 켜져 있는 동안 Square에는 Test mode 배지가 표시됩니다.

저장할 때 플러그인은 선택한 모드의 자격 증명을 Square에서 확인합니다. Square가 Access Token을 거부하거나, 해당 토큰에 대한 Location ID를 찾을 수 없거나, 자격 증명을 확인할 수 없거나, 위치 통화가 쇼핑몰 통화와 다르면 오류가 표시됩니다. Square는 위치 통화로만 청구할 수 있습니다. 플러그인은 확인된 위치의 통화를 기억하고, 그 밖의 통화에 대해서는 체크아웃에서 결제 방법을 숨기며, 설정 페이지에는 경고가 계속 표시됩니다. 또한 샌드박스 Application ID를 라이브 모드에서 사용하거나 그 반대의 경우에도 경고합니다.

General

Enable/Disable: Enable Square Payment Gateway는 결제 방법을 켜거나 끕니다. 기본값: off.

Title: 고객이 체크아웃 중에 보는 결제 방법의 제목입니다. 기본값: Credit / debit card.

Description: 고객이 체크아웃 중에 보는 결제 방법의 설명입니다. 기본값: Pay securely with your credit or debit card via Square.

Square account

Square Developer Dashboard를 열고 애플리케이션을 선택한 다음, Credentials 페이지에서 Application ID와 Access token(샌드박스와 운영 환경의 값은 별도)을, Locations 페이지에서 Location ID를 복사합니다. 위치 통화는 쇼핑몰 통화와 일치해야 합니다. 페이지에는 선택한 모드의 자격 증명 필드만 표시됩니다. Sandbox Mode가 켜져 있으면 샌드박스 필드를, 꺼져 있으면 라이브 필드를 보여 줍니다.

Sandbox Mode: Enable sandbox (test) mode. 결제는 Square 샌드박스로 전송되며 실제 금액은 청구되지 않습니다. Square 테스트 카드를 사용하세요. 기본값: on.

Sandbox Application ID: Square 샌드박스 Application ID(sandbox-sq0idb-로 시작합니다).

Sandbox Access Token: Square 샌드박스 Access Token.

Sandbox Location ID: Square 샌드박스 Location ID.

Live Application ID: Square 운영 환경 Application ID(sq0idp-로 시작합니다).

Live Access Token: Square 운영 환경 Access Token.

Live Location ID: Square 운영 환경 Location ID.

Advanced

Debug log: Log API requests and responses. 오류는 항상 기록됩니다. 켜면 모든 요청도 기록되며, 카드 데이터와 키는 포함되지 않습니다. 로그는 WooCommerce > Status > Logs에서 확인할 수 있으며, 소스는 wcp_square_gateway입니다. 기본값: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. 플러그인을 삭제하면 게이트웨이 설정과 로그 파일을 삭제합니다. 주문의 결제 데이터는 보존됩니다. 기본값: off.

체크아웃

고객은 결제 방법(기본값 Credit / debit card)을 선택하고, 설명 아래에 표시되는 Square 카드 양식에 카드를 입력합니다. 샌드박스 모드에서는 체크아웃에 샌드박스 안내가 표시됩니다. 고객이 Place order를 클릭하면 카드는 브라우저에서 구매자 인증(3-D Secure / SCA)과 함께 토큰화됩니다. 금액, 통화, 청구 연락처가 Square에 전달되며, 고객의 은행이 확인을 요청할 수 있습니다. 쇼핑몰 서버는 일회용 토큰만 받습니다.

그다음 플러그인은 주문 통화로 된 주문 총액에 대해 Square Payments API를 통해 토큰으로 청구합니다. 참조로는 주문 ID를 사용하고, 주문 번호와 사이트 이름이 포함된 Order # 메모와 청구 이메일을 함께 보냅니다. 결제는 즉시 매입됩니다. 주문은 Square가 확인한 후에만 결제 완료로 표시됩니다. Square 응답에는 주문 총액, 통화, 주문 ID, 위치가 정확히 일치하는 COMPLETED 결제가 나타나야 합니다. 그다음 고객은 주문 접수 페이지로 이동합니다. 결제가 COMPLETED가 아니거나 어떤 값이 다르면 주문은 메모와 함께 보류되고, 고객은 그래도 주문 접수 페이지로 이동합니다.

주문당 동시에 실행되는 결제 시도는 하나뿐입니다. 고객이 두 번 클릭하거나 두 개의 탭에서 결제하면, 두 번째 시도에는 This order is already being paid. Please wait a moment and check your e-mail before trying again.(이 주문은 이미 결제 중입니다. 잠시 기다린 후 이메일을 확인하고 다시 시도하세요.)가 표시됩니다. 요청은 멱등성을 가지므로, 같은 주문, 토큰, 금액으로 두 번째 결제가 생성되는 일은 없습니다.

Square가 응답하지 않으면(네트워크 문제, 시간 초과, 서버 오류) 같은 멱등성 키로 요청을 한 번 더 시도합니다. 그래도 응답이 없으면 고객에게 We could not get a confirmation from the payment provider. Please wait a minute and try again — if your card was already charged, the payment will be recognised and you will not be charged twice.(결제 제공업체로부터 확인을 받지 못했습니다. 1분 정도 기다렸다가 다시 시도하세요. 카드에 이미 청구되었다면 결제가 인식되며 이중으로 청구되지 않습니다.)가 표시됩니다. 주문 메모에는 Square Dashboard를 확인하라는 안내가 기록됩니다. 다음 시도에서 플러그인은 먼저 Square에서 이 주문의 이전 결제를 찾아 그 결제로 주문을 완료하며, 카드를 다시 청구하지 않습니다.

은행이 카드를 거절하면 고객은 Square 오류 코드에 따른 간단한 메시지를 봅니다. 예를 들어 Your card was declined. Please use another card or payment method., The card security code (CVV) is incorrect. Please check it and try again. 또는 Your bank requires additional verification (3-D Secure). Please enter your card again and complete the verification.와 같습니다. 기술적 사유는 주문 메모와 로그에 기록됩니다. 고객은 다른 카드로 다시 시도할 수 있으며, 나중에 Pay for order 페이지에서도 시도할 수 있습니다.

이 결제 방법은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

이 플러그인은 즉시 매입되는 카드 결제만 지원합니다. 저장된 카드나 고객 프로필, WooCommerce Subscriptions 또는 사전 주문, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH 또는 Square 기프트카드, 승인 전용 결제, Square 웹훅, Square와의 상품 또는 재고 동기화는 지원하지 않습니다. 분쟁(차지백)은 Square Dashboard에서 관리합니다.

주문 및 환불

주문 상태

Pending payment: 주문이 생성되었지만 아직 결제되지 않았습니다. 예를 들어 카드가 거절되었거나 Square의 응답이 유실된 후입니다.

Processing: Square가 주문 총액에 대한 COMPLETED 결제를 확인했습니다. 결제 후의 WooCommerce 표준 상태입니다(다운로드 가능한 가상 상품만 있는 주문은 완료됨이 됩니다). 주문 메모에는 Square 결제 ID, 카드 브랜드와 끝 4자리, 모드(샌드박스 또는 운영)가 표시됩니다. 거래 ID는 Square 결제 ID이며, 주문 화면에서는 Square Dashboard의 결제 내역으로 연결됩니다.

On hold: Square가 COMPLETED가 아닌 결제나, 금액, 통화, 참조 또는 위치가 다른 결제로 응답했습니다. Square payment needs review 메모에는 결제 ID, 상태, 금액이 표시됩니다. 주문을 이행하기 전에 Square Dashboard에서 매입, 금액, 통화를 확인하세요.

플러그인은 주문에 Square 결제 ID, 카드 브랜드와 끝 4자리, 환경 및 위치를 저장합니다. 카드 번호는 절대 저장되지 않습니다.

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Credit / debit card를 클릭합니다(버튼에는 설정한 Title이 표시됩니다). 전액 및 부분 환불을 지원합니다. 환불은 결제가 이루어진 환경(샌드박스 또는 운영)과 위치로 전송되므로, 해당 모드의 Access Token이 설정되어 있어야 합니다. 환불 요청은 멱등성을 가지며, Square가 응답하지 않으면 한 번 재시도합니다. Square가 수락한 환불(상태 PENDING 또는 COMPLETED)은 Square 환불 ID와 함께 주문 메모에 추가됩니다. Square가 거부하면 WooCommerce에 오류가 표시되고 환불은 기록되지 않습니다.

Square는 자체적으로 환불을 완료합니다. Square가 나중에 거부한 환불은 WooCommerce에 보고되지 않으며, Square Dashboard에서 이루어진 환불은 WooCommerce에 나타나지 않습니다.

라이선스 키

플러그인은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Square 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 블록에는 상태(예: 라이선스 유효 기간 종료일)와 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

활성 키가 없으면 체크아웃에서 고객에게 Square가 표시되지 않습니다. 그래도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.(이 결제 방법은 사용할 수 없습니다. 다른 방법을 선택해 주세요.)를 봅니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only)가 표시된 결제 방법이 계속 보여, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에는 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 결제 완료된 주문은 결제 완료 상태를 유지하며, 환불도 작동합니다.

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

문제 해결

체크아웃에 Square가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 Application ID, Access Token, Location ID가 입력되어 있는지 확인하세요. 쇼핑몰 통화(또는 Pay for order 페이지의 주문 통화)가 USD, CAD, AUD, JPY, GBP 또는 EUR이고 Square 위치의 통화와 같은지 확인하세요. 설정 페이지에는 이러한 문제마다 경고가 표시됩니다.

카드 양식이 로드되지 않음: 고객에게 The card form could not be loaded. Please reload the page or choose another payment method.(카드 양식을 불러올 수 없습니다. 페이지를 새로 고치거나 다른 결제 방법을 선택하세요.)가 표시됩니다. Application ID와 Location ID가 선택한 모드에 속하는지 확인하세요(샌드박스 ID는 sandbox-로 시작합니다). 고객이 너무 일찍 클릭하면 The card form is still loading. Please wait a moment and try again.(카드 양식을 아직 불러오는 중입니다. 잠시 기다린 후 다시 시도하세요.)가 표시됩니다.

카드가 정상인데도 결제가 거절됨: 위치 통화는 쇼핑몰 통화와 같아야 합니다. 설정을 저장해 자격 증명 확인 결과를 확인하세요. 확인에 성공하면 다른 통화에서는 결제 방법이 숨겨집니다.

Square가 선택한 모드의 Access Token을 거부함: 토큰이 다른 모드에 속하거나 잘못되었습니다. 애플리케이션의 Credentials 페이지에서 다시 복사하고 Sandbox Mode를 확인하세요.

이 Access Token에 대한 Location ID를 찾을 수 없음: 같은 애플리케이션과 같은 모드의 Locations 페이지에서 Location ID를 복사하세요.

고객이 「We could not get a confirmation from the payment provider」를 봄: Square가 응답하지 않았습니다. 주문 메모를 읽고 Square Dashboard에서 이 위치의 결제(참조 = 주문 ID)를 확인하세요. 고객이 다시 시도하면 플러그인은 먼저 이전 결제를 찾아 그 결제로 주문을 완료하며, 다시 청구하지 않습니다.

주문이 On hold 상태임: Square payment needs review 메모를 읽으세요. 결제가 COMPLETED가 아니었거나, 금액, 통화 또는 위치가 주문과 달랐습니다. Square Dashboard에서 확인한 다음 주문을 이행하거나 결제를 환불하세요.

모드 관련 메시지와 함께 환불이 실패함: 결제는 샌드박스 또는 운영 모드에서 이루어졌는데, 해당 모드의 Access Token이 설정되지 않았습니다. 입력한 후 다시 시도하세요.

기타 오류: Debug log를 켜고 WooCommerce > Status > Logs(소스: wcp_square_gateway)를 확인하세요.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르세요. 예를 들어 키가 이미 다른 도메인에서 사용 중이면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하세요. 사이트 주소가 변경되었다면 Check now를 클릭해 새 도메인에 대해 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 다음 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그 파일은 Delete data on uninstall이 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 보존됩니다. 기존 주문은 결제 메모, Square 결제 ID, 거래 ID를 그대로 유지합니다.

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