VibeFox Kushki for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

쇼핑몰 통화: USD(에콰도르) 또는 COP(콜롬비아). 그 밖의 통화에서는 결제 페이지에 이 결제 수단이 표시되지 않습니다.

HTTPS: Kushki는 실결제 모드에서 결제 페이지가 HTTPS로 제공되어야 한다고 요구합니다.

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

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

설치

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

2. Activate를 클릭합니다.

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

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

5. 테스트용 Public·Private Merchant ID를 입력하고 Test mode를 켜 둡니다. 필요하다면 Kushki Console에서 웹훅을 설정하고 서명 키를 붙여 넣습니다(설정 항목 참조).

6. Enable / Disable을 켜고 테스트 주문을 진행합니다. 준비가 되면 운영 Merchant ID(및 운영 웹훅 서명)를 입력하고 Test mode 체크를 해제합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Kushki. 필드 위에는 결제 수단이 켜져 있지만 현재 모드의 Merchant ID가 없는 경우(이때 결제 수단은 결제 페이지에서 숨겨집니다), 쇼핑몰 통화가 지원되지 않는 경우, HTTPS 없이 실결제 모드를 사용하는 경우, 현재 모드에 웹훅 서명이 없는 경우에 경고가 표시됩니다. 테스트 모드가 켜져 있는 동안에는 Test mode is on: the Kushki test environment is used, no real money is charged. 가 표시됩니다. 결제 수단이 켜진 상태에서 현재 모드의 Merchant ID를 입력하지 않고 저장하면, 입력하라는 오류가 표시됩니다. ID 앞뒤의 공백은 저장할 때 제거됩니다.

일반

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: Use the Kushki test (UAT) environment를 켜면 Merchant ID, 카드 양식, API가 함께 Kushki 테스트 환경으로 전환됩니다. 실제 금액은 청구되지 않으며, 결제 페이지에 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입니다. 비밀로 관리하세요.

웹훅(권장)

결제는 Kushki API 응답으로 즉시 확인되므로 웹훅은 필수가 아닙니다. 웹훅은 응답이 누락된 결제(예: 시간 초과 시)를 추가로 확인하고, Kushki Console에서 이루어진 취소 및 환불을 알려 줍니다. Kushki Console(Webhooks)에서 카드 결제용으로 설정의 이 섹션에 표시된 URL을 추가합니다. 형식은 https://your-site/wc-api/webhook_kushki_p/와 같습니다. 테스트 계정과 운영 계정 모두에 대해 설정하세요.

플러그인은 다음 카드 알림을 처리합니다:

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

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

유효한 서명이 없는 웹훅은 거부됩니다. 서명 키가 없으면 모든 웹훅 알림이 거부되지만, 결제는 API 응답으로 확인되므로 계속 작동합니다.

고급

Debug log: Log API calls and webhooks를 켜면 Kushki 요청과 웹훅이 WooCommerce > Status > Logs에 소스 wcp_kushki_payment로 기록됩니다. 오류는 항상 기록됩니다. 로그에는 Merchant ID, 카드 토큰, 고객 이메일이 절대 포함되지 않습니다. 기본값: 꺼짐.

Delete data on uninstall: 켜져 있으면 플러그인을 삭제할 때 설정과 로그가 제거됩니다. 주문과 Kushki 참조 정보는 유지됩니다. 기본값: 꺼짐.

결제

고객이 결제 수단을 선택합니다(기본값 Credit / debit card (Kushki)). 그 아래에 Kushki 카드 양식이 나타나며, 주문 통화로 주문 총액이 표시됩니다. Pay for order 페이지에서는 양식이 주문 총액을 사용합니다. 고객은 카드를 입력하고, Kushki 양식이 할부를 제공하면 할부 개월을 선택한 뒤, Kushki 양식 안의 결제 버튼을 누릅니다.

클래식 결제에서는 Kushki가 선택된 동안 WooCommerce의 Place order 버튼이 숨겨집니다. 카드가 승인되면 주문이 자동으로 제출됩니다. 체크아웃 블록에서도 고객은 Kushki 양식 안의 결제 버튼을 눌러야 합니다. 이 과정을 거치지 않고 주문하려고 하면 Please enter your card details in the Kushki form and press its pay button. 메시지가 표시됩니다.

그 후 쇼핑몰이 서버에서 카드에 청구합니다. Kushki가 티켓 번호와 함께 확인해야만 주문이 결제 완료로 표시되며, 고객은 바로 주문 접수 페이지로 이동합니다. Kushki가 승인된 금액이나 통화를 보고하면, 이를 주문과 비교합니다.

카드가 거절되면 고객에게는 Kushki의 사유와 함께 Your payment was declined가 표시되며, 같은 양식에서 다른 카드를 시도할 수 있습니다. 네트워크, 키 또는 서버 문제가 있으면 고객에게 The payment could not be processed right now. Please try again in a moment or choose another payment method.가 표시됩니다. 기술적 사유는 주문 메모와 로그에 추가됩니다. 결제가 처리되는 중에 다시 클릭하면 A payment for this order is already being processed. Please wait a moment and check your order status.가 표시됩니다.

이 결제 수단은 클래식 결제, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다. 3-D Secure, 사기 방지 규칙, 제공되는 할부는 Kushki Console에서 설정합니다.

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

주문 및 환불

주문 상태

Pending payment: 주문은 생성되었지만 카드에 아직 청구되지 않았습니다.

Processing: Kushki가 결제를 확인했습니다(API 응답 또는 웹훅으로). 다운로드 가능한 가상 상품만 있는 주문은 WooCommerce 기본값인 Completed가 됩니다. 주문 메모에는 모드, Kushki 티켓 번호, 참조 번호가 표시됩니다. 거래 ID는 Kushki 거래 참조 번호(또는 티켓 번호)입니다.

On hold: Kushki가 티켓 번호 없이 성공을 반환했거나, 주문과 다른 금액 또는 통화를 보고했습니다. 주문 메모에 이유가 설명되어 있습니다. Kushki Console에서 거래를 확인한 후 주문을 처리하거나 결제를 환불하세요.

Failed: 카드가 거절되었거나 결제를 진행할 수 없었습니다. 주문 메모에 Kushki 코드와 메시지가 표시됩니다. 고객은 다시 결제할 수 있습니다.

이미 결제 완료, 취소 또는 환불된 주문에 대해 웹훅이 다른 승인된 결제를 보고하면, 주문은 변경되지 않습니다. 메모에서 이중 결제 여부를 확인하고 Kushki Console에서 환불하라는 안내가 표시됩니다. 실결제 주문에 대해 테스트 환경의 웹훅이 도착하면(또는 그 반대의 경우), 메모와 함께 무시됩니다.

환불

주문을 열고 Refund를 클릭한 다음 주문 총액 전체를 입력하고 Refund via Credit / debit card (Kushki)를 클릭합니다(버튼에는 설정한 Title이 표시됩니다). Kushki는 결제 전액을 환불하므로 전액 환불만 허용됩니다. 부분 금액을 입력하면 플러그인이 Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console.를 표시합니다. 하나의 결제는 한 번만 환불할 수 있습니다.

환불은 결제가 이루어진 모드(테스트 또는 실결제)로 전송되므로, 해당 모드의 Private Merchant ID가 설정되어 있어야 합니다. Kushki가 환불을 받아들이지 않으면 WooCommerce가 오류를 표시하며, 환불은 기록되지 않습니다. 환불이 성공하면 Kushki 환불 티켓과 함께 주문 메모에 추가됩니다.

Kushki Console에서 이루어진 취소 및 환불은 웹훅으로 도착하며 주문 메모에 추가됩니다. 이들은 WooCommerce 환불로 자동 기록되지 않습니다.

라이선스 키

이 플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 영역은 WooCommerce > Settings > Payments > Kushki 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭합니다. 영역에는 라이선스 유효 기한 등의 상태와 사용 중인 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거할 수 있습니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

활성 키가 없으면 Kushki는 결제 페이지에서 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객에게 This payment method is not available. Please choose another one.가 표시됩니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only) 표시와 함께 결제 수단이 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 나타납니다. 기존 주문은 영향을 받지 않습니다. 웹훅은 계속 처리되고 환불도 작동합니다.

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

문제 해결

결제 페이지에 Kushki가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 두 Merchant ID가 모두 있는지 확인하세요. 테스트 모드에서는 테스트 ID, 실결제 모드에서는 운영 ID가 필요합니다. 쇼핑몰 통화(또는 Pay for order 페이지의 주문 통화)가 USD 또는 COP인지도 확인하세요. 설정 페이지에는 이러한 문제마다 경고가 표시됩니다.

결제는 완료되었지만 주문이 Failed이거나 Pending payment 상태로 남아 있음: 시간 초과 등으로 Kushki API 응답이 누락되었습니다. 웹훅이 이러한 결제를 확인합니다. Kushki Console에서 웹훅 URL이 설정에 표시된 것과 정확히 일치하는지, 사용 중인 모드의 계정용인지, 그리고 그 계정의 서명 키가 해당 필드(Test webhook signature 또는 Live webhook signature)에 입력되어 있는지 확인하세요. 결제된 금액과 통화 없이 승인된 결제가 있으면 주문은 대신 보류 상태가 됩니다.

웹훅이 Webhook signature not configured로 응답: 웹훅 서명이 하나도 설정되지 않았습니다. 설정에 서명 키를 붙여 넣으세요.

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

웹훅이 Order mismatch로 응답: 이 알림은 이 주문의 것이 아닙니다(주문 키 또는 거래가 잘못됨). 주문은 변경되지 않습니다.

웹훅이 Busy, retry later로 응답: 같은 순간에 다른 요청이 이 주문을 처리하고 있었습니다. Kushki가 알림을 다시 보낼 수 있습니다.

카드 양식이 로드되지 않음: 고객에게 The Kushki card form could not be loaded. Please reload the page or choose another payment method.가 표시됩니다. 현재 모드의 Public Merchant ID를 확인하세요.

고객에게 This payment option is not available in this store. Please pay by card.가 표시됨: Kushki 양식에서 카드가 아닌 결제 옵션이 선택되었습니다. 플러그인은 카드만 청구합니다.

고객이 결제 중 오류를 봄: 주문 메모를 열거나 Debug log를 켠 후 WooCommerce > Status > Logs(소스 wcp_kushki_payment)를 확인하세요. 잘못되었거나 없는 Private Merchant ID는 결제를 처리할 수 없다는 일반 메시지를 표시합니다.

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

No Kushki ticket number found for this order 메시지와 함께 환불 실패: 이 주문에는 확인된 Kushki 결제가 없습니다. Kushki Console에서 환불하세요.

그 밖의 통화: 개발자는 kushki_p_supported_currencies 필터로 통화 목록을 변경할 수 있지만, 그 책임은 본인에게 있습니다. 해당 통화가 Kushki 계정에서 활성화되어 있어야 합니다.

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

삭제

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

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