Miva용 Checkout

가입 후 24시간 이내에 전담 온보딩 담당자가 맞춤형 통합 프로세스를 시작하기 위해 연락합니다.

Important: 아래 나열된 단계는 참고용이며 온보딩 담당자가 안내합니다.

1. Miva App Store에서 모듈을 다운로드하거나, Zonos에 직접 zonos.mvc 파일을 요청하세요.
2. Miva 관리자에서 Domain Settings -> Modules -> Add Module로 이동하여 zonos.mvc 파일을 업로드한 다음 Add를 클릭합니다.

3. Settings -> Modules로 이동하여 Zonos를 찾은 다음 Install을 클릭합니다. Installed로 표시되는지 확인하세요.

Miva에서 Users -> API Tokens로 이동하여 Add API Token을 클릭합니다. 다음과 같이 구성하세요.

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- 서명 키를 생성하려면 Generate를 클릭하세요
• Timestamp: Require Timestamp Within 30 seconds

다음 화면에서 Customer Service & Sales를 활성화하여 토큰이 주문을 생성하고 수정할 수 있도록 합니다. Save를 클릭합니다.

Miva -> Utility Settings -> Zonos로 이동하여 Miva의 Checkout 모듈로 이동한 다음, 다음 필드를 입력합니다.

1. Store ID: Dashboard -> Settings -> Account -> Integrations에서 Zonos account number를 복사합니다.
2. Zonos API Key: 비밀 API 키입니다(절대 공유하지 마세요).
3. Zonos Public Key: 공개 키입니다.
4. Store Currency: 스토어의 기본 통화입니다(예: USD).
5. Environment: 프로덕션의 경우 Live, 테스트의 경우 Test를 선택합니다.
6. Checkout Button Selector: 결제 버튼에 대한 CSS 선택자입니다(예: a[href*="checkout.html"]).
7. Hidden Selectors: 국제 고객과 관련 없을 수 있는 국내 결제 옵션 및 기타 세부 정보를 숨기는 데 사용됩니다.
8. Import Orders: 완료된 Zonos 주문을 Miva 관리자로 자동 가져오려면 선택하세요. 다음 단계에서 웹훅이 등록되어 있어야 합니다.

계속하기 전에 오른쪽 상단의 Update를 클릭하여 저장하세요.

10.x 모듈에서는 주문이 웹훅을 통해 가져와집니다. 이전 모듈 버전에서는 대신 주문 성공 URL/엔드포인트를 사용했습니다.

설정을 저장한 후 Register Webhooks를 클릭합니다. 이렇게 하면 스토어가 Zonos에 연결되어 완료된 주문이 자동으로 가져와지고, 취소가 동기화되며, 배송 업데이트가 Miva로 다시 전송됩니다.

주문 가져오기, 취소 동기화, 배송 업데이트가 작동하려면 먼저 웹훅이 등록되어 있어야 합니다. Import Orders 확인란은 웹훅 등록을 필요로 합니다.

아래로 스크롤하여 나머지 필드를 완료하세요.

1. Miva API Token: API 토큰 생성 단계에서 만든 API 토큰의 Access Token입니다.
2. Miva API Signature: 동일한 API 토큰 항목의 Signing Key입니다.
3. Image Type: Zonos checkout에 표시할 제품 이미지 크기를 선택합니다(대부분의 스토어에는 Main이 적합합니다).
4. Additional Field Mappings: Miva 사용자 지정 필드를 Zonos 속성/메타데이터(색상, 소재, 사이즈 등)에 선택적으로 매핑합니다. Miva 제품 목록에 제품별 HS code를 설정한 경우 HS code 매핑을 권장합니다. Catalog에 입력한 제품별 HS code 또는 default HS code를 사용할 수 있으므로 관세 및 세금 견적 생성에 필수는 아닙니다. 그러나 권장됩니다. 올바르게 분류된 제품으로 Landed cost 계산 정확도가 크게 향상됩니다. Miva에서 필드를 매핑하려면 HS code용 사용자 지정 필드를 만든 다음 Utility Settings -> Zonos에서 매핑합니다.

모든 설정을 저장하려면 Update를 클릭합니다.

계정과 모듈 설정을 완료했으므로 다음을 수행하여 테스트할 준비가 되었습니다.

• 배송 견적 테스트
• 사이트에서 테스트 주문하기
• 시스템을 통한 주문 흐름 테스트
• 웹사이트 테스트

이 테스트 실행 방법을 알아보세요. 테스트 중에는 모듈의 Environment 필드를 Test로 설정해야 합니다.

테스트를 완료하면 이제 라이브로 전환할 준비가 되었습니다! Environment를 Live로 설정하고, Zonos 자격 증명이 올바른지 확인한 다음, 라이브 스토어에 웹훅이 등록되어 있는지 확인하세요.

1. dashboard.zonos.com -> Hello -> Hello Settings로 이동합니다.
2. Currency behavior를 켭니다.
3. 제품 가격 요소를 대상으로 하는 CSS 선택자를 입력합니다(예: .price).

이 설정을 활성화하면 Zonos Hello가 쇼핑객의 현지 통화로 가격을 자동으로 변환하여 표시합니다.

Miva 카탈로그에 설정된 배송 치수, 원산지 국가, HS code는 자동으로 Zonos에 매핑되며, 입력되어 있는 경우 landed cost/배송 견적에 사용됩니다. 구성을 위한 추가 매핑이 필요하지 않습니다.

모든 옵션이 단일 SKU를 공유하는 구성 가능한 제품을 판매하는 스토어의 경우, Miva의 표준 Product Shipping Rules는 제품당 하나의 치수 세트만 저장하므로 고객이 선택한 옵션과 관계없이 모든 구성이 동일한 크기로 처리됩니다.

Miva와 Zonos는 배리언트 수준의 치수를 지원하지만, 이를 위해서는 각 배리언트를 개별적으로 설정해야 합니다. 개별 배리언트로 매핑되지 않는 수백, 수천 개의 구성을 가진 스토어에는 실용적이지 않을 수 있습니다.

이 기능은 스토어에 이미 마련된 사용자 지정 로직(예: 제품 설명에서 치수를 파싱하는 방식)을 사용하여 결제 시 장바구니에서 구성별 치수를 직접 읽어 이 문제를 해결합니다.

요구 사항

• 스토어는 항목이 장바구니에 추가될 때 장바구니 항목에 사용자 지정 치수 열을 이미 채우고 있어야 합니다(Zonos 모듈의 범위를 벗어난 Miva 측 작업입니다).
• 사용 중인 정확한 열 이름을 알고 있어야 합니다.

구성

Zonos 모듈 관리자의 해당하는 세 필드에 해당 열 이름을 입력하세요. 비워두면 표준 Product Shipping Rules로 대체됩니다 -- 이 기능은 완전히 선택 사항이며 사용하지 않는 스토어에는 영향을 주지 않습니다.

Zonos Dashboard에서 배송 라벨이 생성되거나 추적 번호가 입력되면, 추적 번호와 배송 상태가 Miva 관리자의 해당 주문으로 자동 전송됩니다. 이를 위해서는 웹훅이 등록되어 있어야 합니다(위의 웹훅 등록 단계 참조).

추적 정보는 Miva에서 직접 입력할 수도 있습니다. 모든 Zonos 주문에서 Enter Tracking Number 입력 대화 상자를 사용하세요 -- 추적 번호와 배송 상태가 자동으로 Zonos Dashboard에 다시 동기화됩니다.

디버그 로그는 Miva 관리자 내 Zonos 모듈 설정에서 확인할 수 있습니다. 모듈이 처리하는 모든 주문 이벤트의 전체 라이프사이클 -- 가져오기, 추적 동기화, 취소, Zonos로의 취소 요청 전송 -- 을 성공과 실패를 모두 포함하여 인라인으로 기록합니다.

각 항목에는 Zonos 주문 ID, Miva 주문 ID, 그리고 관련이 있는 경우 Miva 또는 Zonos API의 오류 응답과 같은 고객 수준의 세부 정보가 포함됩니다. 이는 문제를 진단하는 데 가장 완전한 정보 소스입니다.

로그는 최근 500줄만 보관합니다. 이전 항목은 보관되지 않으므로 문제가 발생하면 즉시 확인하세요 -- 이전 이벤트가 이미 덮어써졌을 수 있습니다.

공개 오류 로그(로그인 불필요)

Miva 관리자 로그인 없이 직접 URL을 통해 접근할 수 있는 두 번째 공개용 로그도 있습니다. 오류만 기록하며(성공은 기록하지 않음) 고객 개인 식별 정보나 민감한 데이터는 포함하지 않습니다. 빠른 식별을 위해 모든 항목에는 모듈 버전이 접두사로 붙습니다(예: [v10.09]).

URL 형식:

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

예시:

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code: miva_store_code는 모든 dashboard 주문에 대한 API 응답의 메타데이터 배열에 반환됩니다.

모든 결제 환불은 Zonos dashboard를 통해 직접 처리해야 합니다. Miva의 Refund, Capture, Void 버튼은 설계상 Zonos에서 가져온 주문에는 사용할 수 없습니다. Zonos에서 처리된 환불은 해당 Miva 주문의 결제 금액을 자동으로 업데이트하지 않습니다 -- Miva 주문은 원래 캡처된 금액을 그대로 유지하며 Zonos의 환불 활동과 동기화되지 않습니다.

주문 취소의 경우, 동작은 주문의 현재 상태에 따라 다릅니다.

• Open(아직 배송되지 않음): Miva에서 취소하면 Zonos에서도 취소되고 결제 승인이 무효화됩니다. Zonos는 주문이 배송될 때까지 결제를 캡처하지 않으므로 고객에게 실제로 청구되지 않으며 별도의 환불이 필요하지 않습니다.
• Shipped 또는 Completed: Miva에서 취소하면 Miva 주문은 취소됨으로 표시되지만, 주문이 이미 이행되어 자동 취소 대상이 아니므로 Zonos는 취소를 거부합니다. 이 경우 매장 직원에게만 표시되고 고객에게는 절대 표시되지 않는 관리자 전용 메모가 Miva 주문에 추가되어 해당 주문을 Zonos에서 처리해야 한다는 내용을 설명합니다. 또한 스토어 계정의 기본 이메일 주소로 알림 이메일이 전송되어 Zonos dashboard에서 조치를 취하도록 판매자에게 알리며, 여기서 해당하는 환불을 수동으로 처리할 수 있습니다.

증상: Zonos Checkout에서 주문이 완료되고 Zonos dashboard에는 표시되지만, Miva 관리자에는 아무것도 나타나지 않습니다.

원인: Zonos는 스토어의 /mm5/json.mvc 엔드포인트로 ORDER_CREATED 웹훅(HTTP POST)을 전송합니다. 개발 사이트에서는 서버 수준 보안이 이 요청이 Miva에 도달하기 전에 차단하는 경우가 많습니다. 흔한 원인은 다음과 같습니다.

• HTTP Basic Auth -- 개발 사이트에 비밀번호 프롬프트(Plesk, cPanel, .htaccess 등)가 있는 경우, 웹훅이 401 Unauthorized로 거부됩니다. .htaccess 또는 Plesk 설정에서 Zonos의 IP를 화이트리스트에 추가하여 인증 프롬프트를 우회하도록 하세요.
• Cloudflare WAF / IP Access Rules -- 사이트가 Cloudflare를 통해 프록시되는 경우, 보안 규칙이 요청이 서버에 도달하기 전에 POST를 차단할 수 있습니다. URL 경로에 /mm5/json.mvc가 포함된 POST 요청을 허용하는 WAF 규칙을 추가하거나, Cloudflare의 IP Access Rules에 Zonos의 IP를 직접 화이트리스트에 추가하세요.
• 서버 수준 IP 허용 목록 -- 개발 사이트가 특정 IP만 허용하도록 트래픽을 제한하는 경우(사무실 또는 플랫폼 IP로 제한된 스테이징 환경에서 흔함), Zonos 웹훅 요청은 응답 없이 조용히 삭제됩니다. 서버의 허용 목록(Plesk IP Access Restriction Manager, cPanel IP Blocker 또는 방화벽/호스팅 패널 보안 규칙)에 모든 Zonos 웹훅 전송 IP를 추가하세요.

Zonos 웹훅 전송 IP

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

이는 일반적으로 개발/스테이징 사이트에만 영향을 미칩니다 -- 프로덕션 Miva 사이트는 대개 공개되어 있으며 IP 화이트리스트 처리가 필요하지 않습니다. 구성 방법이 확실하지 않으면 호스팅 제공업체 또는 Miva 지원팀에 문의하세요.

제품 정보는 관세 및 세금 금액과 배송 비용에 영향을 줄 수 있습니다. Zonos에 제공하는 제품 정보가 많을수록 반환되는 견적이 더 정확해집니다. Zonos는 이 정보가 없어도 견적을 생성할 수 있지만, 정확도 향상을 위해 다음 핵심 제품 세부 정보 제공을 권장합니다.

• Weight: 무게는 배송 비용에 영향을 주며 관세 또는 세금에 영향을 줄 수 있습니다. Miva 제품 목록의 무게는 있을 경우 Zonos에서 자동으로 사용됩니다.
• Dimensions: 치수는 배송 비용에 영향을 줄 수 있으며 관세 또는 세금에 영향을 줄 수 있습니다. Zonos는 Miva의 각 제품에 설정된 제품 치수(길이, 너비, 높이)를 활용할 수 있지만, 올바른 통합을 위해 Zonos 앱에서 매핑해야 합니다.
• HS codes: HS code는 관세율에 영향을 주며 때로는 세금에 영향을 줄 수 있습니다. Zonos는 Miva 제품 목록에 설정된 HS code를 사용할 수 있지만 Zonos 앱에서 HS code 필드를 매핑해야 합니다.
• Country of origin: 제품의 원산지 국가는 관세율에 영향을 주며 세금에 영향을 줄 수 있습니다. Miva는 제품의 원산지 국가를 Zonos로 보낼 수 없으므로 Zonos Catalog를 사용하여 추가해야 합니다.

Miva에서 Zonos로 전달되는 제품 세부 정보 

Note: 또는 Catalog에 위 정보를 입력하여 Miva에서 저장 및 전달된 정보를 재정의할 수 있습니다.

플랫폼별 제품 정보에 대해 자세히 알아보기.