VibeFox DPO for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

PHP: SimpleXML 확장이 포함된 8.0 이상. 이것이 없으면 모듈이 설치되지 않습니다.

DPO Pay 계정: DPO 가맹점 계정의 Company Token과 Service Type ID가 필요합니다. DPO는 계정을 개설할 때 이를 발급합니다. DPO 계정 담당자에게 문의하거나 dpogroup.com에서 받으실 수 있습니다. DPO는 자체 token 및 service type이 있는 테스트 계정도 제공할 수 있습니다. 별도의 테스트 서버는 없습니다. DPO는 테스트 계정과 운영 계정에 같은 API 주소를 사용하며, 계정은 token으로 구분됩니다.

통화: 쇼핑몰 통화는 DPO 계정에서 지원되어야 합니다. DPO는 소수점 이하 최대 2자리까지만 허용하므로, 소수점 이하 3자리인 장바구니 총액(예: KWD 12.345)은 결제할 수 없습니다.

서버 cron: 15분마다 모듈의 재확인 URL을 호출하는 cron 작업(Configuration 참조).

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

설치

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

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

3. VibeFox 라이선스 키를 Configure 페이지 상단 라이선스 블록의 License key에 붙여 넣고 Activate를 클릭합니다(라이선스 키 항목 참조).

4. 테스트 및/또는 운영용 Company Token과 Service Type을 입력합니다(Configuration 참조).

5. Configure 페이지에 표시된 push 알림 URL을 DPO 지원팀에 보내고, 계정에 설정해 달라고 요청합니다. cron URL을 서버의 cron 작업에 추가합니다.

6. Enable/Disable을 켜고 Save를 클릭합니다. 테스트 모드에서 테스트 주문을 한 후, 실제 결제를 받으려면 Test mode를 끕니다.

설치 시 모듈은 DPO payment on hold 주문 상태를 생성합니다. PrestaShop은 모든 통화, 국가, 고객 그룹에 대해 새 결제 모듈을 제공합니다. Payment > Preferences에서 이를 제한할 수 있습니다.

Configuration

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox DPO Pay Gateway > Configure. 각 섹션에는 페이지 전체를 저장하는 자체 Save 버튼이 있습니다. 모듈은 활성화되어 있지만 선택한 모드의 Company Token 또는 Service Type이 비어 있으면, 페이지는 체크아웃에서 결제 방법이 숨겨진다고 경고하며, 저장할 때도 같은 경고가 표시됩니다. 테스트 모드가 켜져 있는 동안 페이지에는 Test mode is on: payments are created with the test account credentials.가 표시됩니다.

DPO Pay

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

Title: 고객이 체크아웃에서 보는 결제 방법 이름입니다. 주문에 저장되는 결제 방법 이름이기도 합니다. 기본값: DPO Pay. 필수.

Description: 체크아웃에서 결제 방법 아래에 표시되는 텍스트입니다. 기본값: Pay securely by card or mobile money on the DPO Pay payment page.

API 자격 증명

DPO는 가맹점 계정용 Company Token과 Service Type ID를 발급하며, 테스트 계정용으로는 별도의 값을 발급합니다. DPO 계정 담당자에게 문의하거나 dpogroup.com에서 받으실 수 있습니다.

Test mode: 켜면 새 결제는 테스트용 Company Token과 Service Type으로 생성됩니다. 기본값: 켜짐. 운영 자격 증명으로 실제 결제를 받으려면 끄십시오. 기존 결제의 상태 확인과 취소는 항상 결제가 생성된 계정을 사용합니다.

Test Company Token: DPO 테스트 계정의 Company Token입니다.

Test Service Type: DPO 테스트 계정의 숫자형 Service Type ID입니다.

Live Company Token: DPO 운영 가맹점 계정의 Company Token입니다.

Live Service Type: DPO 운영 가맹점 계정의 숫자형 Service Type ID입니다.

저장된 Company Token은 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.이 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오. Service Type은 반드시 숫자여야 합니다. 그 밖의 값은 저장되지 않으며, 페이지에 경고가 표시되고 이전 값이 유지됩니다.

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

결제 알림

Push notification URL: push 알림은 고객이 결제 후 브라우저를 닫더라도 결제가 이루어졌음을 쇼핑몰에 즉시 알려 줍니다. 이 URL은 대시보드에서 설정하지 않습니다. DPO 지원팀에 요청하여 계정에 이 URL을 설정하십시오. 친숙한 URL을 사용하는 경우 https://your-shop/module/wcp_dpo_pay/notify와 같은 형태이며, 언어 코드가 포함될 수도 있습니다. 페이지에 표시된 그대로 정확히 복사하십시오. 인터넷에서 접근 가능해야 하며, 앞단에 유지 보수 모드, 방화벽 또는 기본 인증이 없어야 합니다.

DPO의 push 알림에는 서명이 없으므로 그 내용은 신뢰하지 않습니다. 모듈은 이를 거래 토큰으로 결제를 찾는 데만 사용하고, 결과는 DPO에 직접 확인합니다. 쇼핑몰이 생성하지 않은 토큰은 DPO에 요청하지 않고 거부됩니다.

Scheduled status re-check (cron): 서버 cron 작업에서 이 URL을 15분마다 호출하십시오(예: curl 사용). 확인되지 않은 결제는 리디렉션 15분 후 및 결제 시간 제한 이후에 DPO에서 다시 확인됩니다. URL에는 비밀 토큰이 포함되어 있으므로 외부에 공개하지 마십시오. push URL과 cron이 없으면, 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 주문이 생성됩니다.

주문

Successful payment status: 검증된 결제 성공 후의 주문 상태입니다.

금액 또는 통화 불일치, 승인만 된 결제, 과다 지불 또는 부족 지불된 거래는 항상 DPO payment on hold로 이동합니다.

고급

Logging: API 호출과 알림을 모듈 폴더의 logs/dpo_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 오류는 항상 기록됩니다. 토큰은 마스킹되며, 고객 데이터는 기록되지 않습니다. 기본값: 끔.

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

Delete data: 켜면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문용으로 저장된 DPO 데이터와 DPO payment on hold 주문 상태는 항상 유지됩니다. 이 옵션 없이 제거하면 데이터는 전혀 삭제되지 않습니다. 기본값: 끔.

체크아웃

결제 단계에서 고객은 결제 방법(기본값 DPO Pay)을 선택하고 You will be redirected to the secure DPO Pay payment page. 안내를 봅니다. 확인하면 모듈은 장바구니 통화로 장바구니 총액에 대한 DPO 거래를 생성합니다. 설명에는 장바구니 번호와 쇼핑몰 이름이 사용되며, 고객은 DPO 결제 페이지로 이동합니다. 고객의 이름, 이메일, 전화번호, 청구 주소는 페이지를 미리 채우기 위해 전달됩니다. 고객은 그곳에서 DPO 계정에서 활성화된 모든 방법으로 결제합니다. 결제 링크는 5시간 동안 유효합니다. 이 시점에는 아직 주문이 없습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 DPO가 확인한 후에만 결제 완료로 표시됩니다. 모듈은 고객이 돌아올 때, push 알림이 도착할 때, 예약된 재확인 때 DPO에 거래 결과를 요청합니다. 그 후 주문이 생성되며 고객은 표준 주문 확인 페이지를 보게 됩니다.

결제가 확인되지 않으면 고객은 다음 메시지 중 하나와 함께 체크아웃으로 돌아갑니다. 장바구니는 유지됩니다.

고객이 DPO 페이지의 버튼을 눌러 쇼핑몰로 돌아가면 먼저 거래를 확인합니다. 결제되었으면 주문이 생성됩니다. 그렇지 않으면 DPO에서 취소되고 고객은 장바구니와 함께 체크아웃으로 돌아갑니다.

고객이 같은 장바구니에 대해 다시 결제하면 이전 DPO 거래를 먼저 확인합니다. 결제되었으면 추가 청구 없이 주문이 생성됩니다. 아직 처리 중이면 고객은 Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again.를 봅니다. 그렇지 않으면 이전 거래는 DPO에서 취소되고 새 거래가 생성됩니다.

DPO가 결제를 시작할 수 없으면 고객은 DPO 오류 코드에 따라 선택된 짧은 메시지와 함께 체크아웃에 머뭅니다. 예를 들어 DPO Pay does not support the currency of this order. Please choose another payment method. 또는 The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. 다른 오류는 DPO Pay is temporarily unavailable. Please try again or choose another payment method.를 표시합니다. 기술적인 원인은 로그에 기록됩니다.

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

이 모듈은 DPO 페이지에서의 일회성 결제만 받습니다. 쇼핑몰에서의 환불, 저장된 카드, 구독 또는 정기 결제, 사이트의 카드 입력란, 승인만 된 결제의 캡처는 지원하지 않습니다.

주문

주문 상태

No order yet: 고객은 DPO로 이동했지만 결제하지 않았거나, 결제가 거절 또는 취소되었거나, DPO가 아직 결제를 확인하지 않았습니다. 장바구니만 존재합니다.

Payment accepted, Delivered or DPO payment on hold: 결제가 검증되었습니다. 상태는 Successful payment status를 따릅니다. 결제는 DPO 거래 토큰을 거래 ID로 하여 기록됩니다. 주문 페이지의 비공개 메모에 금액, 통화, 승인 코드, 토큰의 앞부분이 표시됩니다.

DPO payment on hold after payment: DPO가 결제를 확인했지만 금액이나 통화가 장바구니와 다르거나, 결제가 승인만 되고 캡처되지 않았거나, 거래가 과다 지불 또는 부족 지불되었거나, 고객이 결제를 취소했거나 주문이 이미 취소되었습니다. 비공개 메모에 그 이유가 설명되어 있습니다. DPO 포털에서 거래를 확인하십시오. 승인만 된 결제는 DPO 포털에서 캡처하거나 취소한 다음 주문 상태를 업데이트하십시오.

Cancelled: 결제되지 않은 모듈 주문(예: 승인만 된 결제 때문에 보류 중인 주문)을 취소하면, 그 주문의 미완료 DPO 거래도 DPO에서 취소됩니다.

나중에 도착한 거절 결과가 주문을 변경하지 않으며, 이전 거래의 결과가 현재 시도를 실패시키지도 않습니다. 이미 결제 완료된 주문에 대해 DPO가 두 번째 성공 결제를 확인하면, 주문은 변경되지 않고 중복 결제 가능성에 대한 메모가 추가되므로 DPO 포털에서 환불할 수 있습니다. 결제 완료 또는 환불된 주문은 다시 열리지 않습니다.

환불

이 버전에서는 쇼핑몰에서의 환불을 사용할 수 없습니다. DPO 가맹점 포털에서 결제를 환불한 다음, PrestaShop에서 주문 상태를 변경하십시오.

라이선스 키

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

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

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

문제 해결

DPO Pay does not appear at checkout: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 선택한 모드의 Company Token과 Service Type이 설정되어 있는지 확인하십시오. 테스트 모드에서는 테스트 필드를, 그 외에는 운영 필드를 확인합니다. 설정 페이지는 누락된 항목이 있으면 경고를 표시합니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

The payment went through, but no order was created: 아마도 DPO 계정에 push 알림 URL이 설정되지 않았고, 고객이 쇼핑몰로 돌아오지 않았을 가능성이 큽니다. DPO 지원팀에 설정 페이지에 표시된 URL을 설정해 달라고 요청하고, cron이 15분마다 재확인 URL을 호출하는지 확인하십시오. Logging을 켜고 모듈 페이지의 Log 필드를 확인하십시오.

Push notification answers Unknown transaction: 거래 토큰이 이 쇼핑몰의 DPO Pay 결제에 속하지 않습니다. 예를 들어 같은 DPO 계정의 다른 쇼핑몰에서 알림이 왔을 때 발생합니다.

Push notification answers Verification failed: 결제를 확인하기 위해 DPO에 연결할 수 없었거나, 같은 시점에 다른 요청이 장바구니를 처리하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). DPO는 알림을 다시 보내며, 예약된 재확인도 주문을 확인합니다. 원인은 로그에 있습니다.

The push URL shows Method not allowed in the browser: 정상입니다. 이 URL은 DPO의 요청만 받습니다.

The cron URL answers Forbidden: URL의 토큰이 잘못되었습니다. Configure 페이지에서 URL을 다시 복사하십시오. 정상적인 호출은 OK checked=와 확인된 결제 수를 응답합니다.

The Service Type is not saved: DPO에서 받은 숫자형 Service Type ID여야 합니다.

The customer sees DPO Pay is temporarily unavailable: DPO가 거래 생성을 거부했습니다. 예를 들어 잘못된 Company Token 또는 Service Type이거나 다른 모드의 token인 경우입니다. DPO 결과 코드는 로그에 있습니다.

The customer sees that DPO accepts at most 2 decimal places: 장바구니 총액이 소수점 이하 3자리입니다. DPO는 이러한 금액을 청구할 수 없습니다.

The customer sees This order has already been paid with DPO Pay: DPO가 같은 장바구니에 대한 두 번째 결제를 거부했습니다. DPO 포털에서 결제를, PrestaShop에서 주문을 확인하십시오.

Order is DPO payment on hold after payment: 주문 페이지의 비공개 메모를 읽고(주문 상태 참조), DPO 포털에서 거래를 검토하십시오.

개발자는 actionWcpDpoPayCustomerData 훅으로 DPO에 전송되는 고객 데이터를, actionWcpDpoPayPaymentTimeLimit 훅으로 결제 시간 제한을 변경할 수 있습니다.

제거

Modules > Module Manager로 이동하여 VibeFox DPO Pay Gateway 옆의 메뉴를 열고 Uninstall을 선택합니다. 이 모듈의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. Delete data가 켜져 있으면 모듈 설정과 로그가 삭제됩니다. 꺼져 있으면 나중에 다시 설치할 수 있도록 모든 설정이 유지됩니다. 주문용으로 저장된 DPO 데이터와 DPO payment on hold 주문 상태는 항상 유지되므로, 재설치 후에도 이전 결제에 대한 지연 알림이 계속 작동합니다. 기존 주문은 결제 메모와 거래 ID를 그대로 유지합니다.

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