VibeFox Braintree for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Braintree 계정: Braintree 계정의 Merchant ID, Public Key, Private Key가 필요합니다. 이 정보는 Braintree Control Panel(샌드박스: sandbox.braintreegateway.com, 운영: www.braintreegateway.com)에서 톱니바퀴 아이콘, API, API Keys 아래에 있습니다. 샌드박스 계정과 운영 계정은 키가 서로 다릅니다. 3-D Secure를 Disabled로 설정하지 않는 한, Braintree 가맹점 계정에서 3-D Secure가 활성화되어 있어야 합니다. 웹훅은 필요하지 않습니다. 카드 결제는 즉시 확인됩니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서만 사용할 수 있습니다.

설치

1. 백오피스에서 Modules > Module Manager로 이동하고 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

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

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

4. Braintree Control Panel의 Merchant ID, Public Key, Private Key를 샌드박스 또는 운영 필드에 복사합니다.

5. Enable/Disable을 켜고 Save를 클릭합니다. Sandbox mode는 켜 둔 채로 Braintree 샌드박스 테스트 카드로 테스트 주문을 한 건 합니다. 그런 다음 Sandbox mode를 끄면 운영 자격 증명으로 실제 결제를 받을 수 있습니다.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Braintree payment authorized와 Braintree payment on hold. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. 이 설정은 Payment > Preferences에서 제한할 수 있습니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Braintree Gateway > Configure. 각 섹션에는 별도의 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 결제 수단이 활성화되어 있지만 선택한 환경의 Merchant ID, Public Key 또는 Private Key가 비어 있으면, 채워질 때까지 결제 수단이 체크아웃에서 숨겨진다는 경고가 페이지에 표시됩니다. 샌드박스 모드가 켜져 있는 동안에는 페이지에 Sandbox mode is on: test payments, no real money.가 표시됩니다.

Braintree

Enable/Disable: Enable Braintree card payments는 결제 수단을 켜거나 끕니다. 기본값: off.

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 문구입니다. 기본값: Pay securely with your credit or debit card via Braintree.

API 자격 증명

Braintree Control Panel(샌드박스 또는 운영)에 로그인한 후 톱니바퀴 아이콘을 클릭하고, 이어서 API와 API Keys를 클릭합니다. Public Key와 Private Key가 여기에 나열되며, Merchant ID도 같은 페이지에 표시됩니다. 이 페이지에는 선택한 환경의 자격 증명 필드만 표시되며, 두 세트 모두 저장된 상태로 유지됩니다.

Sandbox mode: Braintree 샌드박스를 사용합니다(테스트 결제, 실제 금액 청구 없음). 기본값: on. 끄면 운영 자격 증명으로 실제 결제를 받습니다. 환불, 캡처, 무효화는 항상 주문이 결제된 환경을 사용합니다. 켜져 있는 동안 고객에게는 결제 수단 아래에 SANDBOX / TEST MODE — no real money is charged.가 표시됩니다.

Sandbox Merchant ID와 Live Merchant ID: 샌드박스 또는 운영 계정의 Merchant ID입니다.

Sandbox Public Key와 Live Public Key: 해당 계정의 Public Key입니다.

Sandbox Private Key와 Live Private Key: 해당 계정의 Private Key입니다. 저장된 Private Key는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오.

Sandbox merchant account ID(s)와 Live merchant account ID(s): 선택 사항입니다. Braintree는 가맹점 계정의 통화로 청구합니다. 비워 두면 기본 가맹점 계정을 사용합니다. ID 하나(예: mystore_EUR)를 입력하거나, 통화별로 입력합니다: EUR=mystore_EUR, USD=mystore_USD. 청구된 통화가 주문 통화와 일치하지 않으면 거래는 자동으로 무효화되며, 고객에게는 청구되지 않습니다.

Clear saved private keys: Sandbox Private Key 또는 Live Private Key에 체크한 뒤 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

결제

Transaction type: 카드를 청구하는 방식입니다.

3-D Secure: EEA와 영국에서는 대부분의 카드 결제에 3-D Secure 2(강력한 고객 인증)가 필수입니다. 이 기능은 Braintree 계정에서도 활성화되어 있어야 합니다(3-D Secure 구성 오류로 결제가 실패하면 Braintree 지원팀에 문의하십시오).

3-D Secure 결과는 카드가 청구되기 전에 브라우저뿐 아니라 서버에서도 확인됩니다.

고급

Debug log: API 호출과 결제 단계도 모듈 폴더의 logs/wc_btg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 옵션이 꺼져 있어도 오류는 항상 기록됩니다. 로그에는 API 키, 카드 또는 고객 데이터가 절대 포함되지 않습니다. 기본값: off.

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

Delete data on uninstall: 켜면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. Braintree 거래, 환불, 주문 상태는 항상 유지되므로, 재설치 후에도 이전에 결제된 주문을 환불, 캡처 또는 무효화할 수 있습니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Credit / debit card)을 선택하고, 결제 옵션 안의 Braintree 양식에 카드를 입력합니다. 이 양식은 체크아웃 페이지에서만 Braintree로부터 로드되며, 쇼핑몰의 언어를 사용합니다. 3-D Secure가 켜져 있으면 고객은 주문을 할 때 카드사의 인증을 완료합니다. 장바구니 합계, 이메일, 청구지 주소가 이 인증에 전달됩니다.

그런 다음 모듈은 일회용 토큰에 대해 장바구니 통화로 장바구니 합계를 Braintree API를 통해 청구하며, Braintree에서 주문 ID로 장바구니 번호를 사용합니다. 이 시점 이전에는 주문이 존재하지 않습니다. 청구된 금액과 통화는 장바구니와 대조됩니다. 주문은 Braintree가 결제를 승인한 후에만 생성되며, 고객에게는 PrestaShop의 표준 주문 확인 페이지가 표시됩니다.

결제가 실패하면 주문은 생성되지 않으며, 그 사유는 모듈 로그에 기록됩니다. 고객은 결제 단계에 머무르며 다음과 같은 메시지를 보게 됩니다. 예: Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. 또는 The card security code or billing address could not be verified. Please check your details and try again. 고객은 즉시 다시 시도할 수 있습니다. 청구된 통화나 금액이 장바구니와 일치하지 않으면 거래는 무효화되며, 고객에게는 This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.가 표시됩니다.

같은 장바구니에 두 번 청구되는 일은 없습니다. 결제가 진행 중일 때 두 번째로 제출하면 This order is already being paid. Please wait a moment and check your e-mail before trying again.가 표시됩니다. 카드에는 청구되었지만 PrestaShop이 주문을 완료하지 못한 경우, 고객에게는 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.가 표시됩니다. 같은 장바구니에 대한 다음 시도는 다시 청구하지 않고 저장된 거래로부터 주문을 생성합니다.

모듈은 카드 결제만 받습니다. 저장된 카드, 구독이나 정기 결제, PayPal, Venmo, Apple Pay, Google Pay 또는 지역 결제 수단은 지원하지 않으며, Braintree 웹훅도 사용하지 않습니다.

주문과 환불

주문 상태

아직 주문 없음: 결제가 이루어지지 않았거나 거절되었습니다. 장바구니만 존재합니다.

Payment accepted: 카드에 청구되었거나(Sale), 승인이 캡처되었습니다. 결제는 Braintree 거래 ID와 함께 기록되며, 주문 메시지의 비공개 메모에 금액, 거래 ID, 3-D Secure 결과가 표시됩니다.

Braintree payment authorized: 금액은 승인만 되었습니다(Authorize only). 캡처하기 전까지는 결제가 기록되지 않습니다.

Braintree payment on hold: Braintree가 예상하지 못한 거래 상태를 반환했거나, 잘못된 통화 또는 금액으로 청구된 건을 자동으로 무효화할 수 없었습니다. 메모에는 Braintree Control Panel에서 무엇을 확인해야 하는지 설명되어 있습니다.

Canceled: 승인이 무효화되었습니다.

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

이미 생성된 주문에 다른 거래가 도착해도 주문은 변경되지 않습니다. 메모에는 Braintree Control Panel에서 이를 확인하고 무효화하거나 환불하라는 안내가 표시됩니다.

Braintree payment 블록

주문 페이지에는 Braintree payment 블록이 표시되며, 이 블록에는 거래 ID(해당 환경의 Braintree Control Panel 거래로 연결되는 링크), 거래 상태, 금액과 가맹점 계정, 3-D Secure 결과, 청구된 금액과 환불된 금액, 샌드박스 결제에 대한 Sandbox 배지, 환불 내역이 포함됩니다. 블록의 버튼은 주문을 편집할 권한이 있어야 하며, Modules 페이지에 접근할 필요는 없습니다.

캡처와 무효화

상태가 Braintree payment authorized인 주문의 경우, Capture Braintree payment를 클릭하면 주문 총액이 청구되고, Void Braintree authorization을 클릭하면 보류된 금액이 해제됩니다. 캡처하면 주문이 Payment accepted로 설정되고 결제가 기록됩니다. 무효화하면 주문이 Canceled로 설정됩니다. 작업이 실패하면 오류가 블록에 표시되고 주문 메모에도 추가됩니다.

환불

Braintree payment 블록에서 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via Braintree를 클릭합니다. Refund this amount through Braintree? This cannot be undone. 확인 메시지에서 승인하십시오. 전액 및 부분 환불을 모두 지원합니다. 환불은 Braintree가 청구한 금액과 통화로 이루어지므로, 금액이나 통화가 일치하지 않은 경우에는 고객이 실제로 결제한 금액까지만 환불할 수 있습니다. Braintree는 정산이 완료된 거래만 환불하며, 보통 24시간 이내에 처리됩니다. 정산 전에는 전액 환불이 무효화로 처리되며, 이때 부분 환불은 정산을 기다리라는 메시지와 함께 실패합니다. 환불은 결제가 이루어진 환경(샌드박스 또는 운영)으로 전송되므로, 해당 환경의 자격 증명이 설정되어 있어야 합니다. Braintree가 환불을 수락하지 않으면 블록에 오류가 표시되며, 환불은 기록되지 않습니다. 성공한 환불은 환불 내역과 메모에 추가됩니다. 전액 환불은 주문을 Refunded로 설정하며, 부분 환불은 상태를 변경하지 않습니다.

모듈은 크레딧 슬립(credit slip)을 만들지 않습니다. 주문 페이지의 PrestaShop 표준 환불 버튼은 Braintree를 통해 돈을 돌려주지 않습니다. 분쟁(차지백), 정산 거절, Braintree Control Panel에서 직접 이루어진 환불은 PrestaShop과 동기화되지 않습니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Braintree Gateway는 Modules > Module Manager > VibeFox Braintree Gateway > Configure의 맨 위, 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하세요. 그 후 블록에는 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: presta-payment-braintree 줄과 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 계정에서 슬롯을 해제하세요.

활성 키가 없으면 체크아웃에서 고객에게 Braintree가 표시되지 않습니다. 그래도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.를 보게 됩니다. PrestaShop 스토어프런트는 백오피스에 로그인되어 있다는 사실을 알지 못하므로, 결제 방법은 관리자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 계속 확인되며, 캡처, 무효화, 환불도 작동합니다.

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

문제 해결

체크아웃에 Braintree가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 환경에 Merchant ID, Public Key, Private Key가 있는지 확인하십시오. 키가 없으면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

카드에는 청구되었지만 주문이 생성되지 않음: 카드 결제는 웹훅 없이 즉시 확인됩니다. 모듈 페이지의 Log 필드를 확인하십시오. 로그에 Braintree의 응답이 유실되었다고 나오면, 다른 결제를 받기 전에 Braintree Control Panel에서 장바구니 번호를 주문 ID로 사용하는 거래가 있는지 확인하십시오. 청구 후 주문을 생성하지 못했다면, 같은 장바구니에 대한 다음 결제 시도에서 다시 청구하지 않고 주문이 생성됩니다.

카드 양식에 Could not initialize payment form이 표시됨: 선택한 환경의 키가 잘못되었거나, 해당 계정에 가맹점 계정 ID가 존재하지 않습니다. 키와 가맹점 계정 ID를 확인한 후 페이지를 새로고침하십시오.

모든 결제에서 3-D Secure가 실패함: Braintree 가맹점 계정에서 3-D Secure가 활성화되어 있어야 합니다. Braintree 지원팀에 문의하거나, 3-D Secure를 Disabled로 설정하십시오(SCA가 의무인 EEA와 영국에서는 권장하지 않습니다).

고객에게 주문 통화로는 결제를 처리할 수 없다고 안내됨: Braintree는 가맹점 계정의 통화로 청구했습니다. 현재 환경의 가맹점 계정 필드에 장바구니 통화에 해당하는 가맹점 계정 ID를 입력하십시오.

고객에게 The order total must be greater than zero to pay by card가 표시됨: 쿠폰 적용 등으로 장바구니 합계가 0입니다. 이러한 주문은 카드로 결제할 수 없습니다.

결제 직후 부분 환불이 실패함: Braintree는 정산이 완료된 거래만 환불할 수 있으며, 보통 24시간 이내입니다. 지금 거래를 무효화하려면 전액을 환불하거나, 정산 후에 부분 환불을 진행하십시오.

환경과 관련된 메시지와 함께 환불, 캡처 또는 무효화가 실패함: 결제는 샌드박스 또는 운영 환경에서 이루어졌지만, 해당 환경의 자격 증명이 설정되지 않았습니다. 자격 증명을 입력한 후 다시 시도하십시오.

제거

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

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