VibeFox Cashfree for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

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

PHP: 8.0 이상.

HTTPS: Cashfree는 https:// 주소로만 웹훅을 전달합니다. HTTPS가 없어도 고객이 쇼핑몰로 돌아올 때 결제는 확인되지만, 운영을 시작하기 전에 HTTPS를 활성화하세요.

Cashfree 계정: Cashfree 계정의 App ID와 Secret Key가 필요합니다. 테스트(샌드박스) 환경과 운영 환경의 값은 각각 다릅니다. 또한 Cashfree Merchant Dashboard에 웹훅을 설정해야 합니다(설정 항목 참조). Secret Key는 웹훅 검증에도 사용되므로 별도의 웹훅 시크릿은 없습니다. 주문 통화가 Cashfree 계정에서 활성화되어 있어야 합니다.

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

설치

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

2. Activate를 클릭하세요.

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

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

5. Sandbox App ID와 Sandbox Secret Key를 입력하고, Cashfree Merchant Dashboard에 웹훅을 추가한 다음(설정 항목 참조), Enable/Disable을 켜고 결제를 테스트하세요.

6. 준비가 되면 운영 App ID와 Secret Key를 입력하고 Sandbox Mode 체크를 해제하세요.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Cashfree Payments. 결제 수단이 활성화되어 있으면, 선택된 모드의 API 키가 없을 때 페이지가 경고를 표시하며(이 경우 결제 수단은 체크아웃에서 숨겨집니다), 샌드박스 모드가 켜져 있는 동안에는 Sandbox mode is on: customers see a test checkout and no real money is charged.를 표시합니다. 선택된 모드의 키 없이 활성화된 게이트웨이를 저장하면, 키가 설정될 때까지 결제 수단이 체크아웃에서 숨겨진다는 오류 메시지가 표시됩니다.

일반

Enable/Disable: Enable Cashfree Payments로 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

Title: 체크아웃에서 고객이 보는 결제 수단 이름입니다. 기본값: Cashfree Payments.

Description: 체크아웃에서 결제 수단 아래에 표시되는 문구입니다. 기본값: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

모드 및 API 키

App ID와 Secret Key는 Cashfree Merchant Dashboard의 Developers > API Keys에서 확인하세요. 테스트 키와 운영 키는 서로 다르므로, 각 키를 해당 섹션에 입력하세요.

Sandbox Mode: Enable Sandbox (test) mode는 테스트에 Cashfree 샌드박스를 사용합니다. 실제 돈은 청구되지 않으며, 체크아웃에는 SANDBOX MODE - no real payments will be processed.가 표시됩니다. 기본값: 켜짐. 운영 결제를 받으려면 체크를 해제하세요.

Sandbox 자격 증명

Sandbox App ID: Cashfree 테스트 환경의 App ID입니다.

Sandbox Secret Key: Cashfree 테스트 환경의 Secret Key입니다.

운영 자격 증명

App ID: Cashfree 운영 환경의 App ID입니다.

Secret Key: Cashfree 운영 환경의 Secret Key입니다.

주문은 생성된 환경을 그대로 유지합니다. 웹훅은 그 환경의 키로 검증되고 환불도 그 키로 전송되므로, 운영으로 전환한 후에도 샌드박스 주문이 정산될 때까지 샌드박스 키를 계속 입력해 두세요.

웹훅

웹훅은 쇼핑몰에 결제가 완료되었는지, 실패했는지, 환불되었는지를 알려 줍니다. Cashfree Merchant Dashboard에서 Developers > Webhooks로 이동하여 이 섹션에 표시된 URL을 Payment 및 Refund 이벤트와 함께 추가하세요. URL은 https://your-site/wc-api/cashfree_p/?action=webhook과 같은 형태입니다. HTTPS 사이트에서는 플러그인이 모든 주문마다 이 URL을 Cashfree에도 전달합니다. 쇼핑몰이 HTTPS를 사용하지 않으면 이 섹션에 경고가 표시됩니다.

플러그인은 다음 이벤트를 처리합니다:

Cashfree는 모든 웹훅을 Secret Key로 서명합니다. 유효한 서명이 없는 웹훅은 거부됩니다. 이 쇼핑몰이 만들지 않은 주문에 대한 서명된 웹훅(예: 같은 Cashfree 계정의 다른 쇼핑몰)은 확인 응답을 보낸 후 무시됩니다. 웹훅이 없으면 주문은 고객이 결제 후 쇼핑몰로 돌아올 때에만 확인됩니다. 결제 후 고객이 브라우저를 닫으면 웹훅만이 주문을 확인할 수 있습니다.

고급

API Version: 사용할 Cashfree API 버전입니다.

Order ID prefix: Cashfree 주문 ID는 접두사 + WooCommerce 주문 ID로 만들어지며, 반복 시도에는 끝에 번호가 붙습니다. 비워 두면 필드 설명에 표시된 이 사이트의 자동 접두사를 사용합니다. 같은 Cashfree 계정에 연결된 쇼핑몰마다 다른 접두사를 사용하세요. 문자, 숫자, "_" 및 "-"만 가능하며 최대 20자입니다. 다른 문자는 저장할 때 메시지와 함께 제거됩니다.

Debug log: Log Cashfree API events for debugging. 오류는 항상 기록됩니다. 켜져 있으면 API 호출과 웹훅도 WooCommerce > Status > Logs에 소스 wcp_cashfree_payment로 기록됩니다. 키와 고객 데이터는 절대 기록되지 않습니다. 기본값: 꺼짐.

Delete Data on Uninstall: Delete all plugin data when uninstalling. 켜져 있으면 플러그인을 삭제할 때 Cashfree 설정, 플러그인 로그, 주문에 저장된 Cashfree 참조 정보가 제거됩니다. 주문 자체는 유지됩니다. 기본값: 꺼짐.

체크아웃

고객은 결제 수단(기본값: Cashfree Payments)을 선택하고 주문합니다. 플러그인은 주문 통화로 된 주문 합계에 대한 Cashfree 주문을 생성하고 Pay for order 페이지를 엽니다. 이 페이지에는 Redirecting to Cashfree for payment...가 표시되며 Cashfree 체크아웃을 불러옵니다. 자동으로 열리지 않으면 고객은 Pay Now를 클릭할 수 있습니다. Cashfree 체크아웃에서 고객은 Cashfree 계정에서 활성화된 결제 수단(예: 카드, UPI, 넷뱅킹 또는 전자지갑)으로 결제합니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Cashfree가 확인한 후에만 결제 완료로 표시됩니다. 서명된 웹훅이나, 고객이 돌아올 때 플러그인이 Cashfree에 보내는 서버 측 요청을 통해 확인됩니다. 은행이 아직 결제를 확인하지 않았다면 주문 접수 페이지에 Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.가 표시됩니다.

결제가 실패하거나 고객이 결제하지 않고 Cashfree 페이지를 떠나면, 고객은 The Cashfree payment was not completed. Please try again or choose another payment method.와 함께 Pay for order 페이지로 돌아갑니다. 고객이 다시 시도하면 열려 있는 Cashfree 결제가 재사용됩니다. 주문 합계가 바뀌었거나 세션이 곧 만료되면 이전 Cashfree 주문은 닫히고 새 주문이 생성되므로, 주문이 두 번 결제될 수 없습니다. 주문이 Cashfree에서 이미 결제되었지만 기록되지 않았다면, 다음 시도에서 다시 청구하지 않고 결제를 기록합니다.

Cashfree가 결제를 시작할 수 없으면 고객에게 We could not start the Cashfree payment. Please try again or choose another payment method.가 표시됩니다. 기술적인 이유는 로그에 기록됩니다. Cashfree 최소 금액보다 낮은 주문 합계(통화 1단위, 단 BHD, JOD, KWD, OMR은 0.01, TND는 0.1)는 Cashfree로 결제할 수 없습니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다. 고객에게 표시되는 문구는 힌디어로 번역되어 있습니다.

플러그인은 Cashfree 체크아웃에서의 일회성 결제만 받습니다. 저장된 카드, 구독 또는 정기 결제, 별도의 승인 및 캡처, Cashfree 오퍼 위젯, Cashfree를 통한 COD 또는 결제 링크를 지원하지 않으며, 통화 환전도 없습니다. 주문은 주문 통화로 청구됩니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Cashfree로 이동했지만 아직 결제하지 않았거나, 은행에서 결제가 여전히 대기 중입니다. 고객이 결제 대기 중 상태로 돌아오면, 메모에 플러그인이 Cashfree 웹훅을 기다리고 있다고 표시됩니다.

Processing: 결제가 확인되었습니다(가상 다운로드 상품만 있는 주문은 WooCommerce 기본 동작에 따라 완료됨 상태가 됩니다). 주문 메모에는 Cashfree 거래 ID와 결제 수단 그룹이 표시됩니다. 주문의 거래 ID는 Cashfree 결제 ID입니다. 주문이 취소된 후에 도착한 결제도 돈이 청구되었으므로 그대로 기록됩니다.

On hold: Cashfree가 주문 합계와 다른 결제 금액 또는 통화를 보고했습니다. 주문 메모에 예상 금액과 받은 금액, 거래 ID가 표시됩니다. Cashfree 대시보드에서 결제를 확인한 후 주문을 수동으로 완료하거나 환불하세요.

Failed: 결제가 Cashfree에서 실패했거나 취소되었습니다. 메모에 Cashfree 상태와 사유가 표시됩니다. 실패한 시도가 있을 때마다 메모가 하나씩 추가됩니다.

결제 완료된 주문은 이후의 웹훅이나 복귀로 절대 되돌려지지 않습니다.

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Cashfree Payments를 클릭하세요(버튼에는 결제 수단 제목이 표시됩니다). 전액 및 부분 환불을 지원합니다. 환불은 결제된 Cashfree 주문으로, 결제가 이루어진 환경(샌드박스 또는 운영)으로 전송되므로 해당 환경의 키가 설정되어 있어야 합니다. Cashfree가 환불을 수락하지 않거나 취소 또는 거부로 보고하면, WooCommerce가 오류를 표시하고 환불은 기록되지 않습니다. 시작된 환불은 환불 ID, 금액, 상태와 함께 주문 메모에 추가됩니다. 최종 상태는 환불 웹훅을 통해 다른 주문 메모로 도착합니다.

환불 상태 웹훅은 메모로만 추가됩니다. WooCommerce 환불로 자동 기록되지는 않습니다.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 영역은 WooCommerce > Settings > Payments > Cashfree Payments 페이지 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭하세요. 이 영역에는 상태(예: 라이선스가 유효한 기한)와 도메인이 표시됩니다. 상태를 다시 확인하려면 Check now, 다른 키를 입력하려면 Change key, 이 사이트에서 키를 제거하려면 Remove key를 사용하세요. Manage licenses and domains in your account 링크를 클릭하면 vibefox.net 계정이 열립니다.

키 1개는 도메인 1개에서 작동합니다. 사이트에서 키를 제거해도 도메인 슬롯은 비워지지 않습니다. vibefox.net 계정에서 슬롯을 비우세요.

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

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

문제 해결

체크아웃에 Cashfree가 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 키가 있는지 확인하세요. 샌드박스 모드에서는 Sandbox App ID와 Sandbox Secret Key, 운영 모드에서는 App ID와 Secret Key입니다. 주문 합계가 Cashfree 최소 금액보다 낮아도 결제 수단이 숨겨집니다. 키가 없으면 설정 페이지에 경고가 표시됩니다.

결제는 완료됐지만 주문이 Pending payment 상태로 남아 있음: 웹훅이 작동하지 않습니다. 쇼핑몰이 HTTPS를 사용하는지, Developers > Webhooks의 URL이 설정에 표시된 것과 정확히 같은지, Payment 이벤트가 선택되어 있는지 확인하세요. 설정의 Secret Key가 주문이 결제된 환경의 키인지 확인하세요. 주문은 고객이 결제 후 쇼핑몰로 돌아올 때와 다음 결제 시도 때에도 확인됩니다.

웹훅 응답: Missing signature 또는 Invalid signature: 호출에 유효한 Cashfree 서명이 없었거나, 설정의 Secret Key가 주문이 생성된 환경과 맞지 않습니다. Cashfree가 웹훅을 다시 보냅니다.

웹훅 응답: Ignored: 웹훅은 올바르게 서명되었지만 이 쇼핑몰이 만들지 않은 주문(예: 같은 Cashfree 계정의 다른 쇼핑몰)에 대한 것입니다. 쇼핑몰마다 고유한 Order ID prefix를 사용하세요.

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

고객에게 The Cashfree payment page could not be loaded가 표시됨: 브라우저에서 Cashfree 스크립트를 불러오지 못했습니다(예: 차단 도구 때문). 고객은 Pay Now를 다시 클릭하거나 Choose another payment method를 선택할 수 있습니다.

고객에게 We could not start the Cashfree payment가 표시됨: Debug log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_cashfree_payment를 확인하세요. 일반적인 원인은 선택된 모드의 잘못된 키 또는 Cashfree 계정에서 활성화되지 않은 통화입니다.

고객에게 The minimum amount for a Cashfree payment is …가 표시됨: 주문 합계가 해당 통화의 Cashfree 최소 금액보다 낮습니다.

고객에게 We could not verify the payment가 표시됨: 복귀 링크가 주문과 일치하지 않았습니다. 돈이 청구되었다면 웹훅이 여전히 주문을 확인합니다. 고객이 다시 결제하기 전에 Cashfree 대시보드에서 결제를 확인하세요.

결제 후 주문이 On hold 상태임: 주문 메모를 읽어 보세요. 결제된 금액 또는 통화가 주문과 달랐습니다. 주문을 완료하거나 결제를 환불하세요.

샌드박스 또는 운영 모드 관련 메시지와 함께 환불 실패: 주문이 그 환경에서 결제되었고, 해당 API 키가 설정되어 있지 않습니다. 키를 입력한 다음 다시 시도하세요.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정, 주문에 저장된 Cashfree 데이터, 로그는 Delete Data on Uninstall이 켜져 있었던 경우에만 제거됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

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