KR
EUR
뒤로

VibeFox Peach Payments for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: OpenSSL 확장이 포함된 8.0 이상(웹훅 복호화에 사용됩니다). 이것이 없으면 모듈이 설치되지 않습니다.

통화: 장바구니 통화는 ZAR, KES 또는 MUR이어야 합니다. 다른 통화의 장바구니에서는 결제 수단이 숨겨집니다. 쇼핑몰의 기본 통화가 이 중 하나가 아니면 설정 페이지에 경고가 표시됩니다.

Peach Payments 계정: Peach Payments 계정의 Card API 자격 증명이 필요합니다: Entity ID와 Access Token. 테스트 자격 증명은 Peach Payments 샌드박스 대시보드에서, 운영 자격 증명은 Peach Payments 대시보드에서 발급받으며, 두 가지는 서로 다릅니다. 웹훅을 사용하려면 Peach Payments가 쇼핑몰에 대해 Card 웹훅을 활성화할 때 보내 주는 웹훅 복호화 키도 필요합니다(구성 참조). 웹훅을 받으려면 쇼핑몰이 인터넷에서 접근 가능해야 합니다.

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

설치

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

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

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

4. Peach Payments 샌드박스 대시보드에서 테스트 Entity ID와 Access Token을 입력하고, 설정 페이지에 표시된 웹훅 URL에 대해 Card 웹훅을 활성화해 달라고 Peach Payments에 요청합니다(구성 참조).

5. Enable/Disable을 켜고 Save를 클릭합니다. Test mode는 켜 둔 상태에서 Peach Payments 샌드박스 테스트 카드로 결제합니다. 그다음 Test mode를 끄고, 운영 자격 증명과 운영 웹훅 키를 입력한 뒤 Save를 클릭합니다.

설치 시 모듈은 두 가지 주문 상태를 생성합니다: Awaiting Peach Payments payment와 Peach Payments payment on hold. PrestaShop은 설치 시점에 활성화된 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. 나중에 추가한 국가는 Payment > Preferences에서 이 모듈에 대해 활성화해야 하며, 같은 곳에서 국가를 제한할 수도 있습니다.

구성

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 필드 위에는 페이지가 다음과 같은 알림을 표시합니다: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; 현재 모드의 Entity ID 또는 Access Token이 없으면 오류(그 전까지 결제 단계에서 결제 수단이 표시되지 않음); 현재 모드의 웹훅 복호화 키가 없으면 경고(이 경우 고객이 쇼핑몰로 돌아와야만 결제가 확인됨); 쇼핑몰의 기본 통화가 지원되지 않으면 오류. 저장할 때 자격 증명의 공백은 제거되며, 64자리 16진수 값이 아닌 웹훅 키는 경고와 함께 표시됩니다.

Peach Payments

Enable/Disable: Enable Peach Payments는 결제 수단을 켜거나 끕니다. 기본값: 끔.

Title: 결제 단계에서 고객에게 표시되는 결제 수단 이름입니다. 주문에도 결제 수단 이름으로 저장됩니다. 기본값: Credit / Debit Card (Peach Payments). 필수 항목입니다.

Description: 결제 단계에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

API credentials

Card API의 Access Token과 Entity ID는 Peach Payments 대시보드에 표시됩니다(테스트 자격 증명은 샌드박스 대시보드에 있음). 이 섹션에는 두 대시보드와 Peach Payments 개발자 문서로 연결되는 링크가 있습니다.

Test mode: 테스트 자격 증명으로 새 결제를 Peach Payments 샌드박스에 보냅니다. 실제 금액은 청구되지 않습니다. 끄면 운영 자격 증명으로 실제 결제를 받습니다. 한 모드에서 시작된 결제는 전환한 뒤에도 항상 그 모드에서 확인합니다. 기본값: 켬.

Test Entity ID: 샌드박스 계정의 Entity ID(3-D Secure 채널)입니다.

Test Access Token: 샌드박스 계정의 bearer 액세스 토큰입니다.

Test Webhook Decryption Key: 샌드박스 Card 웹훅을 복호화하는 데 사용하는 64자리 16진수 키입니다.

Live Entity ID: 운영 계정의 Entity ID(3-D Secure 채널)입니다.

Live Access Token: 운영 계정의 bearer 액세스 토큰입니다.

Live Webhook Decryption Key: 운영 계정의 Card 웹훅을 복호화하는 데 사용하는 64자리 16진수 키입니다.

저장된 액세스 토큰과 웹훅 키는 다시 표시되지 않습니다. 필드는 비어 있고 Saved — leave empty to keep it.를 표시합니다. 값을 바꾸려는 경우에만 새 값을 입력하세요.

Clear saved secrets: 액세스 토큰 또는 웹훅 키에 체크한 뒤 Save를 클릭하면 삭제됩니다. 필드가 비어 있으면 저장된 값이 유지됩니다.

Webhook

웹훅은 고객이 쇼핑몰로 돌아오기 전에 브라우저를 닫아도 결제를 확인합니다. Webhook URL 필드에는 쇼핑몰의 웹훅 URL이 표시됩니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_peach_pay/webhook처럼 보이며, /en/과 같은 언어 코드가 포함될 수도 있습니다. 설정에 표시된 URL을 정확히 그대로 복사하세요. 이 URL로 계정의 Card 웹훅을 활성화해 달라고 Peach Payments(support@peachpayments.com)에 요청한 뒤, 받은 복호화 키를 같은 모드의 Webhook Decryption Key 필드에 입력합니다.

Peach Payments는 모든 웹훅을 암호화합니다(AES-256-GCM). 테스트 키나 운영 키로 복호화할 수 없는 웹훅은 거부되므로, 주문을 변경할 수 있는 것은 Peach Payments뿐입니다. 한 모드의 키로 복호화된 웹훅은 그 모드에서 시작된 결제에만 적용됩니다. 모듈은 다음 결제 알림을 사용합니다:

Debit payment (DB): 장바구니의 카드 결제 결과입니다. 주문이 결제 완료, 보류 또는 확인 대기 상태로 생성되거나, 시도가 거부됨으로 표시됩니다(주문 참조).
Refund (RF), reversal (RV), chargeback (CB): Peach Payments 대시보드에서 수행한 환불이나 취소, 또는 보고된 차지백입니다. 주문 메모에 추가되며, 주문 상태는 바뀌지 않습니다.

웹훅을 활성화할 때 보내는 테스트 알림 등 그 밖의 알림은 ignored로 응답합니다. 웹훅 키가 없으면 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 주문이 생성됩니다.

Payment form

Card brands: Peach Payments 양식에 표시되는 브랜드입니다: Visa, Mastercard, American Express, Diners Club. Entity ID에서 활성화된 브랜드만 선택하세요. 기본값: Visa와 Mastercard. 브랜드를 하나도 선택하지 않으면 저장 시 경고가 표시되고, 양식에는 Visa와 Mastercard가 표시됩니다.

Advanced

Logging: API 요청과 결제 결과를 모듈 폴더의 logs/peach_p_debug.log.php에 기록합니다. 이 파일은 웹에서 읽을 수 없습니다. 오류와 경고는 항상 기록됩니다. 로그에는 카드 데이터, 키, 고객 데이터가 포함되지 않습니다. 기본값: 끔.

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

Delete data on uninstall: 켜 두면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문에 속한 Peach Payments 데이터(결제 시도, 결제 ID)와 주문 상태는 주문에 속하므로 유지됩니다. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Credit / Debit Card (Peach Payments))을 선택하고 주문을 확정합니다. 테스트 모드에서는 결제 수단에 Test mode: no real payment will be made.가 표시됩니다. 모듈은 장바구니 통화로 장바구니 금액에 대한 Peach Payments 체크아웃을 준비하고, 쇼핑몰의 Peach Payments payment 페이지를 Peach Payments 카드 양식과 선택된 카드 브랜드와 함께 표시합니다. Peach Payments가 지원하는 경우 고객의 언어로 표시됩니다. 테스트 모드에서는 이 페이지에 Test mode: use a Peach Payments test card, no real payment will be made.가 표시됩니다. 카드 정보는 Peach Payments 양식에 입력되며, 양식 스크립트는 Subresource Integrity 해시와 함께 로드됩니다. Choose another payment method 링크를 누르면 체크아웃으로 돌아갑니다. 이 시점에는 아직 주문이 없습니다. 페이지를 새로고침하면 장바구니가 바뀌지 않은 경우 같은 체크아웃을 최대 25분 동안 다시 사용합니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Peach Payments가 확인한 뒤에만 결제 완료로 표시됩니다. 쇼핑몰은 체크아웃을 생성한 모드에서 Peach Payments API를 통해 이 장바구니의 체크아웃 결과를 조회하고, 결제가 이 장바구니에 속하는지 확인합니다. 웹훅도 독립적으로 같은 작업을 수행하므로, 먼저 도착한 쪽이 주문을 생성하고 다른 쪽은 아무것도 바꾸지 않습니다. 그다음 고객은 표준 주문 확인 페이지를 봅니다.

결제가 완료되지 않으면 고객은 메시지와 함께 체크아웃으로 돌아가 다시 시도할 수 있습니다: Payment failed: 뒤에 Peach Payments가 알려 준 사유가 이어지고, Please try again or use another card. 또는 The payment was not completed. Please try again.가 표시됩니다. 장바구니는 유지됩니다. 결과를 아직 확인할 수 없는 경우(예: Peach Payments가 응답하지 않았거나 웹훅이 같은 장바구니를 바로 그 순간 처리 중인 경우)에는 We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. 메시지가 표시됩니다. 결제 모드에 웹훅 키가 설정되어 있지 않으면 고객에게는 대신 쇼핑몰로 문의하라는 안내가 표시됩니다.

결제 양식을 준비할 수 없으면 고객은 짧은 메시지와 함께 체크아웃에 머무릅니다: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method.(자격 증명이 없거나 잘못된 경우), 일부 청구 정보가 결제 서비스 제공업체에서 승인되지 않았다는 메시지, 또는 The payment form could not be loaded. Please try again in a moment. 기술적인 사유는 로그에 기록됩니다.

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

모듈은 체크아웃 단계 자체에 카드 양식이 없으며, 저장된 카드, 구독, 사전 승인 및 캡처, EFT, BNPL, QR 등 카드 이외의 결제 수단을 지원하지 않습니다.

주문

주문 상태

No order yet: 고객이 결제하지 않았거나, 결제가 거부되거나 완료되지 않았거나, Peach Payments가 아직 확인하지 않은 상태입니다. 장바구니만 존재하며 고객은 다시 결제할 수 있습니다.

Payment accepted: 결제가 확인되었고 금액과 통화가 장바구니와 일치하는 상태입니다. 결제는 Peach Payments 결제 ID를 거래 ID로 기록하며, 메모에는 Peach Payments 결과 코드, 설명, 결제 ID가 표시됩니다. Peach Payments가 결제를 수동 검토 대상으로 표시한 경우, 메모에서 배송 전에 Peach Payments 대시보드에서 확인하라고 안내합니다.

Awaiting Peach Payments payment: Peach Payments가 확인을 기다리는 결제를 보고한 상태입니다. 이후 웹훅이 주문을 Payment accepted로 옮기거나 실패로 표시합니다.

Peach Payments payment on hold: 결제된 금액 또는 통화가 장바구니와 다르거나(메모: amount/currency mismatch — manual review required), 주문이 취소된 뒤에 결제가 도착한 상태입니다. 메모에 확인해야 할 내용이 설명되어 있습니다. Peach Payments 대시보드에서 결제를 확인한 뒤 주문을 처리하거나 결제를 환불하세요.

Payment error: 대기 중인 주문이 기다리던 결제를 Peach Payments가 거부한 상태입니다. 거부된 시도는 결제 완료, 보류 또는 취소된 주문을 절대 변경하지 않습니다.

이미 결제 완료된 주문에 대한 두 번째 결제가 성공해도 주문은 변경되지 않습니다. 메모는 중복 결제라는 점을 알리고, Peach Payments 대시보드에서 환불하라고 요청합니다. 환불된 주문에 도착한 결제는 주문에 메모로만 기록됩니다.

Peach Payments 결제 블록

주문 페이지에는 Peach Payments payment 블록이 표시되며, 결제 ID, 체크아웃 ID, 가맹점 거래 ID, Peach Payments로 보낸 금액, 결과와 결과 코드, 테스트 결제에 대한 Test mode 배지, 주문의 Peach Payments notes가 포함됩니다.

환불

PrestaShop 주문 페이지에서는 환불할 수 없습니다. Peach Payments 대시보드에서 결제를 환불하고, 필요하면 PrestaShop에도 기록하세요(부분 환불 또는 크레딧 슬립). 웹훅을 설정하면 Peach Payments에서 수행한 환불, 취소, 차지백이 금액과 ID와 함께 주문 메모에 추가됩니다. 주문 상태는 바뀌지 않습니다.

라이선스 키

이 모듈은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox Peach Payments Pay Gateway 라이선스 블록은 Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하세요. 그러면 블록에 키가 마스킹되어 표시되고, 상태(예: 라이선스 유효 기간 종료일과 도메인)가 나타납니다. 또한 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 있습니다. 그 아래에는 Product: presta-payment-peach 줄과 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 계정에서 슬롯을 해제하세요.

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

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

문제 해결

체크아웃에 Peach Payments가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 모드의 Entity ID와 Access Token이 입력되어 있는지(테스트 모드는 Test Entity ID와 Test Access Token, 운영 모드는 Live Entity ID와 Live Access Token), 장바구니 통화가 ZAR, KES 또는 MUR인지 확인하세요. 설정 상단의 알림에 문제가 표시됩니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객의 그룹에 대해 모듈이 허용되어 있는지도 확인하세요.

결제는 완료되었지만 주문이 생성되지 않음: 고객이 쇼핑몰로 돌아오지 않았고 웹훅도 도착하지 않은 경우입니다. Peach Payments가 설정에 표시된 URL에 대해 Card 웹훅을 활성화했는지, 결제가 이루어진 모드의 Webhook Decryption Key가 입력되어 있는지, 방화벽이나 비밀번호 보호가 URL을 막고 있지 않은지 확인하세요. Logging을 켠 뒤 Log 필드에서 거부된 웹훅을 확인하세요.

웹훅이 Decryption failed로 응답함: 웹훅을 테스트 키로도, 운영 키로도 복호화할 수 없었습니다. 키가 잘못되었거나 다른 계정이나 모드의 키입니다. 이 웹훅 URL에 대해 Peach Payments가 보낸 키를 입력하세요.

웹훅이 Webhook key not configured로 응답함: 테스트 및 운영 웹훅 키가 모두 설정되어 있지 않거나 유효하지 않습니다. 64자리 키를 입력하세요. Peach Payments가 나중에 웹훅을 다시 보냅니다.

웹훅이 Busy, retry later로 응답함: 같은 순간 고객의 복귀로 장바구니가 처리되고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). 아무것도 변경되지 않았으며, Peach Payments가 웹훅을 다시 보냅니다. 사유는 로그에 표시됩니다.

웹훅이 Missing or malformed data로 응답함: 요청에 암호화된 본문이나 X-Initialization-Vector / X-Authentication-Tag 헤더가 없었습니다(예: 프록시가 요청을 변경한 경우). 아무것도 변경되지 않았습니다.

웹훅이 ignored로 응답함: 알림은 진짜지만 이 쇼핑몰의 체크아웃에 속하지 않거나(같은 Entity ID를 쓰는 다른 쇼핑몰, 삭제된 장바구니), 결제와 다른 모드에서 왔습니다. 아무것도 변경되지 않았습니다.

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

고객이 The payment form is not available right now를 봄: 현재 모드의 Access Token 또는 Entity ID가 잘못되었습니다. 자격 증명과 모드를 확인하고, 로그에서 Peach Payments 코드를 확인하세요.

결제 후 주문이 Peach Payments payment on hold 상태임: Peach Payments payment 블록의 메모를 읽어 보세요. 결제된 금액 또는 통화가 장바구니와 달랐거나, 주문이 취소된 뒤에 결제가 도착한 경우입니다. Peach Payments 대시보드에서 결제를 확인한 뒤 주문을 처리하거나 결제를 환불하세요.

저장할 때 웹훅 키는 64자리 16진수 키여야 한다는 메시지가 표시됨: 입력한 값이 Peach Payments에서 발급한 키가 아닙니다. 수정하기 전까지 웹훅은 복호화할 수 없습니다.

제거

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

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