VibeFox Transbank for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상입니다.

WooCommerce: 8.0 이상이며, 설치되어 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상입니다.

쇼핑몰 통화: 칠레 페소(CLP). Webpay Plus는 정수 페소만 청구하므로, WooCommerce > Settings > General에서 Number of decimals를 0으로 설정하십시오. 다른 통화를 사용하는 쇼핑몰에서는 결제 수단이 표시되지 않습니다.

Transbank 계정: 실제 결제를 받으려면 표준 Webpay Plus 커머스(즉시 캡처)와 운영용 Commerce Code, API Key Secret이 필요합니다. Commerce Code는 가맹 신청이 승인되면 Transbank에서 제공하고, API Key Secret은 통합 검증 절차를 마친 뒤 제공합니다(Transbank 개발자 문서 참조). 테스트에는 자격 증명이 필요하지 않습니다. Webpay Plus Mall, Oneclick, 지연 캡처 커머스 코드는 지원하지 않습니다.

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

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하고, 플러그인 ZIP 파일을 선택한 뒤 Install Now를 클릭합니다. FTP로 wcp_transbank_gateway 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. WooCommerce > Settings > General에서 쇼핑몰 통화를 칠레 페소로, Number of decimals를 0으로 설정합니다.

4. 설정을 엽니다: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

5. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

6. Enable / Disable을 켜고, Integration (test) mode를 켠 상태에서 Transbank 개발자 문서의 테스트 카드로 결제를 시험합니다.

7. 실제 운영으로 전환하려면 Production Commerce Code와 Production API Key Secret을 입력하고, Integration (test) mode의 체크를 해제한 뒤 저장합니다.

Transbank에서 반환 URL이나 웹훅을 설정할 필요는 없습니다. 플러그인이 모든 거래마다 반환 URL을 전달합니다.

구성

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Transbank Webpay Plus. 입력란 위에서 페이지는 다음 경우 경고합니다: 운영 모드가 선택되었는데 Production Commerce Code 또는 API Key가 없거나 잘못된 경우(이때 Webpay는 체크아웃에서 숨겨짐), 쇼핑몰 통화가 CLP가 아닌 경우(결제 수단이 숨겨짐), CLP 가격에 소수점이 있는 경우(합계가 정수 페소로 반올림됨). 통합 모드가 켜져 있으면 페이지에 Integration (test) environment가 표시되며 실제 금액은 청구되지 않습니다. 저장 후에는 경고가 새 설정을 따릅니다. 결제 수단 목록에서는, 유효한 자격 증명 없이 운영 모드가 선택된 경우 게이트웨이가 설정 필요로 표시됩니다.

일반

Enable / Disable: Enable Transbank Webpay Plus payments는 결제 수단을 켜거나 끕니다. 기본값: 끔.

Title: 고객이 체크아웃에서 보는 결제 수단 이름입니다. 기본값: Webpay Plus.

Description: 체크아웃에서 결제 수단 아래에 표시되는 텍스트입니다. 기본값: Pay with credit, debit or prepaid card via Webpay.

환경 및 자격 증명

이 섹션의 텍스트는 Transbank 개발자 문서에 연결되며, Transbank가 운영용 자격 증명을 언제 제공하는지 설명합니다.

Integration (test) mode: Use the Transbank integration environment. 결제는 Transbank 통합 환경으로 전송되며, 공개 테스트 커머스 코드(597055555532)가 자동으로 입력됩니다. 아래의 운영용 자격 증명은 사용되지 않으며 실제 금액은 청구되지 않습니다. 기본값: 켬. 운영으로 전환하려면 체크를 해제하십시오.

Production Commerce Code: 운영용 커머스 코드(Tbk-Api-Key-Id): 12자리이며 5970으로 시작합니다. 8자리인 경우 그대로 입력하십시오. 저장할 때 플러그인이 5970 접두사를 추가합니다. 공백과 기타 문자는 제거됩니다. Transbank의 공개 테스트 커머스 코드는 운영 환경에서 허용되지 않습니다.

Production API Key Secret: 운영용 커머스의 Tbk-Api-Key-Secret입니다. 비밀로 보관하십시오. 저장할 때 공백이 제거됩니다.

고급

Debug log: Log API requests and returns (errors are always logged). 자세한 내용은 WooCommerce > Status > Logs의 소스 wcp_transbank_gateway에 기록됩니다. 이 필드에는 view logs 링크가 있습니다. 이 옵션이 꺼져 있어도 오류와 경고는 기록됩니다. 카드 데이터, API 키, 전체 토큰은 기록되지 않습니다. 기본값: 끔.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). 기본값: 끔.

테스트와 운영

Integration (test) mode는 새 결제가 갈 곳을 결정합니다. 각 결제는 자신의 환경을 기억합니다. 결제의 확정과 환불은 나중에 모드를 바꾸더라도 항상 결제가 생성된 환경(통합 또는 운영)과 생성 시 사용한 자격 증명으로 처리됩니다.

체크아웃

고객은 결제 수단(기본값 Webpay Plus)을 선택하고 주문합니다. 통합 모드에서는 체크아웃에 TEST MODE: Integration environment가 표시됩니다. 실제 청구는 없습니다. 플러그인은 주문 합계를 정수 페소로 하여 Transbank 거래를 생성하고(소수점이 있는 합계는 가장 가까운 페소로 반올림됨), 고객을 짧은 페이지 Redirecting to Webpay. Please wait...로 보내며, 이 페이지가 Webpay 양식으로 전달합니다. JavaScript가 없으면 고객이 Proceed to Webpay를 클릭합니다. Webpay에서 고객은 신용카드, 체크카드 또는 선불카드로 결제합니다.

고객이 돌아오면 플러그인은 서버 간 통신으로 Transbank와 거래를 확정(commit)합니다. 주문은 Transbank가 확정한 뒤에만 결제 완료로 표시됩니다. 응답이 승인되어야 하며, 금액, buy order, 세션이 이번 시도에 대해 쇼핑몰이 보낸 내용과 일치해야 합니다. 이후 고객은 주문 접수 페이지를 봅니다. 확정 요청이 실패하면(예: 시간 초과), 플러그인은 Transbank에 거래 상태를 요청합니다. 상태를 여전히 알 수 없으면 주문은 변경되지 않고, 고객에게는 We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.가 표시됩니다.

고객이 Webpay에서 취소하거나, Webpay 양식이 만료되거나 오류를 보고하면 아무것도 청구되지 않습니다. 주문은 결제 대기 상태로 남고, 고객은 메시지와 함께 Pay for order 페이지로 돌아갑니다. 예: You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. 카드가 거부되면 Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method.가 표시됩니다. 고객은 같은 페이지에서 다시 결제할 수 있습니다. 새로운 시도마다 새로운 Webpay 거래가 생성됩니다.

각 Webpay 시도는 최대 한 번만 확정됩니다. 반환 페이지 새로고침, 브라우저 뒤로 가기 버튼, 또는 같은 순간의 두 번째 반환은 결코 두 번 확정하지 않으며 주문을 변경하지도 않습니다. 주문이 더 이상 결제를 필요로 하지 않는 경우(다른 시도로 이미 결제됨, 취소됨 또는 환불됨), 늦은 반환은 확정되지 않으므로 Transbank가 청구하지 않습니다. 고객에게는 This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.가 표시됩니다.

Webpay가 결제를 시작할 수 없으면 고객에게 짧은 메시지가 표시됩니다. 예: Could not connect to Webpay. Please try again in a moment. 또는 Webpay payments are not available at the moment. Please choose another payment method. 기술적 원인은 로그에 기록됩니다.

이 결제 수단은 클래식 체크아웃, 체크아웃 블록, Pay for order 페이지에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

Transbank에는 결제 웹훅이 없습니다. 결과는 고객이 Webpay에서 돌아올 때 처리됩니다. 고객이 Webpay에서 브라우저를 닫고 돌아오지 않으면 거래는 확정되지 않고 주문은 대기 상태로 남습니다. Transbank에 따르면 확정되지 않은 거래는 정산되지 않습니다. 플러그인은 Webpay Plus Mall, Oneclick 저장 카드, 정기결제, 지연 캡처, 통화 변환을 지원하지 않습니다.

주문 및 환불

주문 상태

Pending payment: 고객이 Webpay로 이동했지만 아직 결제하지 않았거나, 취소했거나, 양식이 만료되었거나, 결제를 아직 확정할 수 없는 상태입니다. 종료된 각 시도는 buy order와 함께 메모에 기록됩니다.

Processing or Completed: Transbank가 결제를 승인했습니다. 상태는 WooCommerce가 설정합니다. 가상의 다운로드 가능 상품만 있는 주문은 Completed(완료됨), 그 외에는 Processing(처리 중)입니다. 주문 메모에는 승인 코드, 카드 끝 4자리, buy order, 금액, 결제 유형, 할부 개월 수가 표시됩니다. 거래 ID는 Webpay 토큰입니다.

On hold: Transbank가 주문과 일치하지 않는 결제(금액, buy order 또는 세션 ID)를 승인했습니다. 예를 들어 결제가 시작된 뒤 주문이 수정된 경우입니다. 메모에는 차이점이 나열됩니다. Transbank 포털을 확인한 뒤 주문을 환불하거나 완료하십시오.

Failed: 결제가 거부되었습니다. 아무것도 청구되지 않았습니다. 메모에는 응답 코드와 상태가 표시됩니다.

Webpay가 이미 결제 완료, 취소 또는 환불된 주문에 대한 결제를 반환하면, 해당 결제는 확정되지 않으며, 고객이 청구를 보고하면 Transbank 포털을 확인하라는 메모가 남습니다. 기존 주문은 이후 시도의 영향을 받지 않습니다.

환불

환불 버튼은 Webpay로 결제된 주문에만 제공됩니다. 주문을 열고 Refund를 클릭한 다음 금액을 입력하고 Refund via Webpay Plus를 클릭하십시오(버튼은 결제 수단 제목을 사용합니다). 전액 및 부분 환불은 정수 페소 단위로 지원됩니다. 소수점이 있는 부분 금액은 Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals.라는 메시지와 함께 거부됩니다. 소수점이 있는 주문 합계의 마지막 잔액은 청구와 같은 방식으로 반올림됩니다. 환불은 결제가 이루어진 환경으로 전송되므로, 운영 환경에서는 운영용 자격 증명이 설정되어 있어야 합니다.

Transbank는 취소(REVERSED) 또는 무효화(NULLIFIED)로 응답합니다. 환불이 성공하면 금액, 유형, 승인 코드, Transbank에 남은 잔액과 함께 주문 메모에 추가됩니다. Transbank가 환불을 승인하지 않으면 WooCommerce가 오류를 표시하며 환불은 기록되지 않습니다. Transbank 포털에서 이루어진 환불은 WooCommerce로 가져오지 않습니다.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Transbank Webpay Plus 페이지 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 블록에는 상태(예: 라이선스가 유효한 날짜와 도메인)가 표시됩니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하며, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 작동합니다. 사이트에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하십시오.

활성 키가 없으면 Webpay Plus는 체크아웃에서 고객에게 표시되지 않습니다. 그래도 결제가 시작되면 고객은 This payment method is not available. Please choose another one.를 봅니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only)라고 표시된 결제 수단이 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문은 영향을 받지 않습니다. 이미 시작된 결제는 계속 확정되며 환불도 작동합니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

Webpay Plus가 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable / Disable이 켜져 있는지, 쇼핑몰 통화가 CLP인지(Pay for order 페이지에서는 주문 통화), 통합 모드가 꺼져 있을 때 유효한 Production Commerce Code(12자리, 5970으로 시작)와 Production API Key Secret이 저장되어 있는지 확인하십시오. 설정 페이지는 누락된 조건마다 경고를 표시합니다.

결제는 완료되었지만 주문이 Pending payment 상태로 남아 있음: Transbank에는 웹훅이 없으므로 고객이 Webpay에서 돌아와야 주문이 확정됩니다. 고객이 Webpay에서 브라우저를 닫았다면 거래는 확정되지 않았으며, Transbank에 따르면 정산되지 않습니다. 주문 메모와 로그, 그리고 Transbank 포털의 거래를 확인하십시오.

고객이 We could not confirm your Webpay payment with Transbank 메시지를 봄: 확정 요청이 실패했고 상태를 확인할 수 없었습니다. 주문은 변경되지 않았으며 메모가 추가되었습니다. 고객은 잠시 후 다시 시도할 수 있습니다. Transbank 포털에서 거래가 승인된 것으로 표시되면, 발송 전에 그곳에서 확정하십시오.

고객이 주문할 때 오류를 봄: Debug log를 켜고 WooCommerce > Status > Logs, 소스 wcp_transbank_gateway를 확인하십시오. Webpay payments are not available at the moment 메시지는 보통 잘못된 운영용 자격 증명을 뜻합니다. Could not connect to Webpay는 Transbank에 연결할 수 없다는 뜻입니다. CLP가 아닌 통화의 주문은 Webpay로 결제할 수 없습니다.

합계와 환불이 몇 페소 차이 남: CLP 가격에는 소수점이 있습니다. Webpay는 정수 페소만 청구하므로 합계가 반올림됩니다. Number of decimals를 0으로 설정하십시오.

The production Commerce Code / API Key are missing 메시지로 환불 실패: 결제는 운영 환경에서 이루어졌지만 운영용 자격 증명이 저장되지 않았습니다. 자격 증명을 입력하고 다시 시도하십시오.

Transbank refused the refund 또는 Transbank did not approve the refund 메시지로 환불 실패: Transbank가 승인하지 않았습니다. 메시지에 사유 또는 반환된 유형과 응답 코드가 표시됩니다. 환불된 금액은 없습니다. Transbank 포털에서 거래를 확인하십시오.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르십시오. 예를 들어 키가 다른 도메인에서 이미 사용 중이면 vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하십시오. 사이트 주소가 바뀌었다면 Check now를 클릭하여 새 도메인에 키를 활성화하십시오. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

제거

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 제거하려면 Plugins 페이지에서 비활성화한 뒤 삭제하십시오. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. 게이트웨이 설정, 기타 옵션, 플러그인의 임시 데이터, 로그(회전된 로그 파일 포함)와 데이터베이스 로그 항목은 Delete data on uninstall이 켜져 있었을 때만 삭제됩니다. 그렇지 않으면 나중에 재설치할 수 있도록 유지됩니다. 주문에 저장된 Transbank 데이터는 회계와 환불에 필요하므로 항상 보관됩니다. 기존 주문은 결제 메모와 거래 ID를 유지합니다.

Transbank 및 Webpay는 각 소유자의 상표입니다. 이 플러그인은 Transbank와 제휴하지 않으며 Transbank의 승인을 받지 않았습니다.