VibeFox Midtrans for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

쇼핑몰 통화: 인도네시아 루피아(IDR). 다른 통화에서는 체크아웃에서 결제 수단이 숨겨집니다. 통화 환산은 없습니다.

Midtrans 계정: Midtrans Dashboard > Settings > Access Keys의 Server Key가 필요합니다. 샌드박스 대시보드와 운영 대시보드에서 각각 확인하세요. Server Key만 사용됩니다. Snap Redirect에는 Client Key가 필요하지 않습니다. 결제 수단 자체(GoPay, QRIS, 가상계좌 등)는 Midtrans 계정에서 활성화합니다.

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

설치

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

2. Activate를 클릭합니다.

3. 쇼핑몰 통화를 인도네시아 루피아(IDR)로 설정합니다.

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

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

6. Server Key를 입력하고 결제 알림 URL을 복사해 Midtrans 대시보드에 설정합니다(설정 항목 참조).

7. Enable/Disable을 켭니다. Sandbox에서 테스트한 다음 Environment를 Production으로 전환합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Midtrans. 입력란 위에서 페이지는 선택한 환경의 Server Key가 없을 때(이 경우 체크아웃에서 결제 수단이 숨겨짐)와 쇼핑몰 통화가 IDR이 아닐 때 경고하며, Sandbox를 선택하면 Sandbox mode: payments are simulated, no real money is charged.를 표시합니다. 결제 수단 목록에서 Midtrans는 Server Key를 입력하기 전까지 설정 필요로 표시되고, Sandbox에서는 Test mode로 표시됩니다.

일반

Enable/Disable: Enable Midtrans payments는 결제 수단을 켜거나 끕니다. 기본값: off.

Title: 체크아웃에서 고객에게 표시되는 결제 수단 제목. 기본값: Midtrans.

Description: 체크아웃에서 결제 수단 아래에 표시되는 문구. 기본값: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. Sandbox에서는 SANDBOX MODE: no real money is charged. 줄이 추가됩니다.

API 자격 증명

Midtrans Dashboard > Settings > Access Keys에서 Server Key를 복사합니다. 이 섹션에는 운영 대시보드와 샌드박스 대시보드로 가는 링크가 있습니다.

Environment: 새 결제에 사용할 Midtrans 환경. 전환하면 선택한 환경의 키와 API가 사용됩니다. 주문은 환불과 알림을 위해 결제된 환경을 유지합니다. 기본값: Sandbox.

Sandbox: 테스트용, 실제 금액은 청구되지 않습니다.

Production: 실제 결제.

Production Server Key: Mid-server-로 시작합니다. 비밀로 유지하세요.

Sandbox Server Key: SB-Mid-server-로 시작합니다.

결제 알림 URL

알림은 결제가 이루어졌음을 쇼핑몰에 알려 줍니다. 이 섹션에는 사용할 URL이 표시됩니다. 형식은 https://your-site/wc-api/midtrans_p_callback/과 같습니다. 사용하는 샌드박스 대시보드와 운영 대시보드의 Midtrans Dashboard > Settings > Payment > Notification URL에 붙여 넣으세요. 브라우저에서 URL을 열면 짧은 설명이 나타나므로 접근 가능한지 확인할 수 있습니다. Midtrans 대시보드의 Test notification URL 버튼에도 응답합니다.

각 알림에는 Server Key 중 하나로 만든 유효한 서명이 있어야 하며, 키의 환경이 주문의 환경과 일치해야 합니다. 유효한 서명이 없는 알림은 거부됩니다. 이후 상태는 Midtrans 상태 API에서 다시 조회됩니다. 플러그인이 처리하는 Midtrans 거래 상태는 다음과 같습니다:

settlement, capture (accepted): 결제가 완료되었습니다. 금액(정수 루피아)과 통화가 일치하면 주문이 결제 완료로 표시됩니다.

capture (challenge): Midtrans 사기 탐지에 의해 표시된 카드 결제. Midtrans 대시보드에서 승인하거나 거부할 때까지 주문은 보류중 상태로 남습니다.

pending: 고객이 지연 결제 수단(가상계좌, 편의점 결제)을 선택했고 아직 결제하지 않았습니다. 주문은 보류중 상태가 됩니다.

expire: 미결제 거래의 기한이 지났습니다. 주문은 취소되고 재고가 복구됩니다. 포기된 카드 결제는 주문을 변경하지 않습니다.

cancel: 거래가 취소되었습니다. 주문은 취소됩니다.

deny: 결제가 거부되었습니다. challenge로 보류 중이던 주문은 실패가 됩니다. 그렇지 않으면 메모가 추가되고 고객은 다시 시도할 수 있습니다.

failure: 결제에 실패했습니다. 주문은 실패가 됩니다.

refund, partial_refund: Midtrans 대시보드에서 처리한 환불은 WooCommerce 환불로 기록됩니다.

결제 알림 URL이 없으면 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 주문이 확정됩니다.

결제 설정

Midtrans는 IDR로만 청구하며, 금액은 정수 루피아로 전송됩니다. 주문 항목의 합계가 반올림된 총액과 맞지 않으면 Midtrans로 Rounding adjustment 줄이 전송됩니다.

Status after payment: 결제 확인 후의 주문 상태. 상태는 한 번에 설정되며, 고객에게 이메일이 중복으로 발송되지 않습니다.

Processing: WooCommerce 기본값을 따르며, 다운로드 가능한 가상 상품만 있는 주문은 완료됨이 됩니다(기본값).

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

On hold: 결제된 모든 주문은 수동 검토를 기다립니다.

Payment page expiry (minutes): 고객이 결제할 수 있는 시간(Snap 페이지, 가상계좌 등). 비워 두거나 0을 입력하면 Midtrans 기본값이 사용됩니다.

Order ID prefix: Midtrans로 보내는 주문 번호 앞에 추가되어, 여러 쇼핑몰이 하나의 Midtrans 계정을 공유할 수 있습니다. 영문자, 숫자, - _ . ~만 허용되며 최대 20자입니다. 그 밖의 문자는 저장 시 제거됩니다. 다른 쇼핑몰의 알림은 무시됩니다. 기본값: WC-.

고급

Debug log: Log API calls and notifications를 켜면 WooCommerce > Status > Logs에 소스 wcp_midtrans_payment_gateway로 기록됩니다. 오류는 항상 기록됩니다. 키와 고객 데이터는 절대 기록되지 않습니다. 기본값: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. 기본값: off.

체크아웃

고객은 결제 수단(기본값 Midtrans)을 선택하고 주문을 제출합니다. 플러그인은 주문 금액을 정수 루피아로 하는 Midtrans Snap 거래를 생성하며, 주문 항목, 배송비, 세금과 고객의 청구지 및 배송지 정보를 포함해 고객을 Midtrans 결제 페이지로 보냅니다. 그곳에서 고객은 Midtrans 계정에서 활성화된 결제 수단 중 원하는 것을 선택합니다.

결제 후 고객은 쇼핑몰의 주문 접수 페이지로 돌아갑니다. 돌아오는 링크 자체로는 주문이 결제 완료되지 않습니다. 플러그인이 Midtrans 상태 API에 조회하고, Midtrans가 확인한 후에만 주문이 결제 완료로 표시됩니다. 결제가 확인되지 않은 동안 페이지에는 We are waiting for Midtrans to confirm your payment. ...가 표시됩니다. 페이지에는 사용된 결제 수단도 표시됩니다.

결제가 완료되지 않았다면 고객은 The Midtrans payment was not completed. You can try again below. 메시지와 함께 Pay for order 페이지로 이동합니다. 결제가 거부되었거나 만료되었다면 메시지는 Your Midtrans payment was declined or has expired. ...입니다. 고객이 다시 결제하면 같은 금액의 미사용 또는 대기 중인 Snap이 재사용됩니다. 금액이 바뀌었다면 먼저 Midtrans에서 대기 중인 거래의 기한을 만료시킵니다. 그 사이 이전 Snap이 결제되었다면 주문은 확정되고 새 거래는 만들어지지 않습니다.

Midtrans가 결제를 시작할 수 없다면 고객에게 Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us.(예: 잘못된 Server Key인 경우) 또는 Midtrans가 알려 준 사유가 표시됩니다. 기술적 사유는 주문 메모에 추가됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 동작합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

플러그인은 Snap Redirect만 사용합니다. Snap 팝업, 쇼핑몰 사이트의 카드 입력 양식, 저장된 카드나 원클릭 결제, 할부 또는 프로모션 설정(결제 수단은 Midtrans 대시보드에서 설정), WooCommerce Subscriptions는 지원하지 않습니다. 카드 결제는 즉시 캡처되며, 별도의 승인과 캡처는 없습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Midtrans로 이동했지만 아직 결제 수단을 선택하지 않았습니다.

On hold: 고객이 지연 결제 수단을 선택했고 아직 결제하지 않았거나, 카드 결제가 사기 검토(challenge) 중이거나, 결제된 금액 또는 통화가 주문과 일치하지 않습니다. 취소된 주문에 결제가 들어온 경우에도 보류중이 됩니다. 주문은 자동으로 다시 열리지 않습니다. 주문 메모에 이유가 설명됩니다.

Processing, Completed or On hold after payment: 결제가 확인되었습니다. 상태는 Status after payment를 따릅니다. 주문 메모에는 결제 수단과 Midtrans ID가 표시됩니다. 거래 ID는 Midtrans 거래 ID이며, 주문 화면에서는 주문이 결제된 환경의 Midtrans 대시보드에 있는 거래로 연결됩니다.

Failed: 결제에 실패했거나, challenge 상태였던 카드 결제가 거부되었습니다.

Cancelled: 미결제 거래의 기한이 지났거나 취소되었습니다. 재고는 복구됩니다. WooCommerce에서 미결제 Midtrans 주문을 취소하면(또는 미결제 주문 타이머가 취소하면), 발급된 가상계좌 같은 대기 중인 Midtrans 거래의 기한이 만료되어 더 이상 결제할 수 없게 됩니다.

이미 결제된 주문에 두 번째 결제가 들어와도 주문은 다시 변경되지 않습니다. 메모에서 Midtrans 대시보드를 통해 두 번째 결제를 환불하라고 안내합니다. 환불된 주문에 대한 결제는 메모만 추가합니다.

환불

주문을 열고 Refund를 클릭한 뒤 금액을 입력하고 Refund via Midtrans를 클릭합니다(버튼에는 Title이 표시됩니다). 전액 및 부분 환불은 정수 루피아 단위로 지원되며, 소수점이 있는 금액은 거부됩니다. 환불은 주문이 결제된 환경으로 전송되므로, 그 환경의 Server Key가 설정되어 있어야 합니다. Midtrans는 일부 결제 수단과 거래 상태에서만 API 환불을 허용합니다(예: 정산 완료된 카드, GoPay, QRIS 또는 ShopeePay 결제). Midtrans가 환불을 거부하면 WooCommerce는 오류를 표시하고 환불은 기록되지 않습니다. 이 경우 Midtrans 대시보드에서 환불하세요. 성공한 환불은 주문 메모에 추가됩니다.

Midtrans 대시보드에서 처리한 환불은 알림을 통해 도착하며, Refunded in the Midtrans dashboard 사유와 함께 WooCommerce 환불로 자동 기록됩니다.

라이선스 키

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

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

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

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

문제 해결

체크아웃에 Midtrans가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 Environment에 Server Key가 있는지 확인하세요. 쇼핑몰 통화(또는 Pay for order 페이지의 주문 통화)가 IDR인지 확인하세요. 설정 페이지는 이러한 문제마다 경고를 표시합니다.

결제는 완료되었지만 주문이 Pending payment 상태에 머묾: 알림이 작동하지 않습니다. 사용 중인 환경(샌드박스 또는 운영)의 Midtrans 대시보드에 결제 알림 URL이 설정되어 있고 접근 가능한지 확인하세요. 브라우저에서 열면 짧은 설명이 나타납니다. Debug log를 켜서 알림을 확인하세요. 고객이 결제 후 쇼핑몰로 돌아와도 주문은 확정됩니다.

알림 응답이 Invalid signature: 알림이 Sandbox 또는 Production Server Key로 서명되지 않았습니다. 설정의 키가 알림을 보내는 대시보드와 같은 Midtrans 계정에 속하는지 확인하세요.

알림 응답이 Server key not configured: Server Key가 설정되지 않았습니다. 설정에 입력하세요. Midtrans가 알림을 다시 시도합니다.

알림 응답이 Order not found — ignored: Midtrans 주문 ID가 이 쇼핑몰의 주문이 아닙니다. 예를 들어 같은 Midtrans 계정을 쓰는 다른 쇼핑몰에서 온 것입니다. 쇼핑몰마다 서로 다른 Order ID prefix를 지정하세요.

알림 응답이 Environment mismatch — ignored: 알림이 주문이 결제된 환경과 다른 환경의 키로 서명되었습니다.

알림 응답이 Verification failed, please retry: Midtrans 상태 API에 연결할 수 없습니다. Midtrans가 알림을 다시 시도합니다.

주문이 On hold 상태: 주문 메모를 읽으세요. 고객이 지연 결제를 완료하지 않았거나, 카드 결제가 사기 검토 중이거나, 결제된 금액 또는 통화가 주문과 일치하지 않습니다.

고객이 주문할 때 오류를 봄: 주문 메모를 열거나 Debug log를 켜고 WooCommerce > Status > Logs에서 소스 wcp_midtrans_payment_gateway를 확인하세요. IDR이 아닌 주문에는 Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.가 표시됩니다.

환불이 실패함: 결제 수단이나 거래 상태가 API 환불을 허용하지 않습니다. Midtrans 대시보드에서 환불하세요. 환불은 WooCommerce에 자동으로 기록됩니다. 메시지에 주문이 결제된 환경의 Server Key가 설정되지 않았다고 나오면 그 키를 입력하고 다시 시도하세요.

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

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 비활성화한 뒤 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정과 로그는 Delete data on uninstall이 켜져 있을 때만 삭제됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 남겨집니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

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