VibeFox Kushki for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 이전 버전의 PHP에서는 모듈 설치가 거부됩니다.

통화: USD(에콰도르) 또는 COP(콜롬비아). 다른 통화의 장바구니에서는 체크아웃에 해당 결제 방법이 표시되지 않습니다.

HTTPS: Kushki는 실결제 모드에서 체크아웃이 HTTPS로 제공되어야 합니다.

Kushki 계정: Kushki 테스트(UAT) 계정과 운영 계정의 Public·Private Merchant ID가 필요합니다. 이들은 Kushki Console의 Developers > Credentials에 있습니다. 선택 사항인 웹훅을 사용하려면 각 계정의 웹훅 서명 키도 필요합니다(설정 참조).

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

설치

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

2. 업로드가 끝나면 Configure를 클릭합니다. 나중에 하려면 모듈 목록에서 VibeFox Kushki Payment를 찾아 Configure를 클릭합니다.

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

4. 테스트용 Public·Private Merchant ID를 입력하고 Test mode는 켜진 상태로 둡니다. 선택 사항으로 Kushki Console에서 웹훅을 설정하고 그 서명 키를 붙여 넣습니다(설정 참조).

5. Enable / Disable을 켜고 Save를 클릭한 후 테스트 주문을 합니다. 준비가 되면 운영용 Merchant ID(및 운영용 웹훅 서명)를 입력하고 Test mode를 끕니다.

설치 시 모듈은 Kushki payment on hold 주문 상태를 만듭니다. PrestaShop은 새 결제 모듈을 쇼핑몰의 통화, 국가, 고객 그룹에 할당합니다. Payment > Preferences에서 모듈이 USD 또는 COP, 그리고 에콰도르 또는 콜롬비아에 대해 허용되어 있는지 확인합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Kushki Payment > Configure. 각 섹션에는 전체 페이지를 저장하는 Save 버튼이 있습니다. 필드 위에서 페이지는 결제 방법은 활성화되어 있지만 현재 모드의 Merchant ID가 없는 경우(이때 결제 방법은 체크아웃에서 숨겨짐), 쇼핑몰의 기본 통화가 USD 또는 COP가 아닌 경우, HTTPS 없이 실결제 모드를 사용하는 경우, 현재 모드에 웹훅 서명이 없는 경우에 경고합니다. 테스트 모드가 켜져 있는 동안에는 테스트 모드가 켜져 있습니다: Kushki 테스트 환경이 사용되며 실제 금액은 청구되지 않습니다. 라고 표시됩니다. 결제 방법은 켜져 있지만 현재 모드의 Merchant ID가 없는 상태로 저장하면 설정은 저장되고, 입력하라는 메시지가 표시됩니다. 저장할 때 ID 앞뒤의 공백은 제거됩니다.

Kushki

Enable / Disable: Enable Kushki card payments는 결제 방법을 켜거나 끕니다. 기본값: 꺼짐.

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

Description: 체크아웃에서 카드 양식 위에 표시되는 텍스트입니다. 기본값: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.

API 자격 증명

Kushki Console(Developers > Credentials)에서 Public·Private Merchant ID를 복사합니다. 테스트(UAT) 계정과 운영 계정의 ID는 서로 다릅니다. 테스트 모드는 테스트 ID만, 실결제 모드는 운영 ID만 사용합니다.

Test mode: Kushki 테스트(UAT) 환경을 사용합니다. 테스트 Merchant ID, 테스트 카드 양식, 테스트 API가 함께 사용됩니다. 실제 금액은 청구되지 않으며, 체크아웃에 TEST MODE 배지가 표시됩니다. 기본값: 켜짐. 실제 결제를 받으려면 끕니다. 환불은 항상 결제가 이루어진 환경으로 처리됩니다.

Test Public Merchant ID: Kushki 테스트 계정의 Public Merchant ID입니다. 카드 양식을 불러오는 데 사용됩니다.

Test Private Merchant ID: Kushki 테스트 계정의 Private Merchant ID입니다. 서버에서 결제 청구와 환불에 사용됩니다.

Live Public Merchant ID: Kushki 운영 계정의 Public Merchant ID입니다.

Live Private Merchant ID: Kushki 운영 계정의 Private Merchant ID입니다. 비밀로 관리하십시오.

저장된 Private Merchant ID와 웹훅 서명은 다시 표시되지 않습니다. 필드는 비어 있는 상태로 유지되며 저장됨 — 유지하려면 비워 두십시오. 라고 표시됩니다. 변경하려는 경우에만 새 값을 입력합니다.

Webhook (권장)

결제는 Kushki API 응답으로 즉시 확인되므로 웹훅은 필수가 아닙니다. 웹훅은 응답이 누락된 결제(예: 시간 초과)에 대해 주문을 생성하고, Kushki Console에서 이루어진 취소 및 환불을 알리는 역할도 합니다. Kushki Console(Webhooks)에서 카드 결제용으로 Webhook URL에 표시된 URL을 추가합니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_kushki_payment/webhook 형태이며, /es/ 같은 언어 코드가 붙을 수도 있습니다. URL은 설정에 표시된 그대로 정확히 복사하십시오. 테스트 계정과 운영 계정 모두에 대해 이렇게 하십시오.

모듈은 다음 카드 알림을 처리합니다:

Test webhook signature: Kushki 테스트 계정의 웹훅 서명 키입니다(Console > Webhooks).

Live webhook signature: Kushki 운영 계정의 웹훅 서명 키입니다.

Clear saved secrets: Private Merchant ID 또는 웹훅 서명에 체크하고 Save를 클릭하면 삭제됩니다. 빈 필드는 저장된 값을 유지합니다.

유효한 서명이 없는 웹훅은 거부됩니다. 알림은 결제가 이루어진 모드의 키로 서명되어야 하므로, 테스트 알림이 실결제를 확인하는 일은 없습니다. 서명 키가 없으면 모든 웹훅 알림은 거부되지만, 결제는 API 응답으로 확인되므로 계속 작동합니다.

고급

Debug log: Kushki 요청과 웹훅을 모듈 폴더의 logs/kushki_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류는 항상 기록됩니다. 로그에는 Merchant ID, 카드 토큰, 고객 이메일이 절대 포함되지 않습니다. 기본값: 꺼짐.

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

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 설정과 로그가 삭제됩니다. Kushki 결제 기록(결제 청구 및 환불)과 Kushki payment on hold 주문 상태는 항상 남아 있으므로, 재설치 후에도 이전 주문을 환불할 수 있습니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 방법을 선택합니다(기본값 Credit / debit card (Kushki)). 그 아래에 장바구니 통화로 장바구니 합계가 표시된 Kushki 카드 양식이 나타납니다. 고객은 카드 정보를 입력하고, Kushki 양식이 할부를 제공하면 할부를 선택한 다음, Kushki 양식 안의 결제 버튼을 누릅니다.

PrestaShop의 Place order 버튼은 이용약관을 포함하므로 계속 표시됩니다. 이용약관에 이미 동의한 경우에는 Kushki 결제 버튼 다음에 결제가 자동으로 제출됩니다. 그렇지 않으면 고객은 Kushki에서 카드가 승인되었습니다. 이용약관에 동의한 후 "Place order"를 눌러 결제하십시오. 라는 메시지를 봅니다. 고객이 Kushki 양식을 사용하지 않고 Place order를 누르면 Kushki 양식에 카드 정보를 입력한 후 해당 결제 버튼을 누르십시오. 메시지가 표시됩니다.

그다음 쇼핑몰은 서버에서 카드에 청구합니다. 주문은 Kushki가 티켓 번호와 함께 확인한 후에만 결제 완료로 표시됩니다. 그 후 주문이 생성되고, 고객은 카드 결제가 접수되었습니다. 라는 메시지가 있는 표준 주문 확인 페이지를 봅니다. Kushki가 승인된 금액이나 통화를 보고하면 장바구니와 비교합니다. 보류 중인 주문은 결제를 검토 중입니다. 검토가 완료되는 대로 주문을 업데이트하겠습니다. 라고 표시됩니다.

카드가 거절되면 주문은 생성되지 않으며, 고객은 결제가 거절되었습니다와 Kushki가 알려준 사유와 함께 결제 단계로 돌아가 다른 카드를 시도할 수 있습니다. 네트워크, 키 또는 서버 문제가 있으면 고객은 지금은 결제를 처리할 수 없습니다. 잠시 후 다시 시도하거나 다른 결제 방법을 선택하십시오. 를 봅니다. 기술적 사유는 로그에 기록됩니다. 결제가 처리되는 동안 다시 클릭하면 이 주문의 결제가 이미 처리 중입니다. 잠시 기다린 후 주문 상태를 확인하십시오. 가 표시됩니다.

Kushki 응답이 누락되면(예: 시간 초과) 고객은 일반 메시지를 보지만, 결제 시도는 보관됩니다. 서명된 웹훅이 승인된 결제를 알리면 주문이 생성됩니다. 이미 주문이 있는 장바구니나 주문이 아직 생성되지 않은 승인된 결제는 다시 청구되지 않으며, 고객은 해당 주문의 확인을 봅니다. 웹훅이 도착하기 전에 고객이 다시 결제하면 이는 새 결제이며, 첫 번째 결제의 늦은 승인은 중복 결제 가능성에 대한 메모만 추가합니다.

웹훅은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다. 3-D Secure, 사기 방지 규칙, 제공되는 할부는 Kushki Console에서 설정합니다.

이 모듈은 한 번에 완료되는 카드 결제만 지원합니다. 부분 환불, 저장된 카드나 구독은 지원하지 않으며, 현금, 계좌이체(PSE), 체크카드 리디렉션 결제 및 승인과 캡처의 분리도 지원하지 않습니다.

주문 및 환불

주문 상태

No order yet: 고객이 결제하지 않았거나, 카드가 거절되었거나, Kushki 응답이 누락되었고 웹훅이 아직 도착하지 않았습니다. 장바구니만 존재합니다.

Payment accepted: Kushki가 결제를 확인했습니다(API 응답 또는 웹훅으로). 결제는 Kushki 거래 참조 번호(또는 티켓 번호)를 거래 ID로 하여 기록됩니다. 메모에는 모드, Kushki 티켓 번호, 참조 번호가 표시됩니다.

Kushki payment on hold: Kushki가 티켓 번호 없이 성공을 반환했거나, 장바구니와 다른 금액 또는 통화를 보고했거나, 결제 중에 장바구니가 변경되었습니다. 메모에 이유가 설명되어 있습니다. Kushki Console에서 거래를 확인한 후 주문을 처리하거나 결제를 환불하십시오. 이후 티켓 번호와 일치하는 금액으로 서명된 승인이 도착하면 주문은 Payment accepted 상태로 바뀝니다.

Payment error: 웹훅이 보류 중인 주문의 결제가 거절되었다고 알렸습니다.

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

이미 결제되었거나, 취소되었거나, 환불된 주문에 대해 Kushki가 다른 승인된 결제를 보고하면 주문은 변경되지 않습니다. 메모는 중복 결제 여부를 확인하고 Kushki Console에서 환불하라고 요청합니다. 실결제에 대한 테스트 환경의 웹훅(또는 그 반대)은 메모와 함께 무시됩니다.

Kushki 결제 블록

주문 페이지에는 티켓 번호, 거래 참조 번호, 환경(테스트 결제에는 Test 배지 표시), 결제 상태, 청구된 금액과 주문 합계, 환불 양식, 환불 내역, 주문의 Kushki notes가 포함된 Kushki payment 블록이 표시됩니다.

환불

Kushki는 결제 전액을 환불하므로 전액 환불만 가능합니다. Kushki payment 블록에는 Kushki가 청구한 금액이 이미 입력되어 있습니다. 필요하면 사유를 입력하고 Refund via Kushki를 클릭한 다음, Kushki를 통해 결제 전액을 환불하시겠습니까? 이 작업은 취소할 수 없습니다. 라는 질문을 확인하십시오. 주문을 편집할 권한이 있어야 합니다. 그 밖의 금액에 대해서는 모듈이 금액과 함께 Kushki는 전체 결제만 환불할 수 있습니다. 청구된 전체 금액을 입력하십시오 를 표시하며, 아무것도 전송되지 않습니다. 환불은 Kushki가 청구한 금액과 통화로 이루어지므로, 금액이 일치하지 않는 경우 고객은 주문 합계가 아니라 실제로 청구된 금액을 돌려받습니다. 결제는 한 번만 환불할 수 있습니다.

환불은 결제가 이루어진 모드(테스트 또는 실결제)로 전송되므로, 해당 모드의 Private Merchant ID가 설정되어 있어야 합니다. Kushki가 환불을 수락하지 않으면 블록에 Kushki 코드 및 메시지와 함께 Kushki 환불 실패가 표시되며, 환불은 기록되지 않습니다. 환불이 성공하면 Kushki 환불 티켓과 함께 환불 내역과 메모에 추가되고, 주문은 Refunded 상태로 설정됩니다. 환불에는 티켓 번호가 있는 확인된 Kushki 결제가 필요합니다.

모듈은 크레딧 슬립을 만들지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 Kushki를 통해 돈을 돌려보내지 않습니다. Kushki Console에서 이루어진 취소 및 환불은 웹훅으로 전달되어 메모에 추가됩니다. 주문 상태는 자동으로 변경되지 않습니다.

라이선스 키

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

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

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

문제 해결

체크아웃에 Kushki가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 두 Merchant ID가 모두 있는지 확인하십시오. 테스트 모드에는 테스트 ID, 실결제 모드에는 운영 ID가 필요합니다. 장바구니 통화가 USD 또는 COP인지 확인하십시오. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오. ID가 없으면 설정 페이지에 경고가 표시됩니다.

결제는 완료되었으나 주문이 생성되지 않음: 예를 들어 시간 초과로 인해 Kushki API 응답이 누락되었습니다. 웹훅은 이러한 결제에 대해 주문을 생성합니다. Kushki Console에서 웹훅 URL이 Webhook URL에 표시된 것과 정확히 같은지, 사용 중인 모드의 계정에 대한 것인지, 그 계정의 서명 키가 해당 필드(Test webhook signature 또는 Live webhook signature)에 입력되어 있는지 확인하십시오. 결제 금액과 통화가 없는 승인된 결제는 Kushki payment on hold 상태의 주문을 생성합니다.

웹훅 응답이 Webhook signature not configured: 두 웹훅 서명이 모두 설정되지 않았습니다. 서명 키를 설정에 붙여 넣으십시오.

웹훅 응답이 Invalid signature: 서명 키가 다른 계정이나 모드의 것이거나, 알림이 전송 중에 변경되었습니다.

웹훅 응답이 Order mismatch: 알림이 이 장바구니의 결제에 속하지 않습니다(잘못된 시도 키 또는 거래). 아무것도 변경되지 않습니다.

웹훅 응답이 Busy, retry later: 같은 순간에 다른 요청이 주문을 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Kushki는 알림을 다시 보낼 수 있습니다. 오류는 항상 로그에 기록됩니다.

브라우저에서 웹훅 URL에 POST만 표시됨: 정상입니다. 이 URL은 Kushki의 알림만 수락합니다.

카드 양식이 로드되지 않음: 고객은 Kushki 카드 양식을 불러올 수 없습니다. 페이지를 새로 고치거나 다른 결제 방법을 선택하십시오. 를 봅니다. 현재 모드의 Public Merchant ID를 확인하십시오.

고객에게 "이 결제 방법은 이 쇼핑몰에서 사용할 수 없습니다. 카드로 결제하십시오."가 표시됨: Kushki 양식에서 카드가 아닌 결제 방법이 선택되었습니다. 모듈은 카드만 청구합니다.

고객이 결제 시 오류를 봄: Debug log를 켜고 모듈 페이지의 Log 필드를 확인하십시오. 잘못되었거나 없는 Private Merchant ID는 결제를 처리할 수 없다는 일반 메시지를 표시합니다.

고객에게 "결제는 접수되었으나 주문을 자동으로 완료할 수 없습니다."가 표시됨: Kushki는 결제를 승인했지만 PrestaShop이 주문을 생성하지 못했습니다. 로그에 이유가 표시됩니다. 같은 장바구니의 다음 결제 시도는 새로 청구하지 않고 주문을 생성합니다.

모드 관련 메시지와 함께 환불이 실패함: 결제는 테스트 또는 실결제 모드로 이루어졌으나 해당 모드의 Private Merchant ID가 설정되지 않았습니다. 입력한 후 다시 시도하십시오.

환불이 제공되지 않으며 "이 주문에 대한 Kushki 티켓 번호를 찾을 수 없습니다" 메시지가 표시됨: 이 주문에는 확인된 Kushki 결제가 없습니다. Kushki Console에서 환불하십시오.

제거

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

Kushki는 해당 소유자의 상표입니다. 이 모듈은 Kushki와 제휴하거나 Kushki의 승인을 받지 않았습니다.