VibeFox Xendit for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

상점 통화: IDR, PHP, VND, THB, MYR, USD 또는 SGD. 다른 통화에서는 결제 수단이 표시되지 않습니다. 실제로 사용할 수 있는 결제 채널과 통화는 Xendit 계정에 따라 다릅니다.

Xendit 계정: 테스트 모드용으로 Money-in(인보이스)에 쓰기 권한이 있는 시크릿 API 키가 필요하고, 실제 모드용으로 다른 키가 하나 더 필요합니다. 각 모드의 웹훅 검증 토큰도 필요합니다(설정 참조). 시크릿 키와 검증 토큰만 사용됩니다. 고객은 Xendit이 호스팅하는 인보이스 페이지에서 결제하므로 공개 키는 필요하지 않습니다.

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

설치

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

2. Activate를 클릭합니다.

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

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

5. Xendit 시크릿 키를 붙여넣고, Xendit Dashboard에서 웹훅 URL을 설정한 뒤 검증 토큰을 붙여넣습니다(설정 참조).

6. Enable/Disable을 켭니다. 테스트 모드에서 테스트 주문을 하고, 실제 결제를 받으려면 Test Mode 체크를 해제합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Xendit. 입력란 위의 배너는 활성 모드를 보여줍니다. TEST MODE(인보이스는 테스트 시크릿 키로 생성되며 실제 금액은 청구되지 않습니다) 또는 LIVE MODE(인보이스는 실제 시크릿 키로 생성되며 고객에게 청구됩니다). 배너는 활성 모드의 시크릿 키가 없거나 접두사가 잘못된 경우(이때 체크아웃에서 결제 수단이 숨겨짐), 그리고 활성 모드의 웹훅 검증 토큰이 비어 있는 경우(Xendit 알림이 거부되어 고객이 쇼핑몰로 돌아왔을 때만 주문이 업데이트됨)에 경고합니다. 결제 수단 목록에서 Xendit은 활성 모드에 유효한 시크릿 키가 생길 때까지 설정이 필요한 것으로 표시됩니다.

일반

Enable/Disable: Enable Xendit은 결제 수단을 켜거나 끕니다. 기본값: 끔.

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트. 기본값: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

API 키

Xendit Dashboard > Settings > Developers > API keys에서 Money-in(인보이스)에 쓰기 권한이 있는 시크릿 API 키를 만듭니다. 테스트 모드에서 한 번, 실제 모드에서 한 번 만드세요. 키는 인보이스가 생성될 위치를 결정합니다. 저장할 때 접두사가 해당 입력란과 맞지 않는 키는 저장되지 않으며, 페이지에 예를 들어 Test secret key was not saved: it must start with xnd_development_가 표시됩니다. 나머지 설정은 저장됩니다.

Test Mode: Enable test mode는 테스트 시크릿 키로 인보이스를 생성하므로 실제 금액이 청구되지 않습니다. 기본값: 켬. 실제 결제를 받으려면 체크를 해제하고 실제 시크릿 키를 사용합니다.

Test Secret Key: Xendit 테스트 모드의 시크릿 키. xnd_development_로 시작합니다.

Live Secret Key: Xendit 실제 모드의 시크릿 키. xnd_production_으로 시작합니다.

웹훅

웹훅은 인보이스가 결제되었음을 쇼핑몰에 알려 줍니다. Xendit Dashboard > Settings > Developers > Webhooks에서 설정의 이 섹션에 표시된 URL을 테스트 모드와 실제 모드 모두에 대해 Invoices > Invoice paid로 설정합니다. 선택 사항으로 Invoice expired에도 설정할 수 있습니다. URL은 다음과 같은 형식입니다: https://your-site/wc-api/xendit_p_callback/. 설정에 표시된 그대로 정확히 복사하세요.

그다음 Xendit Dashboard에서 각 모드의 Webhook verification token을 해당 입력란에 복사합니다. Xendit은 이 토큰을 x-callback-token 헤더로 보냅니다. 인보이스가 생성된 모드의 토큰이 없는 알림은 거부됩니다. 토큰은 알림이 Xendit에서 왔다는 것만 증명합니다. 인보이스 상태, 금액, 통화는 항상 해당 모드의 시크릿 키로 Xendit API에서 다시 조회합니다. 웹훅이 없으면 주문은 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 확인됩니다.

Test Webhook Verification Token: Xendit 테스트 모드의 웹훅 검증 토큰.

Live Webhook Verification Token: Xendit 실제 모드의 웹훅 검증 토큰.

결제

Invoice Description: Xendit 인보이스에 표시되는 설명. {order_id}, {order_number}, {site_name} 자리표시자를 사용할 수 있습니다. HTML은 제거되고 텍스트는 255자로 잘립니다. 기본값: Order #{order_id}.

Order Status After Payment: Xendit이 결제를 확인한 뒤 설정되는 주문 상태. 한 번의 상태 변경으로 즉시 설정됩니다.

고급

Debug Log: Log API requests and webhooks는 요청, 웹훅, 상태 변경을 WooCommerce > Status > Logs에 기록합니다. 소스는 wcp_xendit_payment_gateway입니다. 이 옵션이 꺼져 있어도 오류와 경고는 항상 기록됩니다. API 키, 토큰, 고객 데이터는 기록되지 않습니다. 기본값: 끔.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다. 주문 데이터(주문에 있는 인보이스 ID)는 항상 유지됩니다. 기본값: 끔.

체크아웃

상점 통화가 IDR, PHP, VND, THB, MYR, USD 또는 SGD이면 결제 수단이 표시됩니다. Pay for order 페이지에서는 주문 통화가 기준이 됩니다. 고객은 결제 수단(기본값 Xendit)을 선택하고 주문합니다. 플러그인은 주문 통화로 주문 총액에 대한 Xendit 인보이스를 생성하고, 고객을 Xendit 인보이스 페이지로 보냅니다. Xendit은 IDR과 VND에 소수점을 허용하지 않으므로 이 통화의 금액은 정수로 반올림됩니다. 고객의 청구 이메일 주소는 Xendit에 전달됩니다. 인보이스 페이지에서 고객은 이 통화에 대해 Xendit 계정에서 활성화된 결제 채널(예: 가상계좌, 전자지갑, QR 코드, 오프라인 매장 또는 카드) 중 하나로 결제합니다.

결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 주문은 Xendit이 확인한 후에만 결제 완료로 표시됩니다. 웹훅으로 확인되거나, 고객이 해당 페이지에 도착할 때 서버에서 Xendit API로 보낸 요청으로 확인됩니다. 그때까지 주문은 결제 대기 상태로 남습니다.

인보이스가 실패하거나 만료되면 Xendit은 고객을 다시 보냅니다. 체크아웃에서 한 주문은 WooCommerce 표준 방식으로 취소되고, 해당 인보이스는 만료됩니다. Pay for order 페이지에서 결제하는 주문(예: 고객을 위해 만든 주문)은 The Xendit payment was not completed. You can try again or choose another payment method. 메시지와 함께 결제 페이지로 돌아가며, 계속 결제할 수 있습니다.

고객은 미결제 주문을 다시 결제할 수 있습니다. 주문 총액, 통화, 모드가 변경되지 않았고 열려 있는 인보이스가 여전히 유효하면, 고객은 같은 인보이스로 안내됩니다. 그렇지 않으면 기존 인보이스가 먼저 만료되고 새 인보이스가 생성되므로, 한 주문에 열린 인보이스가 두 개 있는 일은 없습니다. 기존 인보이스가 이미 결제되었다면, 새로 결제하는 대신 주문이 완료됩니다.

Xendit이 결제를 시작할 수 없으면 고객에게 짧은 메시지가 표시되고, 다른 결제 수단을 선택할 수 있습니다. 예를 들어 Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., 계정에서 해당 통화를 허용하지 않는다는 메시지 또는 주문 총액이 Xendit 금액 한도를 벗어났다는 메시지가 표시됩니다. 기술적인 이유는 로그에 기록됩니다. 총액이 0인 주문은 Xendit으로 결제할 수 없습니다.

결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. 테스트 모드에서는 체크아웃 블록이 결제 수단 아래에 Test mode: no real money is charged.를 표시합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

결제는 항상 Xendit 페이지에서 이루어집니다. 플러그인은 WooCommerce에서의 환불, 저장된 카드, 구독 또는 정기 결제, 체크아웃 페이지의 카드 또는 전자지갑 입력란, 별도의 승인 및 캡처, xenPlatform 하위 계정, 사용자 지정 인보이스 만료 시간, 결제 수수료를 지원하지 않습니다.

주문

주문 상태

Pending payment: 인보이스는 생성되었지만 고객이 아직 결제하지 않았거나, Xendit이 아직 결제를 확인하지 않았습니다. 주문 메모에는 인보이스 ID, 금액, 통화, 모드가 표시됩니다.

Processing or Completed: 결제가 확인되었습니다. 상태는 Order Status After Payment 설정을 따릅니다. 주문 메모에는 인보이스 ID, 결제 금액, 결제 채널, 모드가 표시됩니다. 거래 ID는 Xendit 인보이스 ID입니다.

On hold: 결제된 인보이스가 주문 총액이나 통화와 일치하지 않았거나, 총액보다 적은 금액이 결제되었습니다(예: 인보이스를 만든 뒤 주문이 수정된 경우). 주문 메모에 이유가 설명되며, 주문이 이미 보류 상태였던 경우에도 마찬가지입니다. Xendit Dashboard에서 결제를 확인한 뒤 주문을 처리하거나 결제를 환불하세요.

Failed: 현재 인보이스가 결제 없이 만료되었습니다. 고객은 주문을 다시 결제할 수 있습니다.

Cancelled: 고객이 실패했거나 만료된 인보이스에서 돌아왔거나, 주문이 귀하 또는 미결제 주문에 대한 WooCommerce 시간 제한으로 취소되었습니다. 열려 있는 인보이스는 만료되므로 더 이상 결제할 수 없습니다. Xendit이 이를 허용하지 않으면, 메모에서 Xendit Dashboard에서 인보이스를 만료시키라고 안내합니다.

이미 결제, 취소 또는 환불된 주문에 대해 인보이스가 결제되면 주문은 변경되지 않습니다. 메모에서 Xendit Dashboard에서 결제를 환불하거나 주문을 수동으로 복구하라고 안내합니다.

환불

환불은 WooCommerce에서 Xendit으로 전송되지 않습니다. Xendit Dashboard에서 결제를 환불하고(주문 메모와 거래 ID에 인보이스 ID가 포함됩니다), WooCommerce에는 환불을 수동으로 기록하세요.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 Xendit이 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 활성 모드에 올바른 접두사의 시크릿 키가 있는지(테스트 모드에서는 xnd_development_로 시작하는 Test Secret Key, 실제 모드에서는 xnd_production_으로 시작하는 Live Secret Key), 그리고 상점 통화가 IDR, PHP, VND, THB, MYR, USD 또는 SGD인지 확인하세요. 키가 없거나 잘못된 경우 설정 배너에 경고가 표시됩니다.

결제는 완료됐지만 주문이 결제 대기 상태로 남아 있음: 웹훅이 작동하지 않습니다. 사용 중인 모드(테스트 또는 실제)의 Xendit Dashboard에서 설정에 표시된 URL이 Invoice paid에 설정되어 있는지, 그리고 해당 모드의 검증 토큰이 해당 입력란에 저장되어 있는지 확인하세요. Xendit Dashboard에는 각 웹훅에 대한 쇼핑몰의 응답이 표시됩니다. 고객이 주문 접수 페이지로 돌아오면 주문도 확인됩니다.

웹훅 응답 「Webhook verification token is not configured」: 두 검증 토큰이 모두 설정되지 않았습니다. 설정에 토큰을 붙여넣으세요.

웹훅 응답 「Unauthorized」: Xendit이 보낸 토큰이 설정의 어떤 토큰과도 일치하지 않습니다. 올바른 모드의 토큰을 다시 복사하세요.

웹훅 응답 「Token does not match the mode of this invoice」: 인보이스가 다른 모드에서 생성되었습니다. 테스트 알림은 실제 주문을 절대 확인하지 않으며, 반대도 마찬가지입니다. 주문이 결제된 모드에서 웹훅과 토큰을 설정하세요.

웹훅 응답 「Ignored: not an invoice of this store」: 인보이스가 이 쇼핑몰에서 생성되지 않았습니다. 예를 들어 같은 Xendit 계정의 다른 연동에서 생성되었습니다. Xendit Dashboard의 Test 버튼도 이 응답을 받으며, 이는 URL과 토큰이 작동한다는 것을 확인해 줍니다.

웹훅 응답 「Temporary error」: 인보이스를 확인하기 위해 Xendit API에 연결할 수 없었거나, 인보이스 모드의 시크릿 키가 없거나, 같은 순간 다른 요청이 주문을 업데이트하고 있었습니다. Xendit은 웹훅을 다시 시도합니다. 두 모드의 주문이 있다면 두 시크릿 키가 모두 설정되어 있는지 확인하세요.

키가 저장되지 않음: 값이 해당 입력란의 접두사로 시작하지 않습니다. 테스트 키는 xnd_development_, 실제 키는 xnd_production_으로 시작합니다.

고객에게 「This payment method is temporarily unavailable」가 표시됨: Xendit이 요청을 거부했습니다. 예를 들어 시크릿 키가 잘못되었거나 Money-in(인보이스)에 쓰기 권한이 없는 경우입니다. 필요하면 Debug Log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_xendit_payment_gateway를 확인하세요. 청구 정보에 관한 메시지는 Xendit이 요청 데이터(예: 이메일)를 받아들이지 않았다는 뜻입니다.

고객에게 「A payment for this order was already received by Xendit and is being reviewed」가 표시됨: 이 주문의 이전 인보이스가 결제되었지만 주문과 일치하지 않아 주문이 보류 상태입니다. Xendit Dashboard에서 결제를 확인하세요.

결제 후 주문이 On hold 상태임: 주문 메모를 읽어 보세요. 결제된 금액이나 통화가 주문과 달랐습니다. 주문을 처리하거나 Xendit Dashboard에서 결제를 환불하세요.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 다음 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정, 플러그인의 기타 옵션, 임시 데이터, 로그(순환된 로그 파일, 데이터베이스 로그 항목, 버전 1.0의 로그 폴더 포함)는 Delete Data on Uninstall이 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 남아 있습니다. 기존 주문은 결제 메모, 인보이스 ID, 거래 ID를 유지합니다.

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