VibeFox Worldline for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

Worldline 계정: Worldline Direct(구 Ingenico Direct) 가맹점 계정. 테스트 계정과 실결제 계정은 별도이며 자격 증명도 다릅니다. 각 계정마다 가맹점 ID(PSPID), API Key ID와 그에 대한 Secret API Key, 웹훅 키와 그에 대한 Secret이 필요합니다. 이 모든 항목은 Worldline Merchant Portal에서 만듭니다(「Configuration」 참조).

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

설치

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

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage로 이동하거나, 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

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

5. 테스트 자격 증명을 입력하고, 설정을 저장한 뒤 Test credentials를 클릭합니다.

6. 테스트 계정의 Merchant Portal에 웹훅 URL을 추가하고 웹훅 키와 Secret을 입력합니다(「Configuration」 참조).

7. Enable/Disable을 켜고 테스트 결제를 진행합니다. 그다음 실결제 자격 증명을 입력하고, 실결제 계정에서도 웹훅 설정을 반복한 뒤, Live credentials를 클릭하고 Test Mode 체크를 해제합니다.

Configuration

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Worldline (Ingenico). 결제 수단 목록에서 현재 모드에 가맹점 ID, API Key ID, Secret API Key가 모두 입력되기 전까지 Worldline은 설정이 필요한 것으로 표시됩니다. 설정 페이지에서는 사용하지 않는 모드의 자격 증명 입력란이 흐리게 표시됩니다.

General

Enable/Disable: Enable Worldline Gateway는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 문구입니다. 기본값: Pay securely via Worldline.

Worldline Direct API

테스트 계정과 실결제 계정 각각의 Worldline Merchant Portal에서 자격 증명을 가져옵니다. PSPID가 가맹점 ID입니다. Developer > Payment API에서 API Key ID와 Secret API Key를 만들고, Developer > Webhooks에서 웹훅 키와 Secret을 만듭니다. 이 섹션에는 두 포털과 Worldline 문서로 가는 링크가 있습니다.

Test Mode: Enable test mode (pre-production environment, no real money)를 켜면 API 엔드포인트와 자격 증명이 함께 전환됩니다. 테스트 모드는 사전 프로덕션 환경과 테스트 자격 증명을, 실결제 모드는 프로덕션 환경과 실결제 자격 증명을 사용합니다. 기본값: 켜짐. 실제 결제를 받으려면 체크를 해제합니다. 테스트 모드가 켜져 있는 동안 고객에게는 결제 수단 아래에 Test mode — no real money is charged.가 표시됩니다.

테스트 계정(사전 프로덕션)

Test Merchant ID (PSPID): 테스트 계정의 PSPID입니다.

Test API Key ID: 테스트 계정의 Developer > Payment API에서 만든 API Key ID입니다.

Test Secret API Key: 해당 API Key ID에 속한 Secret API Key입니다.

Test Webhook Key ID: 선택 사항입니다. 설정하면 이 키로 보낸 웹훅만 허용됩니다.

Test Webhook Secret: 테스트 계정의 웹훅 Secret입니다. 각 웹훅의 서명을 확인하는 데 사용됩니다.

실결제 계정(프로덕션)

Live Merchant ID (PSPID): 실결제 계정의 PSPID입니다.

Live API Key ID: 실결제 계정의 Developer > Payment API에서 만든 API Key ID입니다.

Live Secret API Key: 해당 API Key ID에 속한 Secret API Key입니다.

Live Webhook Key ID: 선택 사항입니다. 설정하면 이 키로 보낸 웹훅만 허용됩니다.

Live Webhook Secret: 실결제 계정의 웹훅 Secret입니다.

자격 증명 확인

Test credentials와 Live credentials 버튼은 저장된 각 계정의 자격 증명을 Worldline에 테스트 호출하여 확인합니다. 먼저 변경 사항을 저장하세요. 결과는 버튼 옆에 표시됩니다. 예: Test credentials: connection successful., API credentials are not configured. 또는 Worldline이 반환한 오류.

Webhooks

웹훅은 고객이 쇼핑몰로 돌아오지 않아도, 예를 들어 브라우저를 닫았거나 결제가 나중에 확인된 경우에도 결제 정보를 쇼핑몰에 알려 줍니다. 테스트 계정의 Merchant Portal에서 Developer > Webhooks를 열고, 설정의 이 섹션에 표시된 엔드포인트 URL을 추가합니다. URL은 다음과 같은 형태입니다: https://your-site/wc-api/wlg_worldline_webhook/. 설정에 표시된 URL을 정확히 그대로 복사하세요. URL은 리디렉션 없이 응답해야 하므로, 언어 접두사와 www 또는 https 강제 리디렉션을 확인하십시오. 그다음 웹훅 키 ID와 Secret을 Test Webhook Key ID와 Test Webhook Secret에 입력합니다. 실결제 계정도 실결제 항목으로 같은 방식으로 설정합니다.

플러그인은 Worldline의 엔드포인트 검증 요청에 자동으로 응답합니다. 결제 이벤트(결제 상태 변경)와 환불 이벤트(환불 상태 변경)를 처리합니다. 그 밖의 이벤트는 수락되지만 무시됩니다. 유효한 서명이 없는 웹훅은 거부됩니다. 웹훅을 서명한 Secret이 속한 계정과 다른 가맹점 ID에서 온 웹훅도 무시됩니다. 웹훅이 없으면 주문은 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 확인됩니다.

결제 페이지 및 주문

Payment page template: Merchant Portal에 업로드한 호스티드 결제 페이지 템플릿(변형)의 이름입니다. 선택 사항이며, 예: SimplifiedCustomPaymentPage. 비워 두면 Worldline 기본 결제 페이지를 사용합니다.

Order Status After Payment: Worldline이 캡처된 결제를 확인한 후의 주문 상태입니다. 상태는 즉시 설정되며 두 번째 상태 변경은 없습니다. 결제는 항상 직접 판매(승인 및 캡처)로 요청됩니다.

Processing: WooCommerce 기본 설정입니다. 다운로드 가능한 가상 상품만 있는 주문은 완료됨이 됩니다.

Completed: 결제된 모든 주문이 완료됨이 됩니다.

Logging: Enable debug logging을 켜면 모든 API 요청과 웹훅이 WooCommerce > Status > Logs에 소스 wcp_worldline_gateway로 기록됩니다. 이 옵션이 꺼져 있어도 오류와 경고는 항상 기록됩니다. 키, 카드 정보, 개인정보는 마스킹됩니다. 기본값: 꺼짐.

Delete Data: Delete the plugin settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문에 저장된 결제 데이터는 환불에 필요하므로 유지됩니다. 기본값: 꺼짐.

버전 1.0에서 업데이트하면, 기존의 단일 자격 증명 세트는 쇼핑몰이 사용하던 모드에 따라 테스트 또는 실결제 항목으로 옮겨집니다.

체크아웃

고객이 결제 수단(기본값 Worldline)을 선택하고 주문합니다. 플러그인은 주문 통화로 주문 금액에 대한 Worldline 호스티드 체크아웃을 만든 뒤, 고객을 Worldline 결제 페이지로 보냅니다. 고객은 그곳에서 카드, 전자지갑 또는 Worldline 계정에서 활성화된 다른 결제 수단으로 결제합니다. 청구자 이름, 주소, 이메일, 전화번호는 Worldline에 전달되며, Worldline이 지원하는 경우 결제 페이지는 쇼핑몰의 언어로 열립니다. 각 결제 시도는 주문 ID와 임의의 문자열로 구성된 고유한 참조 번호를 받습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 플러그인은 저장된 결제 시도와 대조해 복귀를 확인하고, 서버에서 Worldline으로부터 결제 상태를 읽습니다. 주문은 Worldline이 이 상태 확인이나 서명된 웹훅으로 결제를 확인한 후에만 결제 완료로 표시됩니다. 그 후 고객에게 주문 접수 페이지가 표시됩니다.

결제가 완료되지 않은 경우, 고객은 다음 메시지와 함께 Pay for order 페이지로 이동합니다:

취소했거나 결제 페이지를 떠남: Worldline 페이지에서 결제가 완료되지 않았습니다. 주문은 저장되어 있습니다. 다시 시도하거나 다른 결제 수단을 선택할 수 있습니다.

거절됨: 결제가 거절되었습니다. 다시 시도하거나 다른 결제 수단을 선택해 주세요.

상태를 확인할 수 없음: 아직 결제를 확인할 수 없습니다. 결제를 완료하셨다면 다시 결제하지 마세요. Worldline이 확인하는 즉시 확인 메시지를 받게 됩니다.

고객은 Pay for order 페이지에서 결제되지 않은 주문을 다시 결제할 수 있습니다. 그 사이에 이전 시도가 결제되었다면 고객은 바로 주문 접수 페이지로 이동하며, 이중으로 청구되지 않습니다. 이전 결제 페이지가 같은 금액과 모드로 아직 열려 있고 30분 이내에 만들어졌다면, 고객은 그 페이지로 다시 보내집니다.

Worldline이 결제를 시작할 수 없는 경우 고객에게 Payment error: Could not create checkout session. Please try again.가 표시되며, 다른 결제 수단을 선택할 수 있습니다. 그 이유는 주문 메모와 로그에 추가됩니다. 현재 모드의 자격 증명이 없으면 고객에게 This payment method is not available at the moment. Please choose another payment method.가 표시됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce High-Performance Order Storage(HPOS)와 호환됩니다.

플러그인은 일회성 결제를 Worldline 페이지에서 직접 판매로 처리합니다. 저장된 카드나 토큰화, 구독, 임베디드 카드 양식, WooCommerce에서 승인 후 캡처 또는 취소하는 승인 전용 모드, 추가 수수료(surcharge), 웹훅 자동 등록은 지원하지 않습니다.

주문 및 환불

Order statuses

Pending payment: 고객이 Worldline으로 보내졌지만 아직 결제하지 않았거나, Worldline이 아직 결제를 확인하지 않았습니다. 메모에는 호스티드 체크아웃 ID, 참조 번호, 모드(테스트 또는 실결제)가 표시됩니다.

Processing or Completed: 결제가 캡처되었습니다. 상태는 Order Status After Payment를 따릅니다. 주문 메모에는 금액, Worldline 결제 ID, 확인 방식(서명된 웹훅 또는 상태 확인)이 표시됩니다. 주문의 트랜잭션 ID는 Worldline 결제 ID입니다.

On hold, waiting for capture: Worldline이 결제를 승인되었거나 캡처가 요청되었다고 보고했지만 아직 캡처되지 않았습니다. 주문 메모에 이 내용이 설명되어 있습니다. 웹훅이 캡처를 확인하면 주문은 자동으로 결제 완료로 표시됩니다. 메모에 결제가 캡처되지 않았다고 나오면 Worldline Merchant Portal에서 캡처하세요.

On hold, held for manual review: 결제가 주문과 일치하지 않습니다. 예를 들어 금액이나 통화가 다른 경우(결제 시작 후 주문이 수정됨), 또는 결제가 다른 시도에 속한 경우입니다. 메모에는 결제된 금액, 주문 합계, 참조 번호가 표시됩니다. 주문을 확인하여 처리하거나 결제를 환불하세요.

Failed: Worldline이 최신 시도의 결제를 거절하거나 취소했거나, 고객이 선택한 결제 수단의 대상이 아니었습니다.

Cancelled: 주문이 귀하 또는 WooCommerce 재고 보유 시간 초과로 취소되었습니다. 취소되었거나 환불된 주문에 결제가 도착해도 주문은 다시 열리지 않습니다. 메모에서는 Worldline Merchant Portal에서 결제를 환불하거나 취소하거나 주문을 수동으로 복구하라고 안내합니다. 돌아온 고객에게는 Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment.가 표시됩니다.

이미 결제된 주문에 두 번째 결제가 도착하면 주문은 다시 변경되지 않습니다. 메모에서는 Worldline Merchant Portal에서 두 번째 결제를 환불하라고 안내합니다.

환불

주문을 열고 Refund를 클릭한 뒤 금액을 입력하고 Refund via Worldline (Ingenico)를 클릭합니다. 전액 환불과 부분 환불을 지원합니다. 결제가 캡처되어 있어야 합니다. 환불은 항상 원래 결제의 환경(테스트 또는 실결제)으로, 해당 계정의 자격 증명을 사용하여 전송되므로 자격 증명이 설정되어 있어야 합니다. 시간 초과 후 다시 시도한 환불은 두 번 실행되지 않습니다. Worldline이 환불을 거부하면 WooCommerce에 오류가 표시되며 환불은 기록되지 않습니다. 승인된 환불은 Worldline 환불 ID와 상태와 함께 주문 메모에 추가됩니다.

환불 상태 변경은 Worldline에서 웹훅으로 전달되며 주문 메모에 추가됩니다. Merchant Portal에서 처리한 환불은 WooCommerce 환불로 자동 기록되지 않습니다. 필요하다면 Refund via Worldline (Ingenico)를 사용하지 않고 WooCommerce에서 수동 환불을 만드세요.

라이선스 키

플러그인은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Worldline (Ingenico) 상단에 있습니다. License key에 키를 붙여 넣고 Activate를 클릭하세요. 블록에는 상태(예: 라이선스 만료일)와 귀하의 도메인이 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

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

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

문제 해결

Worldline이 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 가맹점 ID, API Key ID, Secret API Key가 있는지 확인하세요. 테스트 모드에서는 테스트 항목, 실결제 모드에서는 실결제 항목입니다. 값이 없으면 결제 목록에서 해당 결제 수단이 설정 필요로 표시됩니다.

결제는 성공했지만 주문이 Pending payment 상태로 남아 있음: 웹훅이 작동하지 않습니다. 사용 중인 계정(테스트 또는 실결제)의 Merchant Portal에서 엔드포인트가 있는지, URL이 설정에 표시된 것과 정확히 같은지, 리디렉션이 없는지 확인하세요. 해당 계정의 웹훅 Secret이 맞는 항목(Test Webhook Secret 또는 Live Webhook Secret)에 들어 있는지, Webhook Key ID가 비어 있거나 키와 일치하는지 확인하세요. 고객이 결제 후 쇼핑몰로 돌아와도 주문은 확인됩니다.

웹훅이 Webhook secret not configured로 응답: 웹훅 Secret이 설정되어 있지 않습니다. 설정에 웹훅 Secret을 입력하세요. Worldline은 웹훅을 다시 시도합니다.

웹훅이 Invalid signature로 응답: 웹훅 Secret이 다른 계정이나 다른 키에 속하거나, Webhook Key ID가 웹훅을 보낸 키와 일치하지 않습니다.

웹훅이 Missing signature, Empty body, Invalid JSON으로 응답: 요청이 예상된 형식으로 Worldline에서 오지 않았거나, 프록시 또는 리디렉션이 요청을 변경했습니다. URL이 리디렉션 없이 응답하는지 확인하세요.

웹훅이 Ignored로 응답: 웹훅이 해당 모드 설정의 가맹점 ID와 다른 가맹점 ID에서 왔습니다. Test Merchant ID (PSPID) 또는 Live Merchant ID (PSPID)를 확인하세요.

웹훅이 Retry later로 응답: 같은 시점에 다른 요청이 주문을 업데이트하고 있었습니다. Worldline은 웹훅을 다시 시도합니다.

Test credentials 또는 Live credentials에 오류가 표시됨: 먼저 설정을 저장한 뒤, 가맹점 ID, API Key ID, Secret API Key가 같은 계정에서 발급되었는지, 테스트 값은 테스트 항목에, 실결제 값은 실결제 항목에 입력되었는지 확인하세요.

고객이 주문할 때 오류를 봄: 주문 메모 또는 WooCommerce > Status > Logs를 열어 소스 wcp_worldline_gateway를 확인하세요. 디버그 로깅이 꺼져 있어도 오류는 기록됩니다. 요청의 전체 세부 정보를 보려면 Logging을 켠 뒤 다시 시도하세요.

테스트 결제가 실결제 주문을 확인하지 않음: 테스트와 실결제는 분리되어 있습니다. 테스트 Secret으로 서명된 웹훅은 실결제 결제 시도를 절대 확인하지 않으며, 그 반대도 마찬가지입니다. 원하는 모드로 Test Mode를 전환하고 해당 계정의 자격 증명과 웹훅을 사용하세요.

결제 후 주문이 On hold 상태: 주문 메모를 읽어 보세요. Worldline이 아직 캡처를 확인하지 않았거나(웹훅이 주문을 완료함), 결제된 금액 또는 통화가 주문과 달랐던 경우입니다.

환경 관련 메시지와 함께 환불 실패: 결제는 테스트 또는 실결제 환경에서 이루어졌는데, 해당 환경의 자격 증명이 설정되어 있지 않습니다. 자격 증명을 입력하고 다시 시도하세요.

개발자: 필터 wlg_hosted_checkout_data는 호스티드 체크아웃 요청을 변경합니다(예: 표시되는 결제 수단 제한). wlg_gateway_icon은 결제 수단 아이콘을 변경합니다.

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

삭제

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 뒤 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그는 Delete Data가 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 다시 설치할 때를 위해 남겨집니다. 주문에 저장된 Worldline 결제 데이터는 환불에 필요하므로 항상 유지됩니다. 기존 주문은 결제 메모와 트랜잭션 ID를 그대로 유지합니다.

Worldline은 각 소유자의 상표입니다. 이 플러그인은 Worldline과 제휴하거나 Worldline의 승인을 받은 것이 아닙니다.