VibeFox Square for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 모듈은 이전 PHP 버전에는 설치되지 않습니다.

통화: 장바구니 통화는 Square 위치의 통화와 같아야 합니다: USD, CAD, AUD, JPY, GBP 또는 EUR. 다른 통화의 경우 결제 수단이 체크아웃에 표시되지 않습니다. Square는 미국, 캐나다, 호주, 일본, 영국, 아일랜드, 프랑스, 스페인의 판매자를 지원합니다.

Square 계정: Square Developer Dashboard에서 애플리케이션을 만들어야 합니다. 여기에서 Application ID와 Access Token(Credentials 페이지), Location ID(Locations 페이지)를 복사합니다. Sandbox와 Production의 값은 별도입니다. 웹훅은 필요하지 않습니다. 모듈은 Square의 응답에서 결제 결과를 직접 받습니다.

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

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동하여 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox Square Gateway를 찾아 Configure를 클릭합니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key 입력란에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다(라이선스 키 참조).

4. Sandbox Mode를 켜 둔 상태에서 sandbox용 Application ID, Access Token, Location ID를 입력합니다(설정 참조). Save를 클릭하면 모듈이 Square에서 자격 증명을 확인합니다.

5. Enable/Disable을 켜고 저장한 후, Square 샌드박스 테스트 가이드의 테스트 카드로 결제를 시험합니다. 그다음 Sandbox Mode를 끄고, 운영 자격 증명을 입력한 뒤 다시 저장합니다.

설치 시 모듈은 Square payment on hold 주문 상태를 만듭니다. PrestaShop은 새 결제 모듈에 설치 시점에 활성화된 통화, 국가, 고객 그룹을 허용합니다. 이를 확인하고, 나중에 추가한 국가는 Payment > Preferences에서 체크하세요.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Square Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 Save 버튼이 있습니다. Sandbox 모드가 켜져 있으면 입력란 위에 Square Gateway는 현재 SANDBOX 모드입니다. 실제 결제는 이루어지지 않습니다. 가 표시됩니다. Square가 활성화되어 있는데 선택된 모드의 Application ID, Access Token 또는 Location ID가 없으면(이 경우 결제 수단은 체크아웃에서 숨겨집니다), Square가 쇼핑몰의 기본 통화를 처리할 수 없으면, 또는 Square 위치의 통화가 쇼핑몰 통화와 다르면 경고합니다.

저장하면 모듈은 선택된 모드의 자격 증명을 Square에서 확인합니다. 설정은 어떤 경우에도 저장됩니다. Square가 액세스 토큰을 거부하거나, 해당 토큰에 대해 위치 ID를 찾을 수 없거나, 자격 증명을 확인할 수 없거나, 위치 통화가 쇼핑몰 통화와 다르면 경고가 표시됩니다. Square는 위치의 통화로만 청구할 수 있습니다. 모듈은 확인된 위치의 통화를 기억하고, 다른 통화의 장바구니에서는 결제 수단을 숨깁니다. 또한 live 모드에서 sandbox Application ID를 사용하거나 그 반대인 경우에도 경고합니다.

Square

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

Title: 고객이 체크아웃에서 보는 결제 수단 제목입니다. 주문에 저장되는 결제 수단 이름이기도 합니다. 기본값: Credit / debit card. 필수.

Description: 고객이 체크아웃에서 보는 결제 수단 설명입니다. 기본값: Pay securely with your credit or debit card via Square. 샌드박스 모드에서는 (SANDBOX MODE)가 추가됩니다.

Square 계정

Square Developer Dashboard를 열고(이 섹션에 링크가 있습니다) 애플리케이션을 선택한 뒤, Credentials 페이지에서 Application ID와 Access token(Sandbox와 Production의 값은 별도입니다), Locations 페이지에서 Location ID를 복사합니다. 위치의 통화는 쇼핑몰 통화와 일치해야 합니다. 페이지에는 선택된 모드의 자격 증명 입력란만 표시됩니다. Sandbox Mode가 켜져 있으면 sandbox 입력란, 꺼져 있으면 live 입력란이 표시됩니다. 두 세트 모두 저장된 상태로 유지됩니다.

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

Sandbox Application ID: Square sandbox Application ID입니다(sandbox-sq0idb-로 시작합니다).

Sandbox Access Token: Square sandbox Access Token입니다.

Sandbox Location ID: Square sandbox Location ID입니다.

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

Live Access Token: Square 운영 Access Token입니다.

Live Location ID: Square 운영 Location ID입니다.

저장된 액세스 토큰은 다시 표시되지 않습니다. 입력란은 비어 있으며 저장됨 — 유지하려면 비워 두세요.라고 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

Clear saved secrets: 액세스 토큰을 체크하고 Save를 클릭하면 삭제됩니다. 빈 입력란은 저장된 값을 유지합니다.

고급

Debug log: 오류와 경고는 항상 기록됩니다. 켜면 모든 요청과 응답도 카드 데이터나 키 없이 모듈 폴더의 logs/wc_sqg_debug.log.php에 기록됩니다. 이 파일은 웹에서 열 수 없습니다. 기본값: off.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 비워집니다.

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정과 로그 파일이 삭제됩니다. 주문의 Square 결제와 환불, 그리고 Square payment on hold 주문 상태는 항상 유지됩니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Credit / debit card)을 선택하고, 설명 아래에 표시되는 Square 카드 양식에 카드를 입력합니다. 고객이 주문을 하면 카드는 브라우저에서 구매자 인증(3-D Secure / SCA)과 함께 토큰화됩니다. 장바구니 총액, 통화, 청구지 주소가 Square에 전달되며, 고객의 은행이 확인을 요청할 수 있습니다. 쇼핑몰은 일회용 토큰만 받습니다.

그다음 모듈은 Square Payments API를 통해 장바구니 통화로 장바구니 총액을 해당 토큰에 청구합니다. 참조로 장바구니 ID를 사용하고, 장바구니 번호와 쇼핑몰 이름이 들어간 Cart # 메모와 고객의 이메일 주소도 함께 전송합니다. 결제는 즉시 매입됩니다. 주문은 Square가 확인한 후에만 결제 완료로 표시됩니다. Square의 응답에는 장바구니 총액, 통화, 장바구니 ID, 위치가 정확히 일치하는 COMPLETED 결제가 나타나야 합니다. 그런 다음 주문은 Payment accepted 상태로 생성되고, 고객에게는 카드 결제가 접수되었습니다. 라는 메시지와 Square 영수증 링크가 포함된 표준 주문 확인 페이지가 표시됩니다. 결제가 COMPLETED가 아니거나 값이 하나라도 일치하지 않으면, 주문은 Square payment on hold 상태로 생성되고, 페이지에는 카드 결제가 접수되었으며 검토 중입니다. 검토가 완료되는 대로 주문을 업데이트하겠습니다. 가 표시됩니다.

장바구니당 동시에 실행되는 결제 시도는 하나뿐입니다. 고객이 두 번 클릭하거나 두 개의 탭에서 결제하면, 두 번째 시도에는 이 주문은 이미 결제 처리 중입니다. 잠시 기다린 후 다시 시도하기 전에 이메일을 확인하세요. 가 표시됩니다. 요청은 멱등성을 갖습니다. 같은 장바구니, 같은 카드 토큰, 같은 금액으로는 두 번째 결제가 절대 생성되지 않으며, 이미 주문이 있는 장바구니는 다시 청구되지 않습니다.

Square가 응답하지 않으면(네트워크 문제, 시간 초과, 서버 오류), 같은 멱등성 키로 요청을 한 번 재시도합니다. 그래도 응답이 없으면 모듈은 즉시 Square에서 이 장바구니의 결제를 찾습니다. 찾으면 그 결제로 주문을 생성합니다. 결제를 찾지 못하면 고객은 체크아웃에 머물며 결제 제공업체로부터 확인을 받지 못했습니다. 1분 정도 기다린 후 다시 시도해 주세요. 카드가 이미 청구되었다면 결제가 확인되어 이중으로 청구되지 않습니다. 가 표시됩니다. 다음 시도에서는 먼저 이전 결제를 다시 조회합니다. 이 조회를 위해서도 Square에 연결할 수 없으면, 주문은 결제 없이 Square payment on hold 상태로 생성되며, 카드가 청구되었을 수 있다는 메모가 함께 기록됩니다. 확인 페이지에는 Square에서 카드 결제 확인을 받지 못했습니다. 다시 결제하기 전에 이메일과 카드 명세서를 확인하시거나, 문의해 주세요. 가 표시됩니다.

은행이 카드를 거절하면 주문은 생성되지 않고, 고객은 체크아웃에 머물며 Square 오류 코드에 따른 짧은 메시지를 보게 됩니다. 예를 들어 카드가 거절되었습니다. 다른 카드나 결제 수단을 사용해 주세요., 카드 보안 코드(CVV)가 올바르지 않습니다. 확인 후 다시 시도해 주세요. 또는 은행에서 추가 인증(3-D Secure)이 필요합니다. 카드를 다시 입력하고 인증을 완료해 주세요. 장바구니는 유지되며, 고객은 다른 카드로 다시 시도할 수 있습니다. 기술적인 원인은 로그에 기록됩니다.

이 모듈은 즉시 매입되는 카드 결제만 지원합니다. 저장된 카드나 고객 프로필, 구독, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH, Square 기프트카드를 지원하지 않으며, 승인 전용 결제, Square 웹훅, Square와의 상품 또는 재고 동기화도 지원하지 않습니다. 분쟁은 Square Dashboard에서 관리합니다.

주문 및 환불

주문 상태

No order yet: 카드가 거절되었거나, Square의 응답이 유실되었고 결제를 찾지 못한 경우입니다. 장바구니만 존재합니다.

Payment accepted: Square가 장바구니 총액과 일치하는 COMPLETED 결제를 확인했습니다. 결제는 Square 결제 ID를 거래 ID로 하여 기록되며, 메모에는 결제 ID, 카드 브랜드와 끝 4자리, 모드(sandbox 또는 live)가 표시됩니다.

Square payment on hold: Square가 COMPLETED가 아닌 결제(예: APPROVED)로 응답했거나, 금액, 통화, 참조 번호 또는 위치가 다른 경우입니다. Square 결제 검토 필요 메모에는 결제 ID, 상태, 금액이 표시됩니다. COMPLETED 결제는 Square가 청구한 금액으로 주문에 기록됩니다. 이 상태는 결제 중에 장바구니가 변경된 경우와, Square의 응답이 유실되어 확인할 수 없었던 경우에도 사용됩니다(이 경우 결제는 기록되지 않습니다). 발송 전에 Square Dashboard에서 결제를 확인하세요.

Refunded: 결제가 모듈을 통해 전액 환불되었습니다.

이미 주문이 있는 장바구니에 두 번째 결제가 들어오면 주문은 변경되지 않습니다. 메모에서 이를 확인하고 중복 결제를 Square Dashboard에서 환불하라는 안내가 표시됩니다.

Square 블록

주문 페이지에는 Square 블록이 표시되며, 여기에는 Square 결제 ID(Square Dashboard의 결제로 연결되는 링크), Square 상태, 카드 브랜드와 끝 4자리, Paid / order / refunded 금액, 환경과 위치, Square 영수증 링크, sandbox 결제를 나타내는 Sandbox 배지, 환불 내역, 주문의 Square notes가 포함됩니다. 카드 번호는 저장되지 않습니다.

환불

Square 블록에 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via Square를 클릭합니다. 이 금액을 Square를 통해 환불하시겠습니까? 이 작업은 되돌릴 수 없습니다. 질문을 확인합니다. 전액 및 부분 환불이 지원됩니다. 주문을 편집할 권한이 필요합니다. 환불은 Square가 청구한 금액과 통화로 이루어지므로, 금액이 일치하지 않는 경우 주문 총액이 아니라 고객이 실제로 지불한 금액까지 환불할 수 있습니다. 환불은 결제가 이루어진 환경(sandbox 또는 운영)과 위치로 전송되므로, 해당 모드의 Access Token이 설정되어 있어야 합니다. 환불 요청은 멱등성을 갖으며, Square가 응답하지 않으면 한 번 재시도됩니다. Square가 수락한 환불(PENDING 또는 COMPLETED 상태)은 Square 환불 ID와 함께 환불 내역과 메모에 추가됩니다. Square가 거부하면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 전액 환불은 주문을 Refunded 상태로 바꿉니다. 부분 환불은 상태를 변경하지 않습니다.

모듈은 크레딧 슬립을 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Square를 통해 돈을 돌려주지 않습니다. Square는 환불을 자체적으로 완료합니다. 나중에 Square가 거부한 환불은 다시 보고되지 않으며, Square Dashboard에서 이루어진 환불은 PrestaShop에 나타나지 않습니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Square Gateway는 Modules > Module Manager > VibeFox Square Gateway > Configure 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 그러면 블록에 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: presta-payment-square 줄과 vibefox.net 계정을 여는 Manage licenses and domains in your account 링크가 있습니다. 키를 변경할 수 있는 사람은 이 모듈의 Configure 권한이 있는 직원뿐입니다. 블록의 텍스트는 관리자 페이지 언어를 따릅니다(영어와 러시아어 포함).

키가 승인되지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜가 붙은 License expired on. 쇼핑몰 주소를 변경하거나 계정에서 도메인 슬롯을 해제한 후에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 기본 쇼핑몰의 도메인이며, 멀티스토어 설정에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. 슬롯은 vibefox.net 계정에서 해제하세요.

유효한 키가 없으면 Square는 체크아웃에서 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. PrestaShop 스토어프런트는 사용자가 관리자 페이지에 로그인했는지 알 수 없으므로, 결제 수단은 사용자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 결제 완료된 주문은 결제 완료 상태를 유지하며, 환불도 계속 작동합니다.

라이선스가 만료되어도 모듈은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 관리자 페이지에서 작업하는 동안 상태가 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 후에는 일주일에 한 번입니다. cron 작업은 필요하지 않습니다. 모듈을 제거하거나 초기화하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

체크아웃에 Square가 나타나지 않습니다: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 Application ID, Access Token, Location ID가 입력되어 있는지 확인하세요. 장바구니 통화가 USD, CAD, AUD, JPY, GBP 또는 EUR이며 Square 위치의 통화와 같은지 확인하세요. 설정 페이지는 이러한 문제마다 경고를 표시합니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객의 국가, 고객 그룹에 대해 허용되어 있는지 확인하세요.

카드 양식이 로드되지 않습니다: 고객에게 카드 양식을 로드할 수 없습니다. 페이지를 새로 고치거나 다른 결제 수단을 선택해 주세요. 가 표시됩니다. Application ID와 Location ID가 선택된 모드에 속하는지 확인하세요(sandbox ID는 sandbox-로 시작합니다). 고객이 너무 일찍 클릭하면 카드 양식을 아직 로드하는 중입니다. 잠시 기다린 후 다시 시도해 주세요. 가 표시됩니다.

저장 후 결제 수단이 사라졌습니다: Square 위치의 통화가 장바구니 통화와 다릅니다. 쇼핑몰 통화에 해당하는 Square 위치의 Location ID를 입력하고 다시 저장하세요. 확인이 성공하면 결제 수단이 다시 표시됩니다.

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

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

고객이 결제 제공업체로부터 확인을 받지 못했다는 메시지를 보았습니다: Square가 응답하지 않았고 아직 결제를 찾지 못했습니다. Square Dashboard에서 이 위치의 결제를 확인하세요(참조 = 장바구니 ID). 고객이 다시 시도하면 모듈은 먼저 이전 결제를 찾아, 다시 청구하는 대신 그 결제로 주문을 생성합니다.

고객이 결제는 접수되었으나 주문을 자동으로 완료하지 못했다는 메시지를 보았습니다: 카드는 청구되었지만 PrestaShop이 주문을 생성하지 못했습니다(예: 그 순간 모듈이 비활성화되어 있었던 경우). 로그를 확인한 후, 주문을 수동으로 생성하거나 Square Dashboard에서 결제를 환불하세요.

주문이 Square payment on hold 상태입니다: Square 블록의 메모를 읽으세요(주문 상태 참조). Square Dashboard에서 결제를 확인한 뒤 주문을 처리하거나 결제를 환불하세요.

모드 관련 메시지와 함께 환불이 실패합니다: 결제는 sandbox 또는 live 모드에서 이루어졌고, 해당 모드의 Access Token이 설정되어 있지 않습니다. 토큰을 입력하고 다시 시도하세요.

기타 오류: Debug log를 켜고 모듈 페이지의 Log 필드를 확인하세요.

제거

Modules > Module Manager로 이동하여 VibeFox Square Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data on uninstall이 켜져 있으면 게이트웨이 설정과 로그 파일이 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. 주문의 Square 결제와 환불, 그리고 Square payment on hold 주문 상태는 항상 유지되므로, 이전에 결제된 주문은 재설치 후에도 환불할 수 있습니다. 기존 주문은 결제 메모, Square 결제 ID, 거래 ID를 그대로 유지합니다.

Square는 각 소유자의 상표입니다. 이 모듈은 Square와 제휴하거나 Square의 승인을 받은 것이 아닙니다.