VibeFox MercadoPago for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0–9.x.

PHP: 8.0 이상. 이전 버전의 PHP에서는 모듈 설치가 거부됩니다.

쇼핑몰 통화: MercadoPago 계정 국가의 통화입니다: ARS(아르헨티나), BRL(브라질), CLP(칠레), COP(콜롬비아), MXN(멕시코), PEN(페루) 또는 UYU(우루과이). MercadoPago는 계정 통화로 청구하며 통화 변환을 하지 않으므로, 다른 통화의 장바구니에서는 결제 수단이 숨겨집니다.

MercadoPago 계정: MercadoPago 개발자 패널(Your integrations > your application > Credentials)에서 애플리케이션을 만들고, 테스트 자격 증명(TEST-로 시작)과 실서비스 자격 증명(APP_USR-로 시작)을 준비해야 합니다. 각각 Public Key와 Access Token이 있습니다. 알림의 선택적 서명 확인을 사용하려면 your application > Webhooks에 표시되는 서명 시크릿도 필요합니다.

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

설치

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

2. 업로드가 끝나면 Configure를 클릭합니다. 나중에 모듈 목록에서 VibeFox MercadoPago Gateway를 찾아 Configure를 클릭해도 됩니다.

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

4. Account country를 선택하고, 테스트 및 실서비스 자격 증명을 입력합니다. 필요하면 MercadoPago 애플리케이션에서 알림을 설정합니다(설정 참조).

5. Enable / Disable을 켜고 Save를 클릭합니다. 테스트 모드에서 MercadoPago 테스트 카드로 결제를 시도한 다음 Test mode를 끕니다.

설치 시 모듈은 두 가지 주문 상태를 만듭니다: Awaiting MercadoPago payment와 MercadoPago payment on hold. PrestaShop은 설치 시점에 활성화된 국가에 새 결제 모듈을 할당합니다. Payment > Preferences에서 모듈의 통화, 국가, 고객 그룹을 확인하십시오.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. 각 섹션에는 자체 Save 버튼이 있으며, 이 버튼은 페이지 전체를 저장합니다. 테스트 모드가 켜져 있는 동안 입력란 위에 Test mode is on: the TEST- credentials are used and no real money is charged. 문구가 표시됩니다. 또한 현재 모드의 Public Key 또는 Access Token이 없거나, 쇼핑몰 통화가 MercadoPago 계정의 통화와 다르거나(이 경우 결제 시 결제 수단이 숨겨집니다), 자격 증명이 Account country와 다른 국가의 계정에 속하면 경고합니다.

저장할 때 예상 접두사(테스트 입력란은 TEST-, 실서비스 입력란은 APP_USR-)로 시작하지 않는 자격 증명은 저장되지 않으며, must start with … — the previous value was kept. 오류가 표시됩니다. 모듈은 또한 MercadoPago에 각 Access Token이 어느 국가의 것인지 조회합니다. 현재 모드의 토큰을 확인할 수 없거나, 계정이 지원되지 않는 국가에 있거나, 국가가 Account country와 다르면 오류가 표시됩니다. 이 경우 모듈은 계정의 국가를 사용합니다.

MercadoPago

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

Title: 결제 시 고객에게 표시되는 결제 수단 이름입니다. 주문에도 이 이름이 저장됩니다. 기본값: Credit or debit card (MercadoPago). 필수.

Description: 결제 시 카드 입력란 위에 표시되는 텍스트입니다. 기본값: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

MercadoPago 계정

MercadoPago 개발자 패널에서 애플리케이션의 자격 증명을 가져오십시오: Your integrations > your application > Credentials. 테스트 자격 증명은 TEST-로, 실서비스 자격 증명은 APP_USR-로 시작합니다.

Account country: MercadoPago 계정의 국가입니다. 청구 통화, 카드 입력란의 언어, 카드 소유자 문서 입력 여부를 결정합니다. 쇼핑몰 통화도 같아야 합니다(예: 아르헨티나는 ARS). 자격 증명을 저장하면 국가가 계정과 대조됩니다. 기본값: Argentina (ARS).

Test mode: 테스트 모드에서는 TEST- 자격 증명을 사용하며, MercadoPago 테스트 카드로 결제합니다. 체크아웃에 TEST MODE 배지가 표시됩니다. 실서비스 자격 증명으로 실제 카드에 청구하려면 끄십시오. 기본값: on.

Test Public Key: TEST-로 시작합니다. 브라우저에서 카드를 토큰화하는 데 사용됩니다.

Test Access Token: TEST-로 시작합니다. 서버에서만 사용됩니다. 비밀로 유지하십시오.

Production Public Key: APP_USR-로 시작합니다.

Production Access Token: APP_USR-로 시작합니다. 서버에서만 사용됩니다. 비밀로 유지하십시오.

저장된 Access Token과 웹훅 시크릿은 다시 표시되지 않습니다. 입력란은 비어 있으며 Saved — leave empty to keep it. 문구가 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오.

결제 옵션

Maximum installments: 고객이 선택할 수 있는 최대 할부 개월 수입니다. 1부터 24까지 설정할 수 있습니다. 1 = 일시불만 가능하며, 할부 입력란은 표시되지 않습니다. 이 한도는 서버에서도 적용됩니다. 기본값: 1.

결제 알림(웹훅)

카드 결제는 보통 즉시 최종 결과를 받습니다. MercadoPago가 검토 중(처리 중 또는 대기 중)으로 보류한 결제는 MercadoPago 알림으로 완료됩니다. 쇼핑몰에 공개 주소가 있으면(localhost나 .local, .test 도메인이 아닌 경우) 모듈은 각 결제와 함께 알림 URL을 보냅니다. your application > Webhooks에서 Payments 이벤트로 URL을 추가할 수도 있습니다. URL은 이 섹션의 Notification URL에 표시됩니다. 친숙한 URL을 사용하면 https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks 형태입니다. 설정에 표시된 그대로 URL을 정확히 복사하십시오.

알림은 그 자체로 신뢰되지 않습니다. 모듈은 결제가 이루어진 환경의 Access Token으로 MercadoPago API에서 결제를 다시 조회하고, 이를 쇼핑몰의 결제 시도와 연결합니다. 알림이 없으면 검토 중인 주문은 직접 업데이트할 때까지 Awaiting MercadoPago payment 상태로 남습니다.

모듈은 다음 MercadoPago 결제 상태를 처리합니다:

Webhook secret signature: 선택 사항입니다. your application > Webhooks에 표시되는 서명 시크릿입니다. 설정하면 유효한 x-signature가 없는 알림은 거부됩니다(HTTP 401).

Clear saved secrets: Test Access Token, Production Access Token 또는 Webhook secret signature에 체크하고 Save를 클릭하면 삭제됩니다. 입력란이 비어 있으면 저장된 값이 유지됩니다.

고급

Debug log: MercadoPago 요청과 알림을 모듈 폴더의 logs/wc_mpg_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류는 이 설정이 꺼져 있어도 항상 기록됩니다. Access Token, 카드 토큰, 결제자 데이터는 기록되지 않습니다. 기본값: off.

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

Delete data on uninstall: 켜면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. MercadoPago 결제 기록, 환불, 모듈의 주문 상태는 항상 남으므로, 재설치 후에도 이전에 결제된 주문을 환불할 수 있습니다. 기본값: off.

체크아웃

결제 단계에서 고객은 결제 수단(기본값 Credit or debit card (MercadoPago))을 선택하고 카드 입력란을 채웁니다: Card number, Expiry (MM/YY), Security code, Cardholder name. 국가와 카드에 따라 고객은 Document type을 선택하고 Document number를 입력하며, Card issuer와 Installments 개월 수도 선택합니다. 할부 옵션과 이자는 장바구니 합계에 대해 MercadoPago가 제공합니다. 카드 양식은 Classic 및 Hummingbird 테마에서 작동합니다.

고객이 확인하면 MercadoPago가 카드를 일회용 토큰으로 바꾸고, 쇼핑몰은 장바구니 합계에 대한 결제를 서버에서 생성합니다. 고객의 이메일과 이름, 문서, 장바구니 번호는 MercadoPago로 전달되며, 결제는 Cart #, 장바구니 번호, 쇼핑몰 이름으로 표시됩니다. CLP와 COP 금액은 소수점 없이 청구됩니다. MercadoPago가 응답하기 전에는 주문이 존재하지 않습니다.

승인된 결제는 결제 완료 주문을 만들며, 고객은 Your card payment has been received.가 표시된 주문 확인 페이지를 봅니다. 검토 중인 결제는 Awaiting MercadoPago payment 주문을 만들고, 페이지에는 MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it.가 표시됩니다. 검토 중이던 결제가 나중에 거절되면 페이지에 Your MercadoPago payment was not completed. Please contact us about this order.가 표시됩니다. 보류된 주문에는 Your payment is being reviewed. We will update your order as soon as the review is complete.가 표시됩니다.

거절된 카드는 주문을 만들지 않습니다. 고객은 짧은 사유와 함께 결제 단계에 머무르며, 예를 들어 Your card has insufficient funds. Please use another card or payment method. 또는 Please check the security code of your card.가 표시됩니다. 고객은 정보를 수정하거나 다른 카드를 사용할 수 있으며, 시도할 때마다 새 카드 토큰이 만들어집니다.

MercadoPago가 응답하지 않으면 고객에게 We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically.가 표시됩니다. 다음 시도에서는 먼저 결제를 조회하므로 카드가 이중으로 청구되지 않습니다. 장바구니 결제가 진행되는 동안 다시 클릭하면 This order is already being paid. Please wait a moment and check your e-mail before trying again.가 표시됩니다. 주문이 있는 장바구니는 다시 청구되지 않으며, 고객은 해당 주문의 확인 페이지로 이동합니다.

알림 URL은 쇼핑몰이 점검 모드인 동안에도 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

모듈은 신용카드와 체크카드만 받습니다. Checkout Pro 리디렉션, MercadoPago 월렛이나 잔액, 현금(Rapipago, OXXO, boleto 등), Pix, PSE, Yape 결제, 저장된 카드나 구독, 승인과 캡처의 분리, 3-D Secure 인증, 통화 변환은 지원하지 않습니다.

주문 및 환불

주문 상태

No order: 카드가 거절되었거나 MercadoPago가 아직 응답하지 않았습니다. 장바구니만 존재합니다.

Payment accepted: MercadoPago가 결제를 승인했고, 금액과 통화가 장바구니와 일치합니다. 결제는 MercadoPago 결제 ID를 거래 ID로 하여 기록되며, 메모에는 결제 ID, 환경, 할부 개월 수가 표시됩니다.

Awaiting MercadoPago payment: 결제가 검토 중(처리 중 또는 대기 중)이며 MercadoPago 알림을 기다리고 있습니다. MercadoPago가 승인하면 주문은 Payment accepted로 바뀝니다.

MercadoPago payment on hold: 승인된 금액이나 통화가 장바구니와 다르거나, MercadoPago가 예상치 못한 상태를 반환했습니다. 메모에 이유가 설명되어 있습니다. 주문을 확인하고 처리하거나 결제를 환불하십시오.

Payment error: 검토 중이던 결제가 거절되었거나 취소되었습니다. 메모에 상태와 세부 내용이 표시됩니다.

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

이미 취소되었거나 환불된 주문에 대해 MercadoPago가 결제를 승인하면 주문 상태는 변경되지 않으며, 메모는 주문을 완료하거나 결제를 환불하라고 알려 줍니다. 이미 결제된 주문에 다른 결제가 들어오면, 메모는 MercadoPago 패널에서 추가 결제를 환불하라고 알려 줍니다.

MercadoPago 결제 블록

주문 페이지에는 MercadoPago payment 블록이 표시되며, 결제 ID, 결제 상태, 환경(테스트 결제에는 Test 배지), 할부 개월 수, MercadoPago가 청구한 금액과 주문 합계, 환불된 금액, 환불 내역, 주문의 MercadoPago notes가 포함됩니다.

환불

MercadoPago payment 블록에 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워집니다), 필요하면 사유를 입력한 후 Refund via MercadoPago를 클릭합니다. 확인 질문 Refund this amount through MercadoPago? This cannot be undone.에 응답하십시오. 전액 환불과 부분 환불을 지원합니다. 주문을 편집할 권한이 필요합니다. 환불은 MercadoPago가 청구한 금액을 넘을 수 없으므로, 금액 불일치가 있는 경우 주문 합계가 아니라 고객이 실제로 지불한 금액까지만 환불할 수 있습니다. 환불은 결제가 이루어진 환경(테스트 또는 실서비스)의 자격 증명으로 전송되므로, 해당 환경의 Access Token이 설정되어 있어야 합니다. MercadoPago가 환불을 거부하면, 블록에 사유와 함께 MercadoPago refused the refund가 표시되며 환불은 기록되지 않습니다. 승인되었거나 처리 중인 환불은 환불 ID와 함께 환불 내역과 메모에 추가됩니다. 전액 환불하면 주문이 Refunded로 설정됩니다. 부분 환불은 상태를 바꾸지 않습니다.

모듈은 크레딧 전표를 만들지 않습니다. 주문 페이지의 PrestaShop 표준 환불 버튼은 MercadoPago를 통해 돈을 돌려주지 않습니다.

MercadoPago 패널에서 이루어진 환불, 차지백, 중재는 알림을 통해 전달되며 메모에 추가됩니다. 주문 상태와 크레딧 전표는 자동으로 바뀌지 않습니다. 필요하면 직접 업데이트하십시오.

라이선스 키

모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox MercadoPago Gateway 라이선스 블록은 Modules > Module Manager > VibeFox MercadoPago Gateway > Configure 페이지의 첫 번째 블록이며 설정 위에 있습니다. License key 입력란에 키를 입력하고 Activate를 클릭하십시오. 그 후 블록에는 마스킹된 키, 상태(예: 라이선스가 유효한 마지막 날짜와 도메인), 그리고 다음 버튼이 표시됩니다: 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key. 그 아래에는 Product: presta-payment-mercadopago 줄과 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 계정에서 슬롯을 해제하십시오.

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

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

문제 해결

체크아웃에 MercadoPago가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드에 올바른 접두사를 가진 두 자격 증명이 있는지 확인하십시오. 테스트 모드에서는 TEST- 키, 실서비스에서는 APP_USR- 키입니다. 장바구니 통화가 MercadoPago 계정의 통화인지도 확인하십시오. 설정 페이지에 어떤 항목이 빠졌는지 표시됩니다. Payment > Preferences에서 모듈이 장바구니 통화, 고객 국가, 고객 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 Awaiting MercadoPago payment 상태로 남음: 알림이 도착하지 않았습니다. 모듈은 쇼핑몰에 공개 주소가 있을 때(localhost나 .local, .test 도메인이 아닐 때)만 알림 URL을 보냅니다. Notification URL의 URL을 이벤트 Payments와 함께 your application > Webhooks에 추가하십시오. Webhook secret signature가 설정되어 있다면 같은 애플리케이션의 시크릿인지 확인하십시오. MercadoPago 패널에는 각 알림에 대해 쇼핑몰이 보낸 응답이 표시됩니다.

알림 응답이 invalid signature: 서명 시크릿이 다른 애플리케이션의 것이거나, 알림에 유효한 x-signature가 없습니다. 시크릿을 다시 복사하거나 입력란을 비워 두십시오.

알림 응답이 no credentials for test 또는 no credentials for live: 결제가 이루어진 환경의 Access Token이 설정되어 있지 않습니다. 입력하십시오. MercadoPago가 알림을 다시 보냅니다.

알림 응답이 not for this store: 해당 결제는 이 쇼핑몰의 결제 시도에 속하지 않습니다. 주문은 변경되지 않습니다.

알림 응답이 order busy 또는 payment could not be read: 같은 시점에 다른 요청이 주문을 업데이트하고 있었거나, MercadoPago에 연결할 수 없었습니다. MercadoPago가 알림을 자동으로 다시 보냅니다.

자격 증명이 저장되지 않음: must start with 오류는 값의 접두사가 해당 입력란에 맞지 않는다는 뜻입니다. 테스트 입력란에는 TEST- 자격 증명, 실서비스 입력란에는 APP_USR- 자격 증명을 입력하십시오.

고객에게 This payment method is not configured correctly. Please choose another payment method or contact the store.가 표시됨: 현재 모드의 자격 증명이 없거나, 접두사가 잘못되었거나, MercadoPago가 거부했습니다. 설정 페이지에서 확인하십시오.

고객에게 MercadoPago cannot process payments in가 표시됨: 장바구니 통화가 MercadoPago 계정의 통화가 아닙니다. MercadoPago는 통화를 변환하지 않습니다.

보안 카드 양식이 로드되지 않음: 고객에게 The secure card form could not be loaded. Please reload the page or choose another payment method.가 표시됩니다. 현재 모드의 Public Key를 확인하십시오.

고객에게 Your payment was received, but the order could not be completed automatically가 표시됨: MercadoPago가 결제를 받았지만 PrestaShop이 주문을 만들지 못했습니다(예: 그 시점에 모듈이 비활성화되어 있었던 경우). 모듈 페이지의 Log 항목을 확인하십시오. 오류는 항상 기록됩니다. 고객에게는 다시 결제하지 말라는 안내가 나갑니다. 해당 장바구니에 대한 다음 결제 시도나 알림이 추가 청구 없이 주문을 만듭니다.

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

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

MercadoPago did not answer the refund request로 환불이 실패함: 다시 시도하기 전에 MercadoPago 패널에서 결제를 확인하십시오.

제거

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

MercadoPago는 해당 소유자의 상표입니다. 이 모듈은 MercadoPago와 제휴하거나 MercadoPago의 승인을 받지 않았습니다.