VibeFox Tap for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

쇼핑몰 통화: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR 또는 USD. 다른 통화의 장바구니에서는 체크아웃에 이 결제 수단이 표시되지 않습니다.

쇼핑몰의 인터넷 접근: Tap은 결제 결과를 쇼핑몰의 웹훅으로 보내므로, 사이트가 인터넷에서 접근 가능해야 합니다. 웹훅 URL은 모든 결제와 함께 전송되며, Tap 대시보드에서 별도로 설정할 필요가 없습니다.

Tap 계정: Tap 대시보드(goSell, API 자격 증명)의 API 키가 필요합니다. 테스트 키는 pk_test_ / sk_test_로, 운영 키는 pk_live_ / sk_live_로 시작합니다. 시크릿 키는 항상 필요하며, 퍼블리셔블 키는 팝업에만 필요합니다. 제공되는 결제 수단(mada, KNET, Benefit 등)과 Apple Pay 도메인 인증은 Tap 계정에서 설정합니다.

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

설치

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

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

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

4. Tap 테스트 및 운영 키를 입력하고, 결제 작업, 체크아웃 방식, Tap 페이지 언어를 선택합니다(설정 항목 참조).

5. Enable / Disable을 켜고 Save를 클릭합니다. Tap 테스트 카드로 확인한 다음 Test mode를 끕니다.

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

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Tap Payments > Configure. 각 섹션에는 자체 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 입력란 위에 페이지는 Test mode is on: payments use your Tap test keys and no real money is charged. 또는 Live mode: real payments are accepted.를 표시합니다. 또한 현재 모드의 키가 없을 때(이 경우 체크아웃에 결제 수단이 표시되지 않음)와 쇼핑몰 기본 통화가 Tap에서 제공되지 않을 때 경고합니다.

저장할 때 입력란에 맞지 않는 접두사를 가진 키는 저장되지 않습니다. 이전 값이 유지되고 나머지 설정은 저장되며, Test secret key was not saved: a Tap key for this field starts with "sk_test_".와 같은 메시지가 표시됩니다. 예를 들어 테스트 입력란에 운영 키를 넣으면 거부됩니다. 빈 Title은 허용되지 않습니다: 페이지에 Enter a title for the payment method.가 표시되며 아무것도 저장되지 않습니다.

Tap Payments

섹션 제목에는 현재 모드의 TEST 또는 LIVE도 표시됩니다.

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

Title: 체크아웃에 표시되는 결제 수단 이름입니다. 주문에도 결제 수단 이름으로 저장됩니다. 기본값: Tap Payments. 필수.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Tap API 키

키는 Tap 대시보드(goSell, API 자격 증명)에서 찾을 수 있습니다. 테스트 키는 pk_test_ / sk_test_로, 운영 키는 pk_live_ / sk_live_로 시작합니다.

Test mode: 테스트 키를 사용하며 실제 금액은 청구되지 않습니다. 결제, 상태 조회, 캡처, 환불은 항상 결제가 이루어진 모드의 키를 사용합니다. 따라서 운영으로 전환한 후에도 테스트 결제는 테스트 키로 확인되고 환불됩니다. 기본값: 켬. 켜져 있는 동안 고객에게는 결제 수단 아래에 Test mode: no real payment will be made.가 표시됩니다.

Test publishable key: pk_test_로 시작합니다. 팝업에 필요합니다.

Test secret key: sk_test_로 시작합니다.

Live publishable key: pk_live_로 시작합니다. 팝업에 필요합니다.

Live secret key: sk_live_로 시작합니다.

Merchant ID: 선택 사항입니다. Tap 가맹점 ID입니다. Tap이 특정 가맹점 계정으로 결제를 라우팅하도록 요청한 경우에만 필요합니다.

저장된 시크릿 키는 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요. 퍼블리셔블 키는 공개되는 키이므로 계속 표시됩니다.

Clear saved secrets: 시크릿 키에 체크하고 Save를 클릭하면 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

결제

Payment action: 고객이 결제할 때 금액이 어떻게 처리되는지를 정합니다.

Checkout type: 고객이 결제하는 위치입니다.

Tap page language: English(기본값) 또는 Arabic.

결제 알림(웹훅)

Tap은 결제 결과를 이 섹션의 Webhook URL에 표시된 URL로 전송합니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_tap_payment_gateway/webhook와 같은 형태이며, /en/ 같은 언어 코드가 포함될 수 있습니다. 이 URL은 모든 결제와 함께 전송되므로 Tap 대시보드에서 설정할 필요가 없습니다. 인터넷에서 접근 가능한지만 확인하세요(방화벽이나 HTTP 인증으로 차단되지 않아야 합니다). 각 알림은 hashstring 서명(HMAC-SHA256, 결제가 이루어진 모드의 시크릿 키 사용)으로 검증됩니다. 유효한 서명이 없는 웹훅은 거부됩니다. 서명된 알림이라도 그 자체로 신뢰되지는 않습니다. 모듈은 주문을 생성하거나 변경하기 전에 Tap API에서 결제를 다시 읽습니다. 웹훅이 작동하지 않으면, 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 주문이 생성됩니다.

고급

Debug log: 결제 이벤트를 모듈 폴더의 logs/tap_p_debug.log.php에 기록합니다. 이 파일은 웹에서 읽을 수 없습니다. 오류와 경고는 항상 기록되며, 모든 결제 이벤트도 기록하려면 이 옵션을 켜세요. 로그에는 키, 카드 정보, 고객 데이터가 절대 포함되지 않습니다. 기본값: 끔.

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

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. 주문의 결제 기록은 보존됩니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Tap Payments)을 선택하고 주문을 확정합니다. 이 시점에는 아직 주문이 없습니다.

Tap payment page: 모듈은 장바구니 통화로 장바구니 합계에 대한 Tap 청구(Authorize only 모드에서는 승인)를 만들고, 설명에 Cart #와 장바구니 번호를 넣어 고객을 Tap 결제 페이지로 보냅니다. 고객의 이름, 이메일, 전화번호가 Tap에 전달됩니다. 고객은 그곳에서 카드, mada, KNET, Benefit, Apple Pay, Google Pay 중에서(Tap 계정에서 활성화된 항목) 선택하여 결제합니다. Tap이 결제를 시작할 수 없으면 고객은 체크아웃에 머무르며 The Tap payment could not be started. Please try again or choose another payment method.를 보고, 사유는 로그에 기록됩니다.

Tap checkout popup: 고객은 모듈의 Tap payment 페이지로 이동하며, 그곳에서 Tap 결제 양식이 열립니다. 페이지에는 Pay on the Tap payment page instead 링크도 표시됩니다. 창을 닫으면 Pay now 버튼이 다시 엽니다. 양식을 불러올 수 없으면 고객에게 Tap 결제 페이지를 사용하도록 안내합니다. 페이지를 새로 고쳐도 같은 결제 시도가 재사용됩니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Tap이 확인한 후에만 결제 완료로 표시됩니다. 모듈은 결제의 모드 키로 Tap API에서 결제를 읽고, 그 결제가 이 장바구니를 가리키며 해당 체크아웃에서 시작되었는지 확인한 뒤, 금액과 통화를 장바구니와 비교합니다. 반환 주소에 있는 Tap ID만으로는 주문이 생성되지 않습니다. 웹훅도 백그라운드에서 같은 확인을 합니다. 그 다음 주문이 생성되고, 고객은 표준 주문 확인 페이지를 봅니다. 승인된 결제의 경우 페이지에 Your payment has been authorized. We will process the order as soon as the payment is captured.가 표시되고, 보류된 주문의 경우 Your payment is being reviewed. We will contact you if anything else is needed.가 표시됩니다.

고객이 돌아왔을 때 Tap이 아직 결제를 확인하지 않았다면 Payment confirmation 페이지가 표시되며, We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. 메시지와 Check again, Back to checkout 버튼이 나타납니다. 웹훅이 도착하는 즉시 주문이 생성됩니다.

결제가 거절되거나, 중단되거나, 취소되면 주문은 생성되지 않습니다. 고객은 Your payment was not completed. Please try again or choose another payment method.와 함께 체크아웃으로 돌아갑니다(Tap이 사유를 제공하는 경우 그 사유 포함). 완료되지 않은 결제에는 The payment was not completed. You can try again or choose another payment method.가 표시됩니다. 장바구니는 유지되며 다시 결제할 수 있습니다.

체크아웃의 기타 메시지: 장바구니 통화가 지원되지 않을 때 통화 코드와 함께 Tap does not accept payments in, 그리고 The order total must be greater than zero to pay with Tap.

웹훅은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한의 영향을 받지 않습니다.

모듈에는 저장된 카드나 토큰화, 구독, 체크아웃 페이지에 내장된 카드 입력란이 없습니다. Capture Tap payment는 항상 주문 총액을 캡처하며, 부분 캡처는 지원하지 않습니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 Tap으로 이동했지만 결제하지 않았거나, Tap이 아직 결제를 확인하지 않은 상태입니다. 장바구니만 존재합니다.

Payment accepted: Tap이 캡처된 결제를 확인했습니다. 결제는 Tap 청구 ID(chg_...)를 거래 ID로 기록하며, 메모에는 금액, 청구 ID, 결제 수단, 그리고 (테스트 모드의 경우) 테스트 결제임이 표시됩니다.

Tap payment authorized: 결제는 승인만 되었으며 캡처 또는 취소를 기다리고 있습니다.

Tap payment on hold: 결제된 금액 또는 통화가 장바구니와 달랐거나(Tap: amount/currency mismatch — manual review required.), 주문이 취소된 후에 결제가 도착했습니다. 메모에 설명이 나옵니다. 주문을 확인하고 처리하거나 결제를 환불하세요.

Canceled: 승인이 Void Tap authorization으로 취소되어 예약된 금액이 해제되었습니다.

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

실패한 시도는 결제 완료, 승인 또는 취소된 주문을 절대 변경하지 않습니다. 이미 결제된 주문에 두 번째 성공 결제가 도착해도 주문은 변경되지 않습니다. 메모에는 중복 결제라는 내용과 함께 Tap 대시보드에서 환불하라는 안내가 기록됩니다. 장바구니와 관련되어 있지만 해당 체크아웃에서 시작되지 않은 결제는 메모만 남깁니다.

Tap 결제 블록

주문 페이지에는 Tap payment 블록이 표시되며, Tap ID, 승인과 청구, 모드(테스트 결제에는 Test mode 배지), 결제 상태와 수단, Charged / refunded, 환불 내역, 장바구니의 결제 시도, 주문의 Payment notes가 포함됩니다. 블록의 버튼은 주문 페이지에서 바로 작동합니다. 모듈 설정 접근 권한이 아니라 주문 편집 권한이 필요합니다.

캡처 및 취소

Authorize only 모드에서는 Tap payment authorized 상태의 주문을 엽니다. Capture Tap payment(버튼에 주문 총액 표시)은 Capture the reserved funds of this order through Tap? 확인 후 주문 총액을 캡처합니다. 그 후 주문은 Payment accepted가 됩니다. Void Tap authorization은 Release the reserved funds? The order will be canceled.를 묻고, 금액을 해제하며 주문을 Canceled로 설정합니다. Tap이 작업을 거부하면 블록에 오류가 표시되며 메모에도 추가됩니다. 승인이 Tap 대시보드에서 직접 캡처되면 웹훅이 주문을 결제 완료로 표시합니다. 이러한 결제의 환불은 Tap 대시보드에서 해야 합니다.

환불

Tap payment 블록에 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 뒤 Refund via Tap을 클릭합니다. Refund this amount through Tap? This cannot be undone. 확인 창에서 확인하세요. 캡처된 Tap 청구에 대해 전액 및 부분 환불이 지원됩니다. 주문이 나중에 수정되었더라도 Tap이 실제로 청구한 금액과 통화까지 환불할 수 있습니다. 환불은 결제가 이루어진 모드의 시크릿 키로 전송되므로, 해당 모드의 키가 설정되어 있어야 합니다. Tap이 승인한 환불은 Tap 환불 ID와 상태와 함께 환불 내역과 메모에 추가됩니다. Tap이 거부하면 블록에 오류가 표시되고 환불은 기록되지 않습니다. 전액 환불은 주문을 Refunded로 설정하며, 부분 환불은 상태를 바꾸지 않습니다. 승인된 주문의 환불은 승인이 캡처된 후에 가능합니다. 금액 또는 통화 불일치로 보류된 주문은 Tap 대시보드에서 환불합니다.

모듈은 크레딧 전표를 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Tap을 통해 돈을 돌려주지 않습니다. Tap 대시보드에서 이루어진 환불은 PrestaShop에 나타나지 않습니다.

라이선스 키

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

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

키 하나는 도메인 하나에서 작동합니다. 기본 쇼핑몰의 도메인이며, 다중 쇼핑몰 설정에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

Tap Payments가 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 시크릿 키가 있는지(Checkout type이 팝업이면 퍼블리셔블 키도) 확인하세요. 장바구니 통화가 AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD 중 하나인지 확인하세요. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하세요. 설정 페이지에는 누락된 키와 지원되지 않는 쇼핑몰 통화에 대한 경고가 표시됩니다.

결제는 되었지만 주문이 생성되지 않음: 웹훅이 쇼핑몰에 도달하지 못하고 있습니다. Webhook URL에 표시된 URL이 인터넷에서 접근 가능한지(방화벽이나 HTTP 인증이 없어야 함) 확인하고, Log 필드에서 응답을 보려면 Debug log를 켜세요. 고객이 Tap에서 돌아왔을 때도 주문이 생성됩니다.

Webhook answers invalid signature: 알림이 결제 모드의 시크릿 키로 서명되지 않았습니다. 설정의 시크릿 키를 확인하세요.

Webhook answers gateway not configured: 결제 모드(테스트 또는 운영)의 시크릿 키가 비어 있습니다. 입력하세요.

Webhook answers verification failed: 결제를 확인하기 위해 Tap API에 연결할 수 없었습니다. Tap이 나중에 웹훅을 다시 시도합니다.

Webhook answers order not found: 알림이 이 쇼핑몰에 Tap 결제 시도가 없는 장바구니를 가리킵니다.

Webhook answers busy, retry later or order could not be updated, retry later: 같은 순간에 다른 요청이 주문을 확인하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화된 경우). Tap이 웹훅을 다시 시도합니다. 사유는 Log 필드에서 확인하세요.

키가 저장되지 않음: 키는 해당 입력란의 접두사로 시작해야 합니다: pk_test_, sk_test_, pk_live_ 또는 sk_live_.

고객에게 The Tap payment could not be started가 표시됨: 모듈 페이지의 Log 필드를 확인하세요. 잘못된 키나 거부된 요청이 그곳에 기록됩니다.

고객에게 We could not match this payment to an order가 표시됨: 해당 결제는 이 장바구니에 속하지 않거나 해당 체크아웃에서 시작되지 않았습니다. 돈이 빠져나갔다면 Tap 대시보드에서 결제를 확인하세요.

주문이 Tap payment on hold 상태: Tap payment 블록의 메모를 읽으세요. 결제된 금액 또는 통화가 장바구니와 일치하지 않았거나, 주문이 취소된 후에 결제가 도착했습니다.

환불이 모드 관련 메시지와 함께 실패: 결제는 테스트 또는 운영 모드에서 이루어졌는데 해당 모드의 시크릿 키가 설정되어 있지 않습니다. 키를 입력하고 다시 시도하세요. 블록에 캡처된 Tap 청구를 찾을 수 없다고 나오면 Tap 대시보드에서 결제를 환불하세요.

개발자 후크: actionWcpTapChargePayload, actionWcpTapSupportedCurrencies, actionWcpTapCurrencyDecimals 후크를 사용하면 개발자가 결제 요청, 지원 통화, 통화의 소수점 자릿수를 변경할 수 있습니다.

제거

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

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