VibeFox Klarna for WooCommerce — 도움말

요구 사항

WordPress: 6.0 이상.

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

PHP: 8.0 이상.

HTTPS: Klarna는 실제 결제에 HTTPS를 요구합니다.

Klarna 가맹점 계정: 하나의 API 지역에 대한 가맹점 계정의 Klarna API 자격 증명(사용자 이름과 비밀번호)과 Klarna 테스트 포털의 테스트 자격 증명(설정 참조)이 필요합니다. 각 API 지역은 자체 자격 증명을 가집니다. 쇼핑몰당 하나의 가맹점 계정(하나의 API 지역)만 사용할 수 있습니다.

쇼핑몰 통화: 지역에서 Klarna가 판매하는 통화: 유럽은 EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF 또는 RON; 북미는 USD, CAD 또는 MXN; 오세아니아는 AUD 또는 NZD.

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

설치

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

2. Activate를 클릭합니다.

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

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

5. Klarna 가맹점 계정의 API region을 선택합니다.

6. Klarna 테스트 포털의 테스트 사용자 이름과 비밀번호를 입력하고, Test mode는 켜 둔 채로, Enable/Disable을 켠 다음 테스트 주문을 합니다.

7. Klarna Merchant Portal의 운영 사용자 이름과 비밀번호를 입력하고, Test mode를 끄고, 주문을 캡처할 시점을 선택합니다(기본값: 주문을 완료됨으로 표시할 때).

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Payments > Klarna Payments. 페이지 제목 옆에 TEST MODE 또는 LIVE 배지가 표시됩니다. 활성 모드의 사용자 이름 또는 비밀번호가 없으면(이 경우 Klarna는 체크아웃에서 숨겨집니다), 그리고 선택한 API 지역에서 Klarna가 쇼핑몰 통화를 판매하지 않으면 페이지에서 경고합니다. 결제 수단 목록에서는 활성 모드의 자격 증명을 입력하기 전까지 Klarna가 설정 필요 상태로 표시되며, 테스트 모드가 켜져 있는 동안에는 테스트 모드 배지가 표시됩니다.

일반

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

Title: 고객이 체크아웃에서 보는 결제 수단 이름. 기본값: Klarna.

Description: 고객이 Klarna 위젯 위에서 보는 문구. 기본값: Pay now, later or in instalments with Klarna.

API 자격 증명

Klarna API 자격 증명(사용자 이름과 비밀번호)은 Klarna Merchant Portal(portal.klarna.com)의 Settings > Klarna API credentials에서 만듭니다. 테스트 자격 증명은 테스트 포털에서 가져옵니다: 유럽은 playground.eu.portal.klarna.com, 북미와 오세아니아는 playground.us.portal.klarna.com입니다.

Test mode: Use the Klarna playground (test credentials, no real payments). 기본값: 켬. 테스트 모드가 켜져 있으면 체크아웃에 TEST MODE: Klarna playground, no real payment is made.가 표시됩니다. 주문은 생성된 환경을 유지합니다. 테스트 주문의 캡처와 환불은 항상 테스트 자격 증명을 사용합니다.

API region: Klarna 가맹점 계정의 지역. 고객은 이 지역의 국가에서, 해당 국가의 통화로 결제하는 경우에만 Klarna로 결제할 수 있습니다.

Europe: 오스트리아, 벨기에, 핀란드, 프랑스, 독일, 그리스, 아일랜드, 이탈리아, 네덜란드, 포르투갈, 슬로바키아, 스페인(EUR), 스웨덴(SEK), 노르웨이(NOK), 덴마크(DKK), 영국(GBP), 스위스(CHF), 폴란드(PLN), 체코(CZK), 헝가리(HUF), 루마니아(RON). 기본값.

North America (US, CA, MX): 미국(USD), 캐나다(CAD), 멕시코(MXN).

Oceania (AU, NZ): 호주(AUD), 뉴질랜드(NZD).

Live username (UID): 운영 API 사용자 이름, 예: PK12345_abcdef012345.

Live password: 운영 API 비밀번호(공유 비밀).

Test username (UID): 테스트 API 사용자 이름.

Test password: 테스트 API 비밀번호(공유 비밀).

주문 관리

완료된 Klarna 주문은 승인입니다. 고객은 주문이 캡처될 때만 청구됩니다. 캡처되지 않은 승인은 보통 28일 후에 만료되므로, 주문은 기한 내에 완료(배송)하거나 자동 캡처를 사용하세요.

Capture: 고객에게 청구되는 시점. 환불은 캡처된 금액에 대해서만 가능합니다. 캡처가 실패하면 주문은 메모와 함께 보류 상태가 됩니다.

When the order is Completed (recommended): 주문을 완료됨으로 표시하여 배송 시 캡처(기본값). 캡처되는 금액은 주문 총액에서 이미 캡처된 금액을 뺀 값이며, 아직 승인된 금액을 넘지 않습니다.

Immediately (auto capture): 디지털 상품이나 서비스에 대해 고객에게 즉시 청구합니다.

Manually in the Klarna portal: 플러그인은 캡처하지 않습니다. Klarna Merchant Portal에서 주문을 캡처하세요.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. 기본값: 켬.

알림

Klarna는 사기 검토 결과(“pending”으로 등록된 주문)를 이 섹션에 표시된 알림 URL로 전송합니다. URL 형식은 다음과 같습니다: https://your-site/wc-api/wc_kl_payment/. 이 URL은 모든 주문과 함께 자동으로 전송되므로 Klarna에서 설정할 것은 없습니다. 알림 내용은 신뢰하지 않습니다. 모든 알림은 Klarna Order Management API로 검증되며, Klarna 주문은 이 쇼핑몰의 주문을 참조해야 합니다. 플러그인은 Klarna가 보고한 내용에 따라 동작합니다:

ACCEPTED: Klarna가 구매를 승인했습니다. 금액과 통화를 확인한 뒤 주문이 결제 완료로 표시됩니다.

REJECTED or STOPPED: 구매가 사기 검토를 통과하지 못했습니다. 주문은 실패가 됩니다.

Klarna order CANCELLED, EXPIRED or CLOSED: 고객에게 청구되지 않았습니다. 주문이 취소됩니다.

주문을 취소하거나 환불한 뒤에 Klarna가 구매를 승인하면, 주문은 다시 열리지 않고 Klarna 승인이 해제됩니다.

고급

Debug log: Log API calls and payment events, WooCommerce > Status > Logs에서 소스 wcp_klarna_payment. 오류는 항상 기록됩니다. 로그에는 자격 증명이나 고객 데이터가 절대 포함되지 않습니다. 기본값: 끔.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. 주문 데이터(Klarna 주문 ID)는 항상 보관됩니다. 기본값: 끔.

체크아웃

고객은 결제 수단(기본값 Klarna)을 선택하고, Klarna 위젯이 체크아웃 안에 로드됩니다. 그곳에서 고객은 Klarna가 제공하는 옵션에 따라 즉시 결제, 나중 결제 또는 할부를 선택합니다. 고객이 "주문하기"를 클릭하면 Klarna가 위젯에서 구매를 승인합니다. 체크아웃 블록에서는 먼저 최종 장바구니로 Klarna 세션을 업데이트하므로, 이후 배송이나 합계가 바뀌어도 Klarna가 주문을 거절하지 않습니다. 그런 다음 플러그인은 WooCommerce 주문의 주문 품목, 합계, 주소로 서버에서 Klarna 주문을 생성합니다.

결과는 Klarna의 사기 상태에 따라 달라집니다:

ACCEPTED: 주문이 즉시 결제 완료로 표시되고, 고객은 주문 접수 페이지로 이동합니다. 금액은 승인되며 Capture 설정에 따라 캡처됩니다.

PENDING: Klarna의 알림이 도착할 때까지 주문이 보류 상태가 됩니다. 그 전에는 배송하지 마세요.

REJECTED: 주문은 실패가 되고, 고객에게는 Klarna could not approve this purchase. Please choose another payment method.가 표시됩니다.

Klarna가 주문을 수락할 수 없으면 고객에게 짧은 메시지가 표시됩니다. 예를 들어 Klarna could not accept this order. Please check your billing details or choose another payment method., Klarna did not respond. Please try again in a moment., 또는 승인이 만료된 경우 "주문하기"를 다시 클릭하라는 안내가 나옵니다. 세부 정보는 주문 메모와 로그에 추가됩니다. 고객의 청구 국가와 통화가 지역 내 Klarna 시장과 일치하지 않으면 고객에게 Klarna is not available for your billing country and currency. Please choose another payment method.가 표시됩니다.

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

이 플러그인에는 Klarna Checkout(KCO, 체크아웃 전체 대체), Klarna Express Checkout 버튼, On-site messaging, Sign in with Klarna가 없으며, 구독, 저장된 결제 수단, 주문 품목별 부분 캡처도 지원하지 않습니다. 주문이 완료된 뒤 주문을 수정해도 주문 품목은 Klarna에 다시 전송되지 않습니다.

주문 및 환불

주문 상태

Processing or Completed: Klarna가 구매를 승인했습니다. WooCommerce는 결제된 주문의 일반적인 상태를 설정합니다. 주문 메모에는 Klarna 주문 ID와 캡처 예정 시점이 표시됩니다. 트랜잭션 ID는 Klarna 주문 ID입니다. 주문이 캡처되면 메모에 캡처된 금액과 캡처 ID가 표시됩니다.

On hold: 구매가 사기 검토 대기 중이거나, Klarna가 예상치 못한 사기 상태를 반환했거나, Klarna가 보고한 금액이나 통화가 주문과 일치하지 않았거나, 캡처가 실패했습니다. 주문 메모에 어떤 이유인지 나와 있습니다.

Failed: Klarna가 사기 검토 후 구매를 거절하거나 중단했습니다. 주문을 배송하지 마세요.

Cancelled: 주문을 취소했거나, Klarna가 Klarna 주문을 취소, 만료 또는 종료된 것으로 보고했습니다. Cancellation이 켜져 있으면, 아직 캡처되지 않은 주문을 취소할 때 Klarna 주문도 취소되고 승인이 해제되므로 고객에게 청구되지 않습니다. 이미 캡처된 주문은 Klarna에서 취소되지 않습니다. 돈을 돌려주려면 환불하세요.

캡처

When the order is Completed를 사용하면 주문을 완료됨으로 표시할 때 주문 총액이 캡처됩니다. 캡처가 실패하면(예: 주문을 수정한 뒤 주문 총액이 승인된 금액을 초과한 경우), 주문은 고객에게 청구되지 않았다는 메모와 함께 보류 상태가 되며 고객은 "완료된 주문" 이메일을 받지 않습니다. 문제를 해결한 뒤 주문을 다시 완료됨으로 표시해 재시도하거나, Klarna Merchant Portal에서 캡처하세요.

환불

주문을 열고 Refund를 클릭한 뒤 금액을 입력하고 Refund via Klarna Payments를 클릭합니다. 캡처된 금액에 대해 전액 및 부분 환불이 지원되며, 캡처된 금액에서 이미 환불된 금액을 뺀 한도까지 가능합니다. 환불은 주문이 이루어진 환경과 지역으로 전송되므로, 해당 환경의 자격 증명이 설정되어 있어야 합니다. Klarna가 환불을 거절하면 WooCommerce가 오류를 표시하고 환불은 기록되지 않습니다. 환불이 성공하면 Klarna 환불 ID와 함께 주문 메모에 추가됩니다. 재시도한 환불은 절대 두 번 처리되지 않습니다.

아직 캡처되지 않은 주문은 환불할 수 없습니다. 대신 주문을 취소하여 승인을 해제하세요. Klarna Merchant Portal에서 한 환불은 WooCommerce로 동기화되지 않습니다.

라이선스 키

플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Payments > Klarna Payments 페이지 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 블록에는 상태가 표시됩니다. 예를 들어 라이선스가 활성 상태인 기한과 도메인이 나옵니다. Check now로 상태를 다시 확인하고, Change key로 다른 키를 입력하고, Remove key로 이 사이트에서 키를 제거합니다. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

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

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

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

문제 해결

체크아웃에 Klarna가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 활성 모드의 자격 증명이 입력되어 있는지 확인하세요. 테스트 모드에서는 테스트 사용자 이름과 비밀번호, 운영 모드에서는 운영 자격 증명을 입력해야 합니다. 고객의 청구 국가는 API region의 Klarna 국가여야 하며, 그 국가의 통화로 결제해야 합니다(예: 스웨덴 고객은 SEK로 결제해야 합니다).

결제는 완료되었지만 주문이 On hold 상태로 남아 있음: 구매가 Klarna의 사기 검토 중이며, 주문은 Klarna의 알림이 도착하면 업데이트됩니다. 사이트가 설정에 표시된 알림 URL로 Klarna의 요청을 받을 수 있는지, 그리고 주문이 이루어진 환경의 자격 증명이 여전히 입력되어 있는지 확인하세요. WooCommerce > Status > Logs에서 소스 wcp_klarna_payment를 확인하세요.

알림 응답이 Not configured: 주문이 이루어진 환경(테스트 또는 운영)의 자격 증명이 없어서 알림을 검증할 수 없습니다. 자격 증명을 입력하세요.

알림 응답이 Verification failed: Order Management API에서 Klarna 주문을 읽을 수 없었습니다. Klarna가 알림을 다시 보냅니다.

알림 응답이 mismatch_ref: Klarna 주문이 이 쇼핑몰 주문을 참조하지 않습니다. 주문은 변경되지 않습니다.

위젯이 로드되지 않음: 고객에게 Klarna could not be loaded. Please try again or choose another payment method. 또는 Klarna is not available for this purchase.가 표시됩니다. 활성 모드의 자격 증명과 고객의 국가 및 통화를 확인하세요.

캡처 실패, 주문 On hold: 주문 메모를 읽으세요. 주문 총액이 아직 승인된 금액을 넘었거나, Klarna 주문이 아직 수락되지 않았거나, 승인이 만료되었을 수 있습니다. 문제를 해결한 뒤 주문을 다시 완료됨으로 표시하거나, Klarna Merchant Portal에서 캡처하세요.

환불 실패: 메시지를 읽으세요. 주문이 아직 캡처되지 않았을 수 있고(대신 취소하세요), 금액이 아직 환불 가능한 금액을 넘었을 수 있으며, 주문 환경의 자격 증명이 없을 수도 있습니다.

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

제거

플러그인을 비활성화해도 모든 데이터는 유지됩니다. 제거하려면 비활성화한 뒤 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 게이트웨이 설정과 로그(소스 wcp_klarna_payment)는 Uninstall(Delete the plugin settings and logs when the plugin is deleted)이 켜져 있을 때만 제거됩니다. 그렇지 않으면 나중에 재설치할 수 있도록 남아 있습니다. 기존 주문은 결제 메모와 트랜잭션 ID를 유지합니다.

Klarna는 각 소유자의 상표입니다. 이 플러그인은 Klarna와 제휴하거나 Klarna의 승인을 받지 않았습니다.