VibeFox PagSeguro for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0~9.x.

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

통화: 브라질 레알(BRL). 결제 수단은 BRL 장바구니에서만 표시됩니다.

HTTPS: PagBank가 결제 알림을 보낼 수 있도록 쇼핑몰은 인터넷에서 HTTPS로 접속 가능해야 합니다.

PagBank 계정: 실제 결제용 운영 토큰과 테스트용 샌드박스 토큰. 운영: PagBank 계정에 로그인하고 Venda online > Integrações를 연 다음 Gerar token을 클릭합니다. PagBank가 토큰을 이메일로 보냅니다. 샌드박스: PagBank 개발자 포털에서 샌드박스 계정을 만들고 그 토큰을 복사합니다. 샌드박스 토큰과 운영 토큰은 각자의 환경에서만 작동합니다.

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

설치

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

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

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

4. 샌드박스 토큰을 입력하고, 실제 결제를 받으려면 운영 토큰을 입력합니다.

5. Enable / Disable을 켜고 Save를 클릭합니다. Sandbox Mode를 켠 상태에서 테스트 결제를 하고, 실제 결제를 받으려면 끕니다.

설치 시 모듈은 두 개의 주문 상태, Awaiting PagBank payment와 PagBank payment on hold를 만듭니다. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 제한할 수 있으며, BRL 통화는 모듈에 대해 허용된 상태로 유지되어야 합니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 Save 버튼이 있습니다. 필드 위에는 현재 모드가 표시됩니다: SANDBOX MODE(결제는 PagBank 샌드박스에서 생성되며 실제 청구는 없음) 또는 LIVE(결제는 운영 토큰으로 생성됨). 현재 모드의 토큰이 없으면 경고를 표시합니다(이 경우 결제 수단은 결제 과정에서 숨겨짐). 쇼핑몰 기본 통화가 BRL이 아니면 경고를 표시합니다(이 경우 다른 통화의 장바구니에는 결제 수단이 제공되지 않음).

PagSeguro / PagBank

Enable / Disable: Enable PagSeguro/PagBank payments로 결제 수단을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 결제 과정에서 보는 결제 수단 이름입니다. 주문에도 결제 수단 이름으로 저장됩니다. 기본값: PagSeguro / PagBank. 필수.

Description: 결제 과정에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

PagBank 계정

이 섹션은 토큰을 얻는 방법을 설명하고, 사용자의 PagBank 계정 및 토큰에 관한 PagBank 페이지로 연결되는 링크를 제공합니다.

Sandbox Mode: Enable sandbox/test mode (no real charges). 새 결제는 샌드박스 토큰을 사용해 PagBank 샌드박스로 전송되며, 고객은 결제 수단 아래에서 SANDBOX MODE — Using test environment. No real charges.를 봅니다. 주문의 상태 확인과 환불은 항상 그 결제가 생성된 환경과 토큰을 사용합니다. 기본값: 켬.

Sandbox token: PagBank 샌드박스 토큰입니다. 샌드박스 모드가 켜져 있는 동안 사용됩니다.

Production token: PagBank 운영 토큰(Bearer)입니다. 샌드박스 모드가 꺼져 있을 때 사용됩니다. 비밀로 유지하십시오.

저장된 토큰은 다시 표시되지 않습니다. 필드는 비어 있고 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하십시오.

Clear saved tokens: 토큰을 선택하고 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

결제 알림

Notification URL: 모든 결제는 PagBank에 상태 변경을 어디로 알릴지 알려 주므로, PagBank에서 설정할 것은 없습니다. 이 섹션에 URL이 표시됩니다. 친숙한 URL을 사용하면 다음과 같습니다: https://your-shop/module/wcp_pagseguro_gateway/webhook. 이 주소는 인터넷에서 HTTPS로 접속 가능해야 합니다.

x-authenticity-token 헤더가 있는 알림은 결제가 생성된 환경의 토큰으로 검사하며, 잘못된 서명은 거부됩니다. 알림 본문 자체는 절대 신뢰하지 않습니다. 모듈은 주문을 생성하거나 변경하기 전에 항상 PagBank API에서 결제와 PagBank 주문(상태, 금액, 통화)을 읽습니다. 알림이 없으면 고객이 결제 후 쇼핑몰로 돌아왔을 때 주문이 생성됩니다.

고급

Debug log: Log API requests and notifications는 모듈 폴더의 logs/wc_psg_debug.log.php에 상세 내용을 기록합니다. 이 파일은 웹에서 열 수 없습니다. 로그에는 토큰이나 고객 데이터가 포함되지 않습니다. 오류는 항상 기록됩니다. 기본값: 끔.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 로그가 비워집니다.

Delete Data on Uninstall: 켜 두면 모듈을 제거할 때 게이트웨이 설정과 로그가 삭제됩니다. 주문, PagBank 참조 정보(환불에 필요), 주문 상태는 항상 유지됩니다. 기본값: 끔.

결제 과정

결제 단계에서 고객은 결제 수단(기본값 PagSeguro / PagBank)을 선택하고 확인합니다. 모듈은 장바구니 합계를 BRL로 하나의 항목으로 하여 PagBank 결제를 만듭니다. 항목 이름은 Order #에 장바구니 번호와 쇼핑몰 이름을 더한 형태입니다. 그런 다음 고객을 PagBank 결제 페이지로 보냅니다. 쇼핑몰에 정보가 있으면 고객의 이름과 이메일, 주소의 Identification number 또는 VAT number 필드에 있는 CPF 또는 CNPJ, 그리고 브라질 전화번호가 자동으로 채워집니다. 고객은 PagBank 페이지에서 이를 보완하거나 수정할 수 있습니다. 고객은 PagBank 계정에 활성화된 결제 수단(예: 신용카드, PIX, boleto)으로 결제합니다. 결제 페이지는 120분 후에 만료됩니다. 이 시점에는 아직 주문이 존재하지 않습니다.

결제 후 고객은 쇼핑몰로 돌아갑니다. 주문은 PagBank가 결제를 확인한 후에만 완료로 표시됩니다. 모듈은 알림이 도착하거나 고객이 돌아올 때 PagBank API에서 결제를 읽으며, 단순히 돌아온 것만으로는 주문이 결제 완료로 표시되지 않습니다. 이후 주문이 생성되고, 고객은 Your payment with PagBank has been received.가 표시된 주문 확인 페이지를 봅니다. 생성된 boleto 또는 PIX, 또는 검토 중인 결제의 경우 페이지에 Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment.가 표시됩니다. 이러한 결제가 나중에 거절되거나 취소되면 페이지에 Your PagBank payment was not completed. Please contact us about this order.가 표시됩니다. 고객이 돌아왔을 때 PagBank가 아직 결제를 확인하지 않았다면 Payment confirmation 페이지가 표시되며, 여기에는 We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again.와 Check again 버튼이 나타납니다.

결제가 완료되지 않은 경우 고객은 결제 과정으로 돌아가며 The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. 또는 The payment was declined by PagBank. Please try again with another card or payment method.를 봅니다. 장바구니는 유지됩니다. boleto 또는 PIX 결제를 기다리던 주문이 취소되었다면 고객은 The PagBank payment was cancelled, so the order was cancelled.를 봅니다.

고객이 다시 결제하면, 금액과 환경이 같고 10분 이내에 만료되지 않는 경우 열린 PagBank 결제가 재사용됩니다. 그렇지 않으면 이전 결제가 비활성화되어 더 이상 결제할 수 없습니다. 그 이전 페이지에서 이루어진 결제는 여전히 장바구니에 유효하며, 새 결제 대신 주문이 생성됩니다.

PagBank가 결제를 시작할 수 없으면 고객은 결제 과정에 머무르며 짧은 메시지를 봅니다. 예: PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. 또는 Could not connect to PagBank. Please try again in a moment. 기술적인 이유는 로그에 기록됩니다.

쇼핑몰이 유지 관리 모드여도 알림은 작동하며, 쇼핑몰의 국가 제한에 의해 차단되지 않습니다.

이 모듈에는 사이트 내 카드 입력 양식, 카드 저장, 구독이나 정기 결제, 분할 결제나 마켓플레이스 기능이 없습니다. 결제 수단과 할부는 PagBank 계정에서 설정한 것을 사용합니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 PagBank로 이동했지만 결제하지 않았거나, 카드가 거절되었거나, 결제 페이지가 만료되었습니다. 장바구니만 존재하며 고객은 다시 결제할 수 있습니다.

Payment accepted: 예상 금액과 통화로 결제가 확인되었습니다. 결제는 PagBank 청구 ID(charge ID)를 거래 ID로 하여 기록되며, 메모에 금액, 결제 수단, 청구 ID가 표시됩니다.

Awaiting PagBank payment: boleto 또는 PIX가 생성되어 결제를 기다리고 있거나 결제가 검토 중입니다. PagBank가 결제 완료를 보고하면 주문은 Payment accepted로 이동합니다.

PagBank payment on hold: PagBank가 장바구니와 다른 금액이나 통화를 보고했거나(예: 결제 페이지 생성 후 장바구니가 변경됨), 주문이 취소된 후에 결제가 도착했거나(재고를 확인한 후 주문을 완료하거나 PagBank에서 결제를 환불하십시오), 카드 결제가 승인되었으나 캡처되지 않았습니다(PagBank에서 캡처하십시오). 메모에 그 이유가 설명됩니다. 실제로 받은 금액은 주문에 기록됩니다.

Payment error: 대기 중이거나 검토 중이던 결제가 거절되었습니다.

Canceled: 대기 중이던 결제(예: 만료된 boleto 또는 PIX)가 취소되었습니다.

Refunded: 모듈을 통하거나 PagBank 대시보드에서 결제가 전액 환불되었습니다.

각 PagBank 상태는 한 번만 적용되므로, 반복된 알림이나 복귀로 메모나 상태 변경이 추가되지 않습니다. 이미 결제 완료된 주문에 두 번째 결제가 도착하면 주문은 변경되지 않으며, 메모는 중복 결제를 PagBank에서 환불하라고 안내합니다.

PagBank payment 블록

주문 페이지에는 PagBank 결제 과정, PagBank 주문 및 청구 ID, 결제 수단, 상태, 결제된 금액과 환불된 금액, 샌드박스 결제용 Sandbox 배지, 환불 내역, 주문의 PagBank notes가 포함된 PagBank payment 블록이 표시됩니다.

환불

PagBank payment 블록에서 금액을 입력하고(아직 환불되지 않은 금액이 자동으로 채워짐), 선택적으로 사유를 입력한 뒤 Refund via PagBank를 클릭합니다. Refund this amount through PagBank? This cannot be undone. 질문을 확인하십시오. 전액 및 부분 환불을 지원합니다. 주문을 편집할 수 있는 권한이 필요하며, 모듈 페이지에 대한 접근 권한은 필요하지 않습니다. 한도는 PagBank가 청구한 금액이므로, 금액 불일치가 있는 경우 주문 합계가 아니라 고객이 실제로 지불한 금액까지 환불할 수 있습니다. 환불은 결제가 이루어진 환경과 토큰으로 전송됩니다. 환불은 PagBank가 확인한 경우에만 기록됩니다. 그렇지 않으면 블록에 오류가 표시됩니다(예: PagBank refund failed: ... 또는 PagBank did not confirm the refund). 이 경우 아무것도 기록되지 않습니다. boleto 결제의 환불과 PIX의 부분 환불은 PagBank 규칙을 따릅니다. 성공한 환불은 청구 ID와 함께 환불 내역과 메모에 추가됩니다. 전액 환불은 주문을 Refunded로 설정하며, 부분 환불은 상태를 변경하지 않습니다. 환불은 PagBank가 결제를 완료로 보고한 후에 가능합니다.

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

PagBank 대시보드에서 이루어진 환불은 다음 알림에서 확인됩니다. 전액 환불은 주문을 Refunded로 설정하고, 부분 환불은 환불된 금액을 적은 메모를 추가합니다. 환불을 주문에 수동으로 추가할 수도 있습니다.

라이선스 키

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

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

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

문제 해결

결제 과정에 PagBank가 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 현재 모드의 토큰이 설정되어 있는지(샌드박스 모드에서는 Sandbox token, 라이브 모드에서는 Production token), 그리고 장바구니 통화가 BRL인지 확인하십시오. 토큰이 없거나 쇼핑몰 통화가 BRL이 아니면 설정 페이지에 경고가 표시됩니다. Payment > Preferences에서 모듈이 BRL, 고객의 국가, 고객의 그룹에 대해 허용되어 있는지 확인하십시오.

결제는 완료되었지만 주문이 생성되지 않음: PagBank가 아직 결제를 보고하지 않았고 고객이 쇼핑몰로 돌아오지 않았습니다. 알림이 도착하면 주문이 바로 생성됩니다. 쇼핑몰이 Notification URL에서 인터넷을 통해 HTTPS로 접속 가능한지 확인하고, Debug log를 켜서 알림을 확인하십시오.

알림 응답이 Invalid signature: x-authenticity-token이 결제가 이루어진 환경의 토큰과 일치하지 않거나, 그 토큰이 저장되어 있지 않습니다. 설정에 올바른 토큰이 있는지 확인하십시오.

알림 응답이 Verification failed, retry later: PagBank API에 연결할 수 없거나, 결제 환경의 토큰이 없거나, 장바구니가 같은 시점에 다른 요청에 의해 처리되고 있었습니다. PagBank가 알림을 다시 시도합니다.

알림 응답이 Order not found: 이 알림은 이 쇼핑몰에서 이 모듈로 결제되지 않은 장바구니에 대한 것입니다. 아무것도 변경되지 않습니다.

고객이 보는 메시지 PagBank payments are temporarily unavailable. Please choose another payment method.: 현재 모드의 토큰이 없거나 PagBank가 토큰을 거부했습니다.

고객이 보는 메시지 PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: 장바구니가 다른 통화로 되어 있습니다.

주문이 PagBank payment on hold 상태임: PagBank payment 블록의 메모를 읽고(주문 상태 참조), PagBank에서 금액을 비교한 뒤 주문을 처리하거나 결제를 환불하십시오.

토큰 관련 메시지와 함께 환불이 실패함: 결제는 샌드박스나 운영 환경에서 이루어졌으며, 해당 환경의 토큰이 없거나 거부되었습니다. 올바른 토큰을 입력하고 다시 시도하십시오.

제거

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

PagSeguro와 PagBank는 각 소유자의 상표입니다. 이 모듈은 PagSeguro 또는 PagBank와 제휴하거나 그들의 승인을 받은 것이 아닙니다.