VibeFox Datatrans for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0 ~ 9.x.

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

Datatrans 계정: Merchant ID, 서버 간 API 비밀번호, 그리고 웹훅용으로 권장되는 HMAC-SHA256 서명 키가 필요합니다. 샌드박스 자격 증명은 Datatrans 샌드박스 Web Admin(admin.sandbox.datatrans.com)에서, 운영 자격 증명은 운영 Web Admin(admin.datatrans.com)에서 가져옵니다. 샌드박스와 운영은 Merchant ID와 키가 서로 다른 별도의 Datatrans 계정입니다.

접근 가능한 쇼핑몰: Datatrans는 자체 서버에서 웹훅을 보내므로, 쇼핑몰은 인터넷에서 접근할 수 있어야 합니다.

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

설치

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

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

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

4. Datatrans 샌드박스 Web Admin의 샌드박스 자격 증명을 입력합니다(설정 항목 참조).

5. Enable/Disable을 켜고 Save를 클릭합니다. 샌드박스 모드에서 테스트 결제를 진행합니다. 모든 것이 정상 작동하면 운영 자격 증명을 입력하고 Sandbox mode를 끕니다.

설치 시 모듈은 Datatrans payment on hold 주문 상태를 만듭니다. PrestaShop은 새 결제 모듈을 모든 통화, 국가 및 고객 그룹에 기본으로 활성화합니다. 이는 Payment > Preferences에서 제한할 수 있으며, Datatrans는 그곳에서 허용된 통화에 대해서만 표시됩니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. 각 섹션에는 전체 페이지를 저장하는 Save 버튼이 있습니다. 결제 수단은 활성화되어 있지만 현재 환경에 Merchant ID 또는 API 비밀번호가 없으면, 페이지에 누락된 항목과 함께 Datatrans is hidden at checkout until these settings are filled in:이 표시됩니다. 샌드박스 모드가 켜져 있는 동안에는 페이지에 Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.가 표시됩니다.

Datatrans

Enable/Disable: Enable Datatrans Payment는 결제 수단을 켜거나 끕니다. 기본값: 꺼짐.

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

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay securely via Datatrans.

Sandbox mode: Datatrans 샌드박스를 사용합니다. 테스트 결제만 이루어지며 실제 금액은 청구되지 않습니다. 이 스위치는 Datatrans 서버와 새 결제에 사용되는 자격 증명을 함께 전환합니다. 기본값: 켜짐. 실제 결제를 받으려면 끄십시오. 켜져 있는 동안 고객에게는 결제 수단 아래에 Sandbox mode: no real payment is taken.이 표시됩니다. 환불과 캡처는 이 스위치의 상태와 관계없이 항상 결제가 이루어진 환경을 사용합니다.

샌드박스 자격 증명

Datatrans 샌드박스 Web Admin(admin.sandbox.datatrans.com)에서 복사하십시오. 서명 키는 그곳의 보안 설정에 있습니다.

Sandbox merchant ID: 샌드박스 계정의 Merchant ID입니다.

Sandbox API password: 샌드박스 계정의 서버 간 API 비밀번호입니다.

Sandbox HMAC sign key: 웹훅의 Datatrans-Signature 헤더를 확인하는 데 사용되는 16진수 키입니다. 이 키가 없으면 모든 웹훅이 Datatrans 상태 API로 다시 확인됩니다.

운영 자격 증명

Datatrans 운영 Web Admin(admin.datatrans.com)에서 복사하십시오.

Production merchant ID: 운영 계정의 Merchant ID입니다.

Production API password: 운영 계정의 서버 간 API 비밀번호입니다.

Production HMAC sign key: 운영 웹훅의 Datatrans-Signature 헤더를 확인하는 데 사용되는 16진수 키입니다. 이 키가 없으면 모든 웹훅이 Datatrans 상태 API로 다시 확인됩니다.

저장된 비밀번호와 서명 키는 다시 표시되지 않습니다. 필드는 비어 있으며 Saved — leave empty to keep it.이 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오. 서명 키는 Datatrans가 발급한 16진수 문자열이어야 합니다. 그 밖의 값은 저장되지 않습니다. 페이지에 오류가 표시되고 이전 값이 유지되며, 다른 설정은 저장됩니다.

Clear saved secrets: 비밀번호나 서명 키를 선택하고 Save를 클릭하면 삭제됩니다. 필드를 비워 두면 저장된 값이 유지됩니다.

Webhook URL

이 섹션에는 쇼핑몰의 웹훅 URL이 표시됩니다. 친숙한 URL을 사용하면 https://your-shop/module/wcp_datatrans_gateway/webhook과 같은 형태이며, /en/처럼 언어 코드가 앞에 붙을 수도 있습니다. 모듈은 모든 거래마다 이 URL을 Datatrans에 전달하므로 어디에도 입력할 필요가 없습니다. Datatrans Web Admin의 웹훅 설정에 입력하면, 그곳에서 이루어진 캡처와 취소에 대한 업데이트를 받을 수 있습니다. 설정 화면에 표시된 그대로 정확히 복사하십시오. Datatrans Web Admin에서 이루어진 환불은 주문에 반영되지 않습니다.

웹훅은 거래의 상태를 알려줍니다. 모듈은 다음 상태에 따라 동작합니다:

settled / transmitted: 결제가 캡처되었습니다. 주문은 결제 완료 상태로 생성됩니다(또는 승인된 주문이 결제 완료가 됩니다).

authorized: 결제가 승인만 되었습니다(Auto settle 꺼짐). 주문은 Datatrans payment on hold 상태로 생성됩니다.

canceled: 고객이 결제 페이지를 떠났거나(주문 없음), 승인이 해제되었습니다(주문 취소).

failed: 결제에 실패했습니다. 주문은 생성되지 않으며, 장바구니는 계속 결제할 수 있는 상태로 남습니다.

HMAC 서명 키가 있으면 각 웹훅은 결제가 이루어진 환경의 서명 키로 Datatrans-Signature 헤더를 통해 확인됩니다. 유효한 서명이 없는 웹훅은 거부됩니다. 서명 키가 없으면 모듈은 웹훅 내용을 신뢰하지 않고 모든 웹훅을 Datatrans 상태 API로 확인합니다. 웹훅이 없으면 고객이 결제 후 쇼핑몰로 돌아왔을 때에만 주문이 생성됩니다.

결제 처리

Auto settle: 결제를 즉시 캡처(정산)합니다. 꺼져 있으면 결제는 승인만 되고, 주문은 Datatrans payment on hold 상태가 됩니다. 이후 주문의 Datatrans 블록에서 Capture Datatrans payment로 캡처하거나, Cancel Datatrans authorization으로 승인을 해제할 수 있습니다. 기본값: 켜짐.

Order status after payment: 결제가 정산된 후의 주문 상태입니다.

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

Delivered (Completed): 결제된 모든 주문이 배송 완료 상태가 됩니다.

Datatrans payment on hold (On Hold): 결제된 모든 주문은 수동 검토를 기다립니다. 결제 내역은 주문에 그대로 기록됩니다.

승인만 된 결제와 금액 또는 통화 불일치는 항상 Datatrans payment on hold 상태로 갑니다.

고급

Logging: 결제 이벤트와 API 호출을 모듈 폴더의 logs/datatrans_p_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. 이 스위치가 꺼져 있어도 오류는 항상 기록됩니다. 키, 카드 데이터, 고객 데이터는 기록되지 않습니다. 기본값: 꺼짐.

Log: 로그의 크기와 최신 항목을 보여주며, 로그를 지우는 버튼이 있습니다.

Delete data on uninstall: 켜면 모듈을 제거할 때 모듈 설정과 로그가 삭제됩니다. 주문의 Datatrans 결제 기록(거래, 환불)과 주문 상태는 항상 남습니다. 기본값: 꺼짐.

체크아웃

결제 단계에서 고객은 결제 수단(기본값은 Datatrans)을 선택하고 You will be redirected to the Datatrans payment page to complete the payment securely. 안내를 봅니다. 확인하면 모듈은 장바구니 합계에 대해 장바구니 통화로 Datatrans 거래를 생성하고, 고객을 Datatrans 결제 페이지로 보냅니다. 쇼핑몰 언어가 독일어, 영어, 프랑스어, 이탈리아어 중 하나이면 해당 언어로 페이지가 열립니다. 고객은 그곳에서 Datatrans 계정에 활성화된 모든 방법으로 결제할 수 있습니다. 이 시점에는 아직 주문이 존재하지 않습니다.

결제 후 고객은 쇼핑몰로 돌아옵니다. 주문은 Datatrans가 결제를 확인한 후에만 결제 완료로 표시됩니다. 웹훅을 통해서, 또는 고객이 돌아왔을 때 서버가 Datatrans 상태 API에 요청하여 확인합니다. 복귀 주소에는 장바구니의 보안 키가 포함되며, 복귀 자체가 주문을 생성하지는 않습니다. 그 후 주문이 생성되고, 고객은 Your payment with Datatrans has been received.가 표시된 표준 주문 확인 페이지를 봅니다. 승인만 된 결제의 경우 페이지에 Your payment with Datatrans has been authorized. The amount will be charged when your order is processed.가 표시됩니다. Datatrans가 아직 결제를 확인하지 않았다면, Payment confirmation 페이지에 Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again.가 Check again 버튼과 함께 표시됩니다. 웹훅이 도착하는 즉시 주문이 생성됩니다.

고객이 Datatrans 페이지에서 취소하면 The payment was canceled. You can try again or choose another payment method.라는 메시지와 함께 체크아웃으로 돌아옵니다. 결제에 실패하면 메시지는 The payment was not completed. Please try again or choose another payment method.입니다. 장바구니는 유지됩니다. 다시 시도하면 새 Datatrans 거래가 생성되며, 이전 시도의 늦은 결제도 계속 인식됩니다.

Datatrans가 결제를 시작할 수 없으면 고객은 The payment could not be started. Please try again or choose another payment method.와 함께 체크아웃에 남습니다. 기술적인 원인은 로그에 기록됩니다.

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

모듈은 Datatrans 결제 페이지에서 일회성 결제만 받습니다. 쇼핑몰에서 저장된 카드나 별칭, 구독, Lightbox 또는 Secure Fields, 설정에서의 결제 수단 선택, 승인의 부분 캡처는 지원하지 않습니다.

주문 및 환불

주문 상태

아직 주문 없음: 고객이 Datatrans로 이동했지만 결제하지 않았거나, 결제에 실패했거나 취소되었거나, Datatrans가 아직 확인하지 않은 상태입니다. 장바구니만 존재합니다.

Payment accepted, Delivered 또는 Datatrans payment on hold: 결제가 정산되었습니다. 상태는 Order status after payment를 따릅니다. 결제는 Datatrans 거래 ID와 함께 기록되며, 메모에는 금액, 결제 수단, 환경, 확인 방식(웹훅 또는 복귀)이 표시됩니다.

승인 후 Datatrans payment on hold: Auto settle이 꺼져 있어 결제는 승인만 된 상태입니다. 주문 블록에서 캡처하거나 취소하십시오.

결제 후 Datatrans payment on hold: Datatrans가 장바구니 합계와 다른 금액이나 통화를 보고했거나(예: 결제 시작 후 장바구니가 변경됨), 주문이 취소된 뒤에 결제가 도착한 경우입니다. 메모에 이유가 설명되어 있습니다. Datatrans Web Admin에서 거래를 확인한 뒤 주문을 처리하거나 결제를 환불하십시오.

Canceled: 승인이 주문 블록이나 Datatrans Web Admin에서 해제되었습니다.

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

이미 결제되었거나 승인된 장바구니에 두 번째 결제가 도착하면 주문은 변경되지 않습니다. 메모에서 확인하고 Datatrans에서 중복 결제를 환불하라는 안내가 표시됩니다. 실패하거나 취소된 거래가 결제 완료된 주문의 상태를 낮추는 일은 없습니다.

Datatrans payment 블록

주문 페이지에는 거래 ID, Datatrans 상태, 결제 수단, 금액, 결제된 금액과 환불된 금액, 샌드박스 결제용 Sandbox 배지, 환불 내역, 주문의 Datatrans notes가 포함된 Datatrans payment 블록이 표시됩니다. 블록의 작업에는 주문 편집 권한이 필요하며, 모듈 페이지에 접근할 권한은 필요하지 않습니다.

캡처 및 취소

승인만 된 결제의 경우 블록에 Capture Datatrans payment와 Cancel Datatrans authorization이 표시됩니다. 캡처는 현재 주문 합계에 대해 결제를 정산하며, 이 금액은 승인된 금액을 초과할 수 없습니다. 그 후 주문은 Order status after payment의 상태로 이동합니다. 취소는 승인을 해제하고 주문을 Canceled로 설정합니다. 두 작업 모두 결제가 이루어진 환경으로 전송됩니다. Datatrans가 거부하면 블록에 오류가 표시되고 메모가 추가됩니다.

환불

Datatrans payment 블록에 금액을 입력합니다(아직 환불되지 않은 금액이 자동으로 채워집니다). 필요하면 사유를 입력하고 Refund via Datatrans를 클릭합니다. Refund this amount through Datatrans? This cannot be undone. 질문을 확인하십시오. 전액 및 부분 환불을 지원하며, Datatrans가 실제로 청구한 금액에서 이전 환불 금액을 뺀 범위 내에서 가능합니다. 환불은 결제가 이루어진 환경으로 전송되므로, 해당 환경의 Merchant ID와 API 비밀번호가 설정되어 있어야 합니다. 재시도한 환불은 두 번 환급되지 않습니다. Datatrans가 환불을 수락하지 않으면 블록에 오류가 표시되고 환불은 기록되지 않습니다. 성공한 환불은 Datatrans 환불 거래 ID와 함께 내역과 메모에 추가됩니다. 전액 환불하면 주문이 Refunded가 되며, 부분 환불은 상태를 바꾸지 않습니다.

승인만 된 결제에서는 아직 아무 금액도 청구되지 않았습니다. "환불"할 수 있는 것은 전체 금액뿐이며, 이는 승인을 취소합니다. 환불은 Datatrans가 결제를 정산한 후에만 가능하며, 금액이 일치하지 않는 승인은 정산될 때까지 환불할 수 없습니다.

모듈은 크레딧 슬립을 만들지 않습니다. 주문 페이지의 PrestaShop 표준 환불 버튼은 Datatrans를 통해 돈을 돌려주지 않습니다. Datatrans Web Admin에서 이루어진 환불은 PrestaShop에 기록되지 않습니다.

라이선스 키

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

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

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

문제 해결

Datatrans does not appear at checkout: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 현재 환경에 Merchant ID와 API 비밀번호가 있는지 확인하십시오. 샌드박스 모드에서는 샌드박스 필드, 그 외에는 운영 필드를 확인합니다. 설정 페이지에는 누락된 항목이 표시됩니다. Payment > Preferences에서 장바구니 통화, 고객의 국가, 고객 그룹에 대해 모듈이 허용되어 있는지 확인하십시오.

The payment went through, but no order was created: Datatrans가 웹훅 URL에 접근하지 못했고 고객도 쇼핑몰로 돌아오지 않았습니다. 쇼핑몰이 인터넷에서 접근 가능한지, 방화벽이 웹훅 URL로의 요청을 차단하지 않는지 확인하십시오. 설정의 서명 키가 결제 환경의 것인지 확인하십시오. 모듈 페이지의 Log 필드를 확인하십시오.

Webhook answers Invalid signature: 설정의 HMAC 서명 키가 Datatrans Web Admin의 키와 일치하지 않거나 다른 환경의 키입니다. 키를 다시 복사하십시오.

Webhook answers Not configured or Verification failed: 웹훅을 Datatrans 상태 API로 확인해야 했지만, 해당 환경의 자격 증명이 없거나 Datatrans가 응답하지 않았습니다. Datatrans는 웹훅을 다시 시도합니다.

Webhook answers Busy, retry: 같은 순간에 다른 요청이 주문을 확인하고 있었거나, 주문을 생성할 수 없었습니다(예: 모듈이 비활성화됨). Datatrans는 웹훅을 다시 시도합니다. 로그에 이유가 표시됩니다.

The webhook URL shows Method not allowed in the browser: 정상입니다. 이 URL은 Datatrans의 요청만 허용합니다.

The HMAC sign key is not saved: 키는 16진수 문자열이어야 합니다. Datatrans Web Admin에서 다시 복사하십시오.

The customer sees Datatrans payments are not configured yet: 현재 환경의 Merchant ID 또는 API 비밀번호가 없습니다.

The customer sees The payment could not be started: Log 필드를 확인하십시오. 잘못된 Merchant ID나 API 비밀번호, 또는 잘못된 환경의 자격 증명이 흔한 원인입니다.

Order is Datatrans payment on hold after payment: 주문 블록의 Datatrans notes를 읽고(주문 상태 항목 참조), 주문을 처리하거나 결제를 환불하십시오.

Capture is refused: 주문 합계가 승인된 금액보다 큽니다. Datatrans는 승인된 금액을 초과하여 정산할 수 없습니다.

Refund or capture fails with a message about missing credentials: 결제는 다른 환경에서 이루어졌으며, 그 환경의 Merchant ID 또는 API 비밀번호가 설정되어 있지 않습니다. 이를 입력한 후 다시 시도하십시오.

제거

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

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