VibeFox Xendit for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: 8.0 이상. 모듈은 이전 버전의 PHP에는 설치되지 않습니다.

쇼핑몰 통화: IDR, PHP, VND, THB, MYR, USD 또는 SGD. 그 밖의 장바구니 통화에서는 결제 수단이 표시되지 않습니다. 실제로 사용할 수 있는 결제 채널과 통화는 Xendit 계정에 따라 다릅니다.

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

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

설치

1. 백오피스에서 Modules > Module Manager로 이동하여 Upload a module을 클릭하세요. 모듈의 ZIP 파일을 선택하세요.

2. 업로드가 끝나면 Configure를 클릭하세요. 또는 나중에 모듈 목록에서 VibeFox Xendit Payment Gateway를 찾아 Configure를 클릭하세요.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key에 VibeFox 라이선스 키를 입력하고 Activate를 클릭하세요(라이선스 키 참조).

4. Xendit 시크릿 키를 붙여넣고, Xendit Dashboard에서 웹훅 URL을 설정한 뒤, 검증 토큰을 붙여넣으세요(구성 참조).

5. Enable/Disable을 켜고 Save를 클릭하세요. 테스트 모드에서 테스트 주문을 하고, 실제 결제를 받으려면 Test Mode를 끄세요.

설치 시 모듈은 Xendit payment on hold 주문 상태를 생성합니다. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다.

구성

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 입력란 위의 상자에는 현재 모드가 표시됩니다. 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: 테스트 시크릿 키로 인보이스를 생성하므로 실제 금액은 청구되지 않습니다. 기본값: 켜기. 실제 시크릿 키로 실제 결제를 받으려면 끄세요. 켜져 있는 동안 고객은 결제 수단 아래에서 Test mode: no real money is charged.를 보게 됩니다.

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

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

저장된 키와 토큰은 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요.

웹훅

웹훅은 인보이스가 결제되었음을 쇼핑몰에 알려 줍니다. Xendit Dashboard > Settings > Developers > Webhooks에서, 이 섹션의 Webhook URL에 표시된 URL을 테스트 모드와 실제 모드 모두에 대해 Invoices > Invoice paid로 설정하세요. 원하면 Invoice expired에도 설정할 수 있습니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_xendit_payment_gateway/webhook처럼 보이며, /en/ 같은 언어 코드가 붙을 수도 있습니다. 설정에 표시된 그대로 정확히 복사하세요.

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

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

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

Clear saved secrets: 키 또는 토큰에 체크한 뒤 Save를 클릭하면 삭제됩니다. 빈 입력란은 저장된 값을 유지합니다.

결제

Invoice Description: Xendit 인보이스에 표시되는 설명입니다. {order_id}, {order_number}, {site_name} 자리표시자를 사용할 수 있습니다. 주문은 결제 후에 생성되므로 {order_id}와 {order_number}는 장바구니 번호입니다. HTML은 제거되고 텍스트는 255자로 잘립니다. 기본값: Order #{order_id}.

Order Status After Payment: Xendit이 결제를 확인한 후 설정되는 주문 상태입니다.

고급

Debug Log: API 요청과 웹훅을 모듈 폴더의 logs/xendit_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 옵션이 꺼져 있어도 오류와 경고는 항상 기록됩니다. API 키, 토큰, 고객 데이터는 기록되지 않습니다. 기본값: 끄기.

Log: 로그의 크기와 최신 항목을 표시합니다. 비우려면 Clear log를 클릭하세요.

Delete Data on Uninstall: 켜져 있으면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문 데이터(주문의 인보이스 ID)와 Xendit payment on hold 주문 상태는 항상 유지됩니다. 기본값: 끄기.

체크아웃

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

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Xendit이 확인한 후에만 결제 완료로 표시됩니다. 웹훅으로 확인하거나, 고객이 돌아올 때 서버에서 Xendit API에 요청하여 확인합니다. 그런 다음 주문이 생성되고 고객은 표준 주문 확인 페이지를 보게 됩니다. Xendit이 아직 결제를 확인하지 않았다면 Payment confirmation 페이지가 나타나며, 여기에는 Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. 메시지와 Check again 및 Back to checkout 버튼이 표시됩니다. 웹훅이 도착하는 즉시 주문이 생성됩니다.

인보이스가 실패하거나 만료되면 Xendit은 고객을 되돌려 보냅니다. 모듈은 먼저 인보이스를 확인한 다음(다른 탭에서 결제되었을 수 있으므로), 더 이상 결제할 수 없도록 만료시킵니다. 고객은 The Xendit payment was not completed. You can try again or choose another payment method. 메시지와 함께 체크아웃으로 돌아갑니다. 장바구니는 유지됩니다.

고객은 같은 장바구니를 다시 결제할 수 있습니다. 장바구니 총액, 통화, 모드가 변경되지 않았고 열려 있는 인보이스가 앞으로 최소 5분 더 유효하다면, 고객은 같은 인보이스로 안내됩니다. 그렇지 않으면 기존 인보이스를 먼저 만료시키고 새 인보이스를 생성하므로, 같은 장바구니에 열려 있는 인보이스가 두 개 존재하는 일은 없습니다. 기존 인보이스가 이미 결제되었다면 새로 결제하는 대신 주문이 생성됩니다.

Xendit이 결제를 시작할 수 없으면 고객은 체크아웃에 머무르며 짧은 메시지를 보게 됩니다. 예를 들어 Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., 계정에서 해당 통화가 허용되지 않는다는 메시지, 또는 주문 총액이 Xendit의 금액 한도를 벗어났다는 메시지가 표시됩니다. 기술적인 원인은 로그에 기록됩니다. 총액이 0인 장바구니는 Xendit으로 결제할 수 없습니다.

웹훅은 쇼핑몰이 유지 보수 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

결제는 항상 Xendit 페이지에서 이루어집니다. 모듈은 백오피스에서의 환불, 저장된 카드, 구독 또는 정기 결제, 체크아웃 페이지의 카드 또는 전자지갑 입력란, 별도의 승인 및 캡처, xenPlatform 하위 계정을 지원하지 않습니다.

주문

주문 상태

아직 주문 없음: 고객이 Xendit으로 이동했지만 아직 결제하지 않았거나, Xendit이 아직 결제를 확인하지 않았습니다. 장바구니만 존재합니다.

Payment accepted or Delivered: 결제가 확인되었습니다. 상태는 Order Status After Payment를 따릅니다. 결제는 Xendit 인보이스 ID를 거래 ID로 하여 기록되며, 메모에는 인보이스 ID, 결제 금액, 결제 채널, 모드가 표시됩니다.

Xendit payment on hold: 결제 완료된 인보이스가 장바구니 총액이나 통화와 일치하지 않았거나, 총액보다 적은 금액이 결제되었습니다(예: 인보이스 생성 후 장바구니가 변경된 경우). 메모에 이유가 설명되어 있습니다. Xendit Dashboard에서 결제를 확인한 다음, 주문을 처리하거나 결제를 환불하세요. 같은 장바구니의 다른 인보이스가 나중에 올바른 금액으로 결제되면 결제가 기록되고 주문은 결제 완료 상태로 바뀝니다.

이미 취소되었거나 환불된 주문에 대해 인보이스가 결제되더라도 주문 상태는 바뀌지 않습니다. 메모에서 Xendit Dashboard에서 결제를 환불하거나 주문을 수동으로 복원하라고 안내합니다. 이미 결제된 주문에 두 번째 인보이스가 결제되면 주문은 바뀌지 않으며, 메모에서 Xendit Dashboard에서 중복 결제를 환불하라고 안내합니다.

Xendit payment 블록

주문 페이지에는 Xendit payment 블록이 표시됩니다. 여기에는 인보이스 ID, 모드(테스트 결제에는 Test mode 배지 포함), 결제 상태, 주문의 모든 인보이스 목록(날짜, 인보이스, 외부 ID, 금액 및 결제 금액, 상태, 결제 채널), 그리고 주문의 Payment notes가 포함됩니다.

환불

환불은 쇼핑몰에서 Xendit으로 전송되지 않습니다. Xendit Dashboard에서 결제를 환불하고(Xendit payment 블록에 표시된 인보이스 ID로 검색), 주문에 환불을 수동으로 기록하세요. 주문 페이지의 표준 PrestaShop 환불 버튼은 Xendit을 통해 돈을 돌려주지 않습니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Xendit Payment Gateway는 Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure의 맨 위, 설정 위에 있는 첫 번째 블록입니다. License key에 키를 붙여넣고 Activate를 클릭하세요. 그 후 블록에는 마스킹된 키, 상태(예: 라이선스가 유효한 날짜와 도메인), 그리고 Check now(상태 다시 확인), Change key(다른 키 입력), Remove key(이 쇼핑몰에서 키 제거) 버튼이 표시됩니다. 그 아래에는 Product: presta-payment-xendit 줄과 Manage licenses and domains in your account 링크가 있으며, 이 링크는 vibefox.net 계정을 엽니다. 이 모듈의 Configure 권한이 있는 직원만 키를 변경할 수 있습니다. 블록의 텍스트는 백오피스 언어를 따릅니다(영어와 러시아어 포함).

키가 받아들여지지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜와 함께 License expired on. 쇼핑몰 주소를 바꾼 후, 또는 계정에서 도메인 슬롯을 해제한 후에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 모듈은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 다중 스토어 구성에서도 메인 쇼핑몰의 도메인입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 체크아웃에서 고객에게 Xendit이 표시되지 않습니다. 결제가 그래도 시작되면 고객은 This payment method is not available. Please choose another one.를 봅니다. PrestaShop 스토어프런트는 백오피스에 로그인되어 있다는 것을 알지 못하므로, 결제 수단은 본인에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 체크아웃에서 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 표시됩니다. 기존 주문에는 영향을 주지 않습니다. 이미 시작된 결제는 계속 확인됩니다.

라이선스가 만료되어도 모듈은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 백오피스에서 작업하는 동안 상태는 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 후에는 주 1회입니다. cron 작업은 필요하지 않습니다. 모듈을 제거하거나 초기화하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

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

결제는 완료되었으나 주문이 생성되지 않음: 웹훅이 작동하지 않습니다. 사용 중인 모드(테스트 또는 실제)의 Xendit Dashboard에서 Webhook URL에 표시된 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과 토큰이 작동한다는 것을 확인해 줍니다. Ignored: unknown order와 Ignored: unknown invoice는 이 쇼핑몰이 장바구니 또는 인보이스를 알지 못한다는 뜻입니다.

웹훅 응답 Temporary error: 인보이스를 확인하기 위해 Xendit API에 연결할 수 없었거나, 인보이스 모드의 시크릿 키가 없거나, 같은 순간 다른 요청이 장바구니를 업데이트하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Xendit은 웹훅을 다시 시도합니다. 두 모드 모두에서 결제를 시작했다면 두 시크릿 키가 모두 설정되어 있는지 확인하고, 이유를 보려면 Debug Log를 켜세요.

브라우저에서 웹훅 URL에 Method not allowed가 표시됨: 정상입니다. 이 URL은 Xendit의 요청만 허용합니다.

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

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

고객에게 A payment for this order was already received by Xendit and is being reviewed가 표시됨: 이 장바구니의 이전 인보이스가 결제되었지만 주문을 아직 확인할 수 없었습니다. Xendit Dashboard와 로그에서 결제를 확인하세요.

고객에게 We could not match this payment to an order가 표시됨: Xendit의 반환 링크가 이 쇼핑몰의 장바구니에 속하지 않거나, 장바구니의 인보이스를 찾을 수 없었습니다. Xendit Dashboard와 로그에서 결제를 확인하세요.

결제 후 주문이 Xendit payment on hold 상태임: Xendit payment 블록의 메모를 읽으세요. 결제된 금액이나 통화가 장바구니와 달랐습니다. 주문을 처리하거나 Xendit Dashboard에서 결제를 환불하세요.

개발자를 위해 이 모듈은 인보이스 요청, 통화 목록, 통화별 소수점 자릿수를 변경할 수 있도록 actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies, actionWcpXenditCurrencyDecimals 훅을 제공합니다.

제거

Modules > Module Manager로 이동하여 VibeFox Xendit Payment Gateway 옆의 메뉴를 열고 Uninstall을 선택하세요. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete Data on Uninstall이 켜져 있으면 모듈 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. 주문의 Xendit 인보이스 데이터와 Xendit payment on hold 주문 상태는 항상 유지됩니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

Xendit은 각 소유자의 상표입니다. 이 모듈은 Xendit과 제휴하거나 Xendit의 승인을 받은 것이 아닙니다.