VibeFox PayMongo for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

통화: 필리핀 페소(PHP). PayMongo는 PHP 기준 장바구니에 대해서만 결제 시 표시됩니다. 쇼핑몰의 기본 통화가 PHP가 아니면 설정 페이지에 경고가 표시되며, 고객이 PayMongo를 보려면 PHP로 전환해야 합니다.

PayMongo 계정: PayMongo 계정의 API 시크릿 키와 모드별 웹훅이 필요합니다(설정 참조). 사용되는 것은 시크릿 키(sk_test_..., sk_live_...)와 웹훅 서명 시크릿(whsk_...)뿐입니다. 결제 페이지는 PayMongo가 호스팅하므로 공개 키는 필요하지 않습니다. 제공하는 결제 방법은 PayMongo 계정에서 활성화되어 있어야 합니다.

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

설치

1. 관리자 페이지에서 Modules > Module Manager로 이동하여 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox PayMongo Payment Gateway를 찾아 Configure를 클릭합니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key 필드에 VibeFox 라이선스 키를 입력한 후 Activate를 클릭합니다(라이선스 키 참조).

4. PayMongo 시크릿 키를 붙여넣고, PayMongo에서 웹훅을 만든 뒤 서명 시크릿을 붙여넣습니다(설정 참조).

5. 결제 방법을 선택하고 Enable/Disable을 켠 뒤 Save를 클릭합니다. Test mode를 켠 상태에서 결제를 테스트한 후 끕니다.

설치 시 모듈은 두 가지 주문 상태, Awaiting PayMongo payment와 PayMongo payment on hold를 생성합니다. Payment > Preferences에서 필리핀 페소, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 입력란 위에서 페이지는 쇼핑몰의 기본 통화가 PHP가 아닌 경우, 현재 모드에 시크릿 키가 없는 경우(이 경우 PayMongo는 결제 시 표시되지 않습니다) 또는 웹훅 시크릿이 없는 경우(이 경우 결제는 고객이 쇼핑몰로 돌아왔을 때에만 확인됩니다)에 경고를 표시합니다. 테스트 모드가 켜져 있는 동안에는 Test mode is on: no real payments are made.도 표시됩니다.

PayMongo

Enable/Disable: Enable PayMongo는 결제 방법을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 결제 시 보는 결제 방법 이름입니다. 주문에도 이 이름이 저장됩니다. 기본값: PayMongo (Card, GCash, GrabPay, Maya). 필수.

Description: 결제 시 결제 방법 아래에 표시되는 텍스트입니다. 기본값: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.

Payment methods: PayMongo 결제 페이지에서 제공되는 방법입니다. PayMongo 계정에서 활성화된 방법만 선택하십시오. 그렇지 않으면 PayMongo가 결제를 거부합니다. 아무것도 선택하지 않으면 기본값이 사용됩니다. 기본값: Cards, GCash, GrabPay and Maya.

Cards (Visa, Mastercard): 카드 결제입니다. 3-D Secure는 PayMongo가 처리합니다.

GCash, GrabPay, Maya, ShopeePay: 전자 지갑입니다.

QR Ph: QR 코드로 결제합니다.

BillEase, Atome: 지금 구매하고 나중에 결제합니다.

Direct online banking (BPI, UnionBank): 은행 계좌에서 결제합니다.

API 키

시크릿 키는 PayMongo Dashboard > Developers > API keys에서 복사합니다. 공개 키는 필요하지 않습니다. 각 키는 예상되는 접두사로 시작해야 합니다. 잘못된 접두사를 가진 값은 저장되지 않으며, 페이지에는 필드 must start with에 접두사가 있어야 한다는 안내와 The previous value was kept.가 표시됩니다.

Test mode: Enable test mode (no real payments). 새 결제는 테스트 키를 사용합니다. 이전에 이루어진 결제는 이루어진 모드를 유지하므로, 상태 확인과 환불은 해당 모드의 키를 사용합니다. 기본값: 켬. 실제 결제를 받으려면 끄십시오.

Test secret key: 테스트 모드의 시크릿 키입니다. sk_test_로 시작합니다.

Test webhook secret: 테스트 모드 웹훅의 서명 시크릿입니다. whsk_로 시작합니다.

Live secret key: 운영 모드의 시크릿 키입니다. sk_live_로 시작합니다.

Live webhook secret: 운영 모드 웹훅의 서명 시크릿입니다. whsk_로 시작합니다.

저장된 키와 시크릿은 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved secrets: 키나 시크릿에 체크하고 Save를 클릭하면 삭제됩니다. 빈 필드는 저장된 값을 유지합니다.

웹훅

웹훅은 고객이 결제 후 브라우저를 닫아도 결제가 이루어졌음을 쇼핑몰에 알립니다. 테스트 모드와 운영 모드 각각에 대해 PayMongo 대시보드(또는 PayMongo API)에서 이 섹션의 Webhook URL에 표시된 URL로 웹훅을 만드십시오. 친숙한 URL을 사용하면 https://your-shop/module/wcp_paymongo_payment_gateway/webhook과 같은 형태이며, /en/ 같은 언어 코드가 포함될 수도 있습니다. 설정에 표시된 URL을 정확히 복사하십시오.

다음 이벤트를 선택하십시오(이 섹션에도 나열되어 있습니다):

checkout_session.payment.paid: 고객이 PayMongo 결제 페이지에서 결제했습니다.

payment.paid: 결제가 완료되었습니다.

payment.failed: 결제 시도가 실패했습니다.

각 웹훅의 서명 시크릿(whsk_...)을 Test webhook secret 또는 Live webhook secret에 복사하십시오. 유효한 서명이 없는 웹훅은 거부됩니다. 서명은 해당 모드의 시크릿으로 검증되며, 이벤트의 모드가 일치해야 하므로 테스트 웹훅이 운영 결제를 확인하는 일은 없습니다. 주문을 생성하거나 변경하기 전에 모든 이벤트는 결제 모드의 시크릿 키로 PayMongo API를 통해 다시 확인됩니다. PayMongo는 계정 전체의 이벤트를 모든 웹훅에 보내며, 이 쇼핑몰에서 시작되지 않은 결제의 이벤트는 무시됩니다. 웹훅이 없으면 주문은 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 생성됩니다.

주문

Order status after payment: 결제 성공 후 설정되는 주문 상태입니다.

Payment accepted (Processing): 결제 완료된 주문에 대한 PrestaShop의 표준 상태입니다(기본값).

Delivered (Completed): 배송이 필요 없는 가상 상품이나 다운로드 상품에 적합합니다.

아직 처리 중인 결제는 Awaiting PayMongo payment 상태로 대기합니다. 금액 또는 통화 불일치와 운영 쇼핑몰의 테스트 결제는 항상 PayMongo payment on hold로 갑니다.

고급

Debug log: PayMongo API 호출과 웹훅 이벤트를 모듈 폴더의 logs/paymongo_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류와 경고는 스위치가 꺼져 있어도 항상 기록됩니다. 키와 고객 데이터는 절대 기록되지 않습니다. 기본값: 끔.

Log: 로그의 크기와 최신 항목을 보여줍니다. Clear log를 클릭하면 비워집니다.

Delete data on uninstall: 켜져 있으면 모듈을 제거할 때 설정과 로그가 삭제됩니다. 주문에 저장된 PayMongo ID, 환불 및 모듈의 주문 상태는 환불과 회계에 필요하므로 항상 보존됩니다. 기본값: 끔.

결제

결제 단계에서 고객은 결제 방법(기본값 PayMongo (Card, GCash, GrabPay, Maya))을 선택하고 그 설명을 봅니다. 테스트 모드에서는 결제 페이지에 Test mode: no real payment will be made.도 표시됩니다. PayMongo는 총액이 ₱100.00 이상인 PHP 기준 장바구니에 대해서만 제공됩니다.

확인 후 모듈은 PHP로 된 장바구니 총액에 대해 PayMongo Checkout Session을 만들고, Cart # 행과 장바구니 번호를 포함한 뒤 고객을 PayMongo 결제 페이지로 보냅니다. 고객의 이름, 이메일, 전화번호, 청구지 주소가 PayMongo에 전달됩니다. 고객은 그곳에서 선택된 방법 중 하나를 골라 결제합니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 PayMongo가 결제를 확인한 후에만 결제 완료로 표시됩니다. 모듈은 고객이 돌아왔을 때와 웹훅이 도착했을 때 PayMongo API에 결제 상태를 확인합니다. 그런 다음 주문이 생성되고, 고객은 Your PayMongo payment has been received.가 표시된 표준 주문 확인 페이지를 보게 됩니다. 고객이 돌아왔을 때 PayMongo가 아직 결제를 처리 중이면, 주문은 Awaiting PayMongo payment 상태로 생성되고 페이지에는 PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again.가 표시됩니다. 그 결제가 나중에 실패하면 페이지에 Your PayMongo payment was not completed. Please contact us about this order.가 표시됩니다. 고객이 돌아왔을 때 PayMongo에 연결할 수 없으면, 고객에게 다시 결제하지 말라고 안내하는 Payment confirmation 페이지와 Check again 버튼이 표시되며, 웹훅이 도착하는 즉시 주문이 생성됩니다.

고객이 PayMongo 페이지에서 취소하거나 결제를 완료하지 않으면, 고객은 You cancelled the PayMongo payment. You can try again or choose another payment method. 또는 Your PayMongo payment was not completed. You can try again or choose another payment method.라는 메시지와 함께 결제 단계로 돌아갑니다. 장바구니는 유지됩니다. 새 시도는 먼저 이전 시도를 확인합니다. 그 사이에 결제되었다면 추가 결제 없이 주문이 생성됩니다. 그렇지 않으면 이전 PayMongo 결제 링크가 만료되어 장바구니를 두 번 결제할 수 없습니다. 이전 결제가 아직 처리 중이면 고객에게 Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.가 표시됩니다.

PayMongo가 결제를 시작할 수 없으면 고객은 결제 단계에 머물며 짧은 메시지를 보게 됩니다. 예를 들어 The payment could not be started. Please try again or choose another payment method. 또는 PayMongo could not be reached. Please try again in a moment.입니다. 기술적인 원인은 로그에 기록됩니다.

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

모듈은 PayMongo 페이지에서 일회성 결제만 처리합니다. 쇼핑몰 자체 결제 페이지에는 카드 입력란이 없으며, 저장된 카드, 구독이나 정기 결제, 할부, 승인과 캡처의 분리도 지원하지 않습니다.

주문 및 환불

주문 상태

No order yet: 고객은 PayMongo로 보내졌지만 아직 결제하지 않았거나, PayMongo가 아직 결제를 확인하지 않았습니다. 장바구니만 존재합니다.

Payment accepted or Delivered: 결제가 확인되었습니다. 상태는 Order status after payment를 따릅니다. 결제는 거래 ID로 PayMongo 결제 ID(pay_...)와 함께 기록되며, 메모에는 결제, 금액, 방법, 모드, 확인 방식(웹훅 또는 복귀)이 표시됩니다.

Awaiting PayMongo payment: 고객이 PayMongo가 결제를 아직 처리 중일 때 돌아왔습니다. PayMongo가 확인하면 주문은 결제 완료 상태로 이동합니다.

PayMongo payment on hold: 결제된 금액 또는 통화가 장바구니 총액과 다릅니다(예: 결제가 시작된 후 다른 탭에서 장바구니가 변경된 경우). 또는 쇼핑몰이 운영 모드인 동안 테스트 모드에서 결제가 이루어져 돈이 입금되지 않았고 결제도 기록되지 않습니다. 또는 주문이 취소된 후에 결제가 도착했습니다. 메모에 그 이유가 설명되어 있습니다. 주문을 확인하여 처리하거나 결제를 환불하십시오.

Payment error: 서명된 payment.failed 웹훅이 Awaiting PayMongo payment 상태 주문의 최근 결제 시도가 실패했다고 알렸습니다. 메모에는 PayMongo의 실패 코드와 메시지가 표시됩니다. 같은 결제가 나중에 성공하면 주문은 결제 완료 상태로 이동합니다.

Refunded: 모듈을 통해 결제가 전액 환불되었습니다.

이미 결제된 주문에 대해 두 번째 결제가 도착하면(예: 오래된 결제 링크를 통해), 주문은 변경되지 않습니다. 메모에는 중복 결제를 PayMongo 대시보드에서 환불하라는 안내가 표시됩니다. 결제 후 취소되거나 환불된 주문은 다시 열리지 않습니다.

PayMongo payment 블록

주문 페이지에는 PayMongo 결제 ID와 방법, 결제 인텐트, 체크아웃, 모드, 상태, 결제 금액과 환불 금액, 테스트 결제용 Test mode 배지, 주문의 PayMongo 메모, 환불 내역이 포함된 PayMongo payment 블록이 표시됩니다.

환불

PayMongo payment 블록에서 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via PayMongo를 클릭합니다. Refund this amount through PayMongo? This cannot be undone. 확인 질문에 응답하십시오. 전액 및 부분 환불을 지원하며, 소수점은 최대 두 자리까지입니다. 주문을 편집할 권한이 필요하며, 모듈 페이지에 대한 접근 권한은 필요하지 않습니다. 환불은 PayMongo가 실제로 청구한 금액까지로 제한됩니다. 따라서 금액 불일치 후에는 주문 총액이 아니라 고객이 결제한 금액까지만 환불할 수 있습니다. 환불은 결제가 이루어진 모드(테스트 또는 운영)의 시크릿 키로 전송되므로 해당 모드의 키가 설정되어 있어야 합니다. 입력한 사유는 환불 메모로 PayMongo에 전달됩니다. PayMongo가 환불을 승인하지 않으면 블록에 오류가 표시되며 환불은 기록되지 않습니다. 성공한 환불은 PayMongo 환불 ID와 상태와 함께 환불 내역과 메모에 추가됩니다. 전액 환불 시 주문은 Refunded 상태가 됩니다. 부분 환불은 상태를 변경하지 않습니다.

모듈은 크레딧 전표를 생성하지 않습니다. 주문 페이지의 표준 PrestaShop 환불 버튼은 PayMongo를 통해 돈을 돌려보내지 않습니다. PayMongo 대시보드에서 진행한 환불은 PrestaShop에 복사되지 않습니다. 대신 주문 블록에서 환불하거나 주문을 수동으로 업데이트하십시오.

라이선스 키

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

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

키 하나는 도메인 하나에서 작동합니다. 기본 쇼핑몰의 도메인이며, 멀티스토어 구성에서도 마찬가지입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

PayMongo가 결제 시 표시되지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드에 시크릿 키가 있는지(테스트 모드는 Test secret key, 운영 모드는 Live secret key), 장바구니가 PHP인지, 총액이 ₱100.00 이상인지 확인하십시오. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객의 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

결제는 되었지만 주문이 생성되지 않음: 웹훅이 작동하지 않고 고객이 쇼핑몰로 돌아오지 않았습니다. PayMongo 대시보드에서 사용 중인 모드에 웹훅이 있는지, 그 URL이 Webhook URL에 표시된 것과 정확히 같은지, 세 이벤트가 모두 선택되어 있는지 확인하십시오. 서명 시크릿이 해당 필드(Test webhook secret 또는 Live webhook secret)에 들어 있는지 확인하십시오.

웹훅이 Invalid signature를 응답함: 해당 모드의 서명 시크릿이 없거나 다른 웹훅의 것입니다. 웹훅의 서명 시크릿을 해당 모드의 필드에 붙여넣으십시오.

웹훅이 Mode mismatch를 응답함: 테스트 이벤트가 운영으로 서명되었거나 그 반대입니다. 각 웹훅이 올바른 모드에 속하는지 확인하십시오.

웹훅이 Temporary error를 응답함: 결제 모드의 시크릿 키가 없는 등의 이유로 PayMongo API를 통해 결제를 확인할 수 없었습니다. PayMongo는 웹훅을 자동으로 재시도합니다.

웹훅이 Busy, retry를 응답함: 같은 순간 다른 요청이 주문을 확인하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화된 경우). PayMongo는 웹훅을 자동으로 재시도합니다. 이유는 Log에 있습니다.

웹훅이 Ignored를 응답함: 이벤트가 이 쇼핑몰에서 시작되지 않은 결제 또는 다른 모드의 결제에 속합니다. 아무것도 변경되지 않습니다.

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

값이 저장되지 않음: 키를 잘못된 필드에 붙여넣었습니다. 시크릿 키는 sk_test_ 또는 sk_live_로, 웹훅 시크릿은 whsk_로 시작합니다.

고객이 PayMongo를 선택할 때 오류가 표시됨: 모듈 페이지의 Log 필드를 확인하십시오. 잘못된 시크릿 키는 결제 방법을 일시적으로 사용할 수 없다는 메시지를 표시합니다. PayMongo 계정에서 활성화되지 않은 결제 방법이 있으면 PayMongo가 결제를 거부합니다. 그 방법을 Payment methods에서 제거하십시오.

운영 쇼핑몰에서의 테스트 결제: 쇼핑몰이 운영 모드인 동안 도착한 테스트 결제는 주문을 PayMongo payment on hold 상태로 만들고, 돈이 입금되지 않았다는 메모를 남깁니다. 운영 결제는 테스트 모드로 돌아간 후에도 항상 인식되며, 운영 키로 환불됩니다.

결제 후 주문이 PayMongo payment on hold 상태임: PayMongo payment 블록의 메모를 읽은 후(주문 상태 참조), 주문을 처리하거나 결제를 환불하십시오.

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

개발자는 actionPaymongoPCheckoutSessionData 훅으로 Checkout Session 데이터를 변경할 수 있습니다.

제거

Modules > Module Manager로 이동하여 VibeFox PayMongo Payment Gateway 옆의 메뉴를 열고 Uninstall을 선택하십시오. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data on uninstall이 켜져 있으면 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 보존됩니다. 주문의 PayMongo ID, 환불, 그리고 Awaiting PayMongo payment 및 PayMongo payment on hold 주문 상태는 항상 보존되므로, 이전에 결제된 주문도 재설치 후에 환불할 수 있습니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

PayMongo는 해당 소유자의 상표입니다. 이 모듈은 PayMongo와 제휴하거나 PayMongo의 승인을 받은 것이 아닙니다.