VibeFox Omise for WooCommerce — 도움말

요구 사항

WordPress: 6.2 이상.

WooCommerce: 8.0 이상, 설치되어 활성화되어 있어야 합니다. WooCommerce 없이는 플러그인을 활성화할 수 없습니다. 나중에 WooCommerce를 비활성화하면 게이트웨이가 로드되지 않으며 관리자 알림이 표시됩니다.

PHP: 8.0 이상.

HTTPS: 카드 입력란은 체크아웃 페이지에 있으므로, 체크아웃은 HTTPS로 제공되어야 하며 신뢰할 수 없는 스크립트가 없어야 합니다. 그래도 카드 데이터는 쇼핑몰 서버에 절대 전달되지 않습니다. Omise는 HTTPS 주소로만 웹훅을 보냅니다.

쇼핑몰 통화: THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD 중 하나. 그 밖의 통화에서는 체크아웃에서 해당 결제 수단이 숨겨집니다.

Omise 계정: 테스트 모드와 운영 모드 모두에 대해 Omise 계정의 공개 키와 비밀 키가 필요합니다. Omise 대시보드의 Settings > Keys에서 확인할 수 있습니다. 또한 Settings > Webhooks에 웹훅 엔드포인트가 필요합니다(구성 항목 참조).

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

설치

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

2. Activate를 클릭합니다.

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

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

5. Omise 테스트 키와 운영 키를 입력하고, 설정 페이지에 표시된 웹훅 URL을 Omise 대시보드에 추가합니다(구성 항목 참조).

6. Enable/Disable을 켭니다. 테스트 모드에서 4242 4242 4242 4242와 같은 Omise 테스트 카드로 결제를 테스트한 다음, Test mode 선택을 해제합니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Omise. 테스트 모드가 켜져 있는 동안에는 입력란 위에 Test mode is on — orders are charged with the test keys, no real money is moved.가 표시되며, 현재 모드의 공개 키 또는 비밀 키가 없거나 쇼핑몰 통화가 Omise에서 지원되지 않으면 경고가 표시됩니다. 두 경우 모두 체크아웃에서 해당 결제 수단이 숨겨집니다. 결제 수단 목록에서는 현재 모드의 두 키가 모두 입력될 때까지 Omise가 설정 필요 상태로 표시됩니다.

일반

Enable/Disable: Enable card payments via Omise는 결제 수단을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 체크아웃에서 보는 결제 수단 이름. 기본값: Credit / Debit Card.

Description: 체크아웃에서 카드 양식 위에 표시되는 텍스트. 기본값: Pay securely with your credit or debit card via Omise.

API 키

키는 Omise 대시보드의 Settings > Keys에서 확인할 수 있습니다. 테스트 키는 pkey_test_, skey_test_로 시작하고, 운영 키는 pkey_, skey_로 시작합니다. 저장할 때 잘못된 접두사의 키(예: 운영 키 입력란에 입력한 테스트 키)는 오류와 함께 거부되며, 이전 값이 유지됩니다.

Test mode: Use the test keys (no real charges). 두 키를 함께 전환합니다. 주문의 환불, 캡처, 상태 확인은 항상 주문이 결제된 모드의 키를 사용합니다. 기본값: 켬.

Test public key: 테스트 모드의 공개 키, pkey_test_...

Test secret key: 테스트 모드의 비밀 키, skey_test_...

Live public key: 운영 모드의 공개 키, pkey_...

Live secret key: 운영 모드의 비밀 키, skey_...

결제 및 웹훅

이 섹션에는 쇼핑몰의 웹훅 URL이 표시됩니다. 형식은 다음과 같습니다: https://your-site/wp-json/omise-payment/v1/webhook. 설정에 표시된 그대로 복사하여 Omise 대시보드의 Settings > Webhooks에 추가하십시오(HTTPS만 가능). 플러그인은 다음 이벤트를 처리합니다:

웹훅 본문은 결코 신뢰하지 않습니다. 결제는 주문에 저장된 결제와 일치해야 하며, 상태는 주문 모드의 키를 사용해 Omise API에서 다시 읽습니다. 웹훅이 없으면, 3-D Secure 중 고객이 브라우저를 닫은 주문은 Omise: Sync payment status를 실행할 때까지 보류 상태로 남으며, Omise 대시보드에서 이루어진 캡처는 자동으로 반영되지 않습니다.

Payment action: 카드 금액을 어떻게 처리할지 정합니다.

Per-charge webhook: Send the webhook URL with every charge. 여러 쇼핑몰이 하나의 Omise 계정을 공유할 때 유용합니다. 사이트가 HTTPS를 사용하는 경우에만 작동하며, 그렇지 않으면 대시보드 웹훅이 사용됩니다. 기본값: 끔.

고급

Debug log: Log API requests and payment events를 선택하면 결제 단계가 WooCommerce > Status > Logs에 소스 wcp_omise_payment로 기록됩니다. 키, 토큰, 카드 데이터는 절대 기록되지 않습니다. 기본값: 끔.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Credit / Debit Card)을 선택하고 카드 양식의 Name on card, Card number, Expiry month (MM), Expiry year (YYYY), Security code (CVV)를 입력합니다. 테스트 모드에서는 양식에 TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made.가 표시됩니다. 주문이 제출되면 Omise.js가 브라우저에서 카드를 일회용 토큰으로 바꿉니다. 카드 입력란은 쇼핑몰 서버로 전송되지 않습니다.

쇼핑몰은 주문 금액을 주문 통화로 비밀 키를 사용해 결제(청구)를 생성합니다. 결제 설명은 쇼핑몰 이름과 주문 번호이며, 주문 ID는 결제의 메타데이터에 저장됩니다. 은행이 3-D Secure를 요구하면 고객은 은행으로 이동한 뒤 쇼핑몰로 돌아옵니다. 결과는 항상 Omise API에서 다시 읽습니다.

주문은 Omise가 확인한 후에만 결제 완료로 표시됩니다. 결제가 캡처되어야 하며, 금액과 통화가 주문과 정확히 일치해야 합니다. Authorize only를 사용하면 승인이 성공한 후 주문이 보류 상태가 됩니다. 고객에게는 주문 접수 페이지가 표시됩니다.

카드가 거절되거나 3-D Secure가 실패하면 고객은 체크아웃에 머물며, 잔액 부족, 잘못된 보안 코드, 카드사 거절 등의 이유와 함께 Payment failed: 메시지를 보게 되고 다시 시도할 수 있습니다. 3-D Secure가 실패하면 고객은 Pay for order 페이지로 이동합니다. 3-D Secure 직후 결제를 바로 확인할 수 없으면 고객에게 We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.가 표시됩니다.

재시도로 이중 청구되지 않습니다. 주문의 이전 결제가 이미 결제되었거나 승인된 경우, 새로운 청구 없이 주문이 완료됩니다. 완료되지 않은 3-D Secure 시도는 새 결제가 생성되기 전에 만료됩니다.

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

이 플러그인은 카드 결제만 지원합니다. 다른 Omise 결제 수단(PromptPay, TrueMoney, 모바일 뱅킹, 할부, Konbini, PayNow), 저장된 카드나 Omise 고객, 구독, 부분 캡처는 지원하지 않습니다.

주문 및 환불

주문 상태

결제 대기: 고객이 3-D Secure 단계에 있거나 아직 결제를 완료하지 않았습니다.

처리 중: 결제가 확인되었습니다. 가상의 다운로드 가능한 상품만 있는 주문은 WooCommerce의 일반적인 방식대로 완료로 바뀝니다. 주문 메모에는 금액, 결제 ID, 확인 방식(체크아웃, 3-D Secure 복귀, 웹훅, 수동 캡처 또는 수동 동기화)이 표시됩니다. 거래 ID는 Omise 결제 ID(chrg_...)입니다.

보류, 캡처 대기: 카드가 Authorize only로 승인되었습니다. Omise: Capture payment 또는 Omise: Void authorization을 사용하십시오.

보류, 확인 대기: Omise가 아직 결제를 확인하지 않았습니다. 예를 들어 고객이 3-D Secure 중에 브라우저를 닫았을 수 있습니다. 웹훅 또는 Omise: Sync payment status가 주문을 업데이트합니다.

보류, 불일치: 결제의 금액 또는 통화가 주문과 다릅니다. 메모에 두 값이 모두 표시됩니다. 주문을 확인하고 완료하거나 결제를 환불하십시오.

실패: 결제가 거절되었습니다. 결제 완료된 주문은 이후의 실패 이벤트로 인해 하향 조정되지 않습니다.

취소됨: 결제가 만료되었거나 승인이 무효화되었습니다.

이미 취소되었거나 환불된 주문에 결제 완료 또는 승인된 결제가 도착하면 주문은 다시 열리지 않습니다. 메모에서 Omise 대시보드를 확인하고 수동으로 환불하거나 주문을 다시 열라는 안내가 표시됩니다.

주문 작업

Omise: Capture payment: 승인된 전체 금액을 캡처합니다. 승인된 주문에만 표시됩니다.

Omise: Void authorization: 승인을 무효화합니다. 돈은 캡처되지 않고 주문이 취소됩니다. 승인된 주문에만 표시됩니다.

Omise: Sync payment status: Omise에서 결제를 읽어 주문을 업데이트합니다. 메모에는 Omise에서 환불된 총액도 표시됩니다.

환불

주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Omise를 클릭합니다. 전액 환불과 부분 환불을 지원합니다. 환불은 결제가 이루어진 모드로 전송되므로, 해당 모드의 비밀 키가 설정되어 있어야 합니다. 환불이 성공하면 Omise 환불 ID와 함께 주문 메모에 추가됩니다. 아직 캡처되지 않은 승인에는 전액 환불만 가능하며, 이 경우 승인이 무효화됩니다. Omise가 환불을 거절하면 WooCommerce는 Omise 메시지와 함께 Refund failed.를 표시하며, 환불은 기록되지 않습니다.

Omise 대시보드에서 이루어진 환불은 WooCommerce 환불로 가져오지 않습니다. Omise: Sync payment status는 환불된 총액을 표시합니다. 필요한 경우 WooCommerce에서 해당하는 수동 환불을 생성하십시오.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 Omise가 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 두 키가 모두 입력되었는지(테스트 모드는 테스트 키, 그 외에는 운영 키), 그리고 통화가 지원되는지 확인하십시오. Pay for order 페이지에서는 주문 통화가 기준입니다. 키나 통화가 잘못된 경우 설정 페이지에 경고가 표시됩니다.

결제는 완료되었지만 주문이 결제 대기 또는 보류 상태로 남아 있음: 웹훅이 작동하지 않습니다. Omise 대시보드에서 웹훅 URL이 설정에 표시된 것과 정확히 일치하고 HTTPS를 사용하는지 확인하십시오. 그런 다음 주문에서 Omise: Sync payment status를 실행하십시오. 웹훅 응답을 보려면 Debug log를 켜십시오.

웹훅 응답이 Earlier charge of the order, order not changed인 경우: 이벤트는 재시도로 대체된 주문의 이전 시도에 관한 것입니다. 주문은 변경되지 않습니다. 해당 이전 결제가 Omise에서 아직 결제 완료 또는 승인 상태라면, 주문 메모가 한 번 알려줍니다. Omise 대시보드에서 이중 결제가 있는지 확인하고, 거기서 환불하거나 무효화하십시오.

웹훅 응답이 Charge ID does not match order인 경우: 이벤트의 결제는 다른 주문에 속합니다. 아무것도 변경되지 않습니다.

웹훅 응답이 Order is being processed, retry later 또는 Failed to verify charge인 경우: 주문이 다른 요청에 의해 잠겨 있었거나, Omise API에 연결할 수 없었습니다. Omise가 웹훅을 다시 시도합니다.

저장 시 오류: key must start with ... 또는 must be a live key: 키가 잘못된 입력란에 붙여넣어졌습니다. 테스트 키는 pkey_test_ / skey_test_, 운영 키는 pkey_ / skey_로 시작합니다.

고객에게 Card payments are temporarily unavailable가 표시됨: 키가 잘못되었거나 카드 토큰이 다른 모드의 것입니다(운영 모드에서 테스트 토큰을 사용하거나 그 반대). 키와 Test mode를 확인하십시오.

고객에게 We could not reach the payment provider가 표시됨: 결제를 생성하는 동안 Omise로부터 유효한 응답이 오지 않았습니다. 결제가 이미 생성되었을 수 있습니다. 주문 메모는 주문에 다시 청구하기 전에 Omise 대시보드를 확인하라고 안내합니다.

고객에게 This order is already being paid가 표시됨: 체크아웃이 같은 순간에 두 번 제출되었습니다. 고객은 기다렸다가 이메일을 확인한 후 다시 시도해야 합니다.

결제 후 주문이 보류 상태임: 주문 메모를 확인하십시오. 주문이 캡처를 기다리고 있거나, Omise가 아직 결제를 확인하지 않았거나, 금액 또는 통화가 주문과 다릅니다.

모드 관련 메시지와 함께 환불이 실패함: 결제가 테스트 또는 운영 모드에서 이루어졌는데, 해당 모드의 비밀 키가 설정되지 않았습니다. 키를 입력하고 다시 시도하십시오.

승인된 주문의 부분 환불이 실패함: 결제는 승인 상태일 뿐입니다. 먼저 캡처하거나, 전액을 환불하여 무효화하십시오.

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

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 완전히 제거하려면 Plugins 페이지에서 비활성화한 후 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그는 Delete data on uninstall이 켜져 있는 경우에만 삭제되며, 그렇지 않으면 이후 재설치를 위해 남겨집니다. 주문에 저장된 Omise 데이터는 결제 기록이므로 항상 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

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