Custom integration

Om te beginnen, neem contact op met ons salesteam om een account aan te maken en een overeenkomst te ondertekenen. Zodra een overeenkomst is ondertekend, ontvangt u twee microstortingen op uw account die moeten worden geverifieerd.

E-mail deze microstortingsbedragen naar accounting@zonos.com met uw Dashboard store ID (CC uw sales rep).

Na verificatie worden uw bankgegevens weergegeven in Dashboard -> Settings -> Billing.

Na het aanmaken van uw Zonos-account moet u instellingen in Dashboard configureren om ervoor te zorgen dat Checkout correct werkt met uw winkel. Dit gedeelte behandelt alle essentiële Dashboard-configuraties.

Uitbetalingen instellen 

Koppel een bankrekening om tijdige uitbetalingen van Checkout te ontvangen. Uitbetalingen worden dagelijks verwerkt met een vertraging van 2 dagen na geïnde betaling. Volg hiervoor deze stappen:

1. Navigate to Dashboard -> Settings -> Checkout settings .
2. Click Add bank account
3. You will be taken to a Stripe portal to complete set up and provide the following information:
   • Bankrekeninggegevens.
   • Company EIN.
   • Social Security Number van een bedrijfseigenaar met 25% aandeel. Voor meer details waarom dit vereist is, zie Stripe's documentatie.

Opmerking: Als u uw uitbetalingsschema moet bijwerken, neem contact op met support@zonos.com

Toegestane domeinen instellen 

Het Zonos JS-script vereist een lijst met toegestane domeinen voor beveiligingsdoeleinden. Dit voorkomt dat ongeautoriseerde sites het script laden en zorgt ervoor dat het alleen op uw goedgekeurde domeinen draait. Zonder deze configuratie retourneert het script permission errors.

Stel dit als volgt in:

1. Navigate to Dashboard -> Settings -> Checkout settings
2. Under URLs, add your full domain and any subdomains where Checkout will be used. For example, if your domain is example.com, you should add example.com and test.example.com.

Branding-instellingen aanpassen 

Configureer uw branding-instellingen in Dashboard zodat ze passen bij de look and feel van uw winkel.

Volg hiervoor deze stappen:

1. Navigate to Dashboard -> Settings -> Checkout settings -> Branding
2. Configure the following settings:
   • Logo.
   • Brand and accent color.
   • Theme, Style, and Font.

Voor meer informatie over branding-instellingen, zie onze documentatie.

Een shipping carrier koppelen 

Om verzending bij checkout te offreren, moet u een shipping carrier koppelen aan uw Zonos-account. Hiermee kunt u specifieke shipping service levels bij checkout inschakelen.

Volg hiervoor deze stappen om een shipping carrier te koppelen:

1. Navigate to Dashboard -> Settings -> Shipping -> Rates
2. Click Add carrier
3. Volg de carrier setup-instructies.

Voor meer details over het koppelen van carrier accounts, zie onze documentatie.

Shipping zones instellen 

Shipping zones stellen u in staat te configureren welke shipping carriers en service levels beschikbaar zijn voor verschillende regio's van de wereld.

Volg hiervoor deze stappen om shipping zones in te stellen:

1. Navigate to Dashboard -> Settings -> Shipping -> Locations
2. Click New zone
3. Enter a zone name and select the countries you want to ship to.
4. Select the carrier and service level you want to offer.

Voor meer details over shipping zones, zie onze documentatie.

Fallback country of origin en HS code instellen 

Country of origin en HS code worden gebruikt om nauwkeurige invoerrechten en belastingen te berekenen.

Als u geen specifieke country of origin of HS code opgeeft, gebruiken we de fallbacks die in Dashboard zijn ingesteld.

Om uw fallback Country of Origin en HS code in te stellen:

1. Navigate to Dashboard -> Settings -> Shipping -> Catalog.
2. Selecteer voor country of origin het land waar de meerderheid van uw producten wordt vervaardigd.
3. Voer voor de HS code de HS code in van uw meest voorkomende product. Als u geen HS code hebt, ga naar Classify in Dashboard en voer de naam en beschrijving van uw product in om een nauwkeurige HS code te genereren.

Het Zonos JS-snippet is een client-side JavaScript-integratie die global checkout-functionaliteit op uw site inschakelt. Het fungeert als brug tussen uw ecommerceplatform en Zonos-services en regelt:

• Checkout Experience: Rendert de checkout UI en verwerkt betalingen.
• Location Services: Detecteert bezoekerslocatie en beheert valutaconversie.
• Cart Integration: Verbindt met uw bestaande cart- en ordersysteem.
• Security: Valideert domeinen en authenticeert API-requests.

Het snippet wordt asynchroon geladen om impact op de prestaties van uw site te voorkomen. Het initialiseert met de API-credentials van uw winkel en handelt alle client-side interacties veilig af. De implementatie is ontworpen om niet-opdringerig te zijn en vereist minimale wijzigingen aan uw bestaande checkout flow.

Hieronder staat een volledig voorbeeld met script loading, initialisatie en event handling als referentie bij het integreren van Checkout.

4. Geef de bijbehorende ID's door via uw Checkout customHTML zodat de relay weet tegen welke property/pixel te firen:

Voor stapsgewijze iframe-instructies, de volledige event reference (inclusief de purchase / Purchase payload mapping) en debugging tips, zie:

• Google Analytics 4 for iframe Checkout
• Facebook Pixel for iframe Checkout

Om bestellingen te synchroniseren tussen uw systeem en Zonos Dashboard, implementeert u deze API calls en webhooks:

Required Mutations 

Required Webhooks 

Voordat u live gaat met uw Checkout-integratie, is het belangrijk alle aspecten grondig te testen om een soepele klantervaring te garanderen. Dit omvat het testen van de checkout flow, betalingsverwerking, ordercreatie en webhook-functionaliteit.

Volg onze testgids om te verifiëren dat uw integratie correct werkt en om problemen te identificeren en op te lossen voordat u naar productie gaat.

Hieronder staan enkele veelgestelde vragen over het integratieproces.

Hoe handelt Zonos orderbevestiging af? 

Configureer de post-purchase ervaring in Dashboard -> Settings -> Checkout settings onder Success page type. Drie opties zijn beschikbaar:

• Show Zonos success page (default, recommended) — Zonos toont een ingebouwde bedankpagina nadat de bestelling is geplaatst. De pagina wordt altijd getoond, zelfs als import van de bestelling naar uw systeem mislukt, zodat de shopper altijd een bevestiging krijgt.
• Redirect to a success page — Zonos wacht op een kort „Order complete"-scherm totdat de bestelling is aangemaakt en stuurt dan door naar uw geconfigureerde success URL met zOrderNumber (en orderId voor legacy carts) als query params.
• Close the checkout modal — Zonos sluit zijn modal zodra betaling is geïnd. Als u ook een success URL configureert, stuurt Zonos onmiddellijk na Stripe-betaling door naar die URL — zonder te wachten tot de bestelling is aangemaakt — en voegt zonosCheckoutSessionId toe als query param. Gebruik deze optie wanneer u de snelste overdracht terug naar uw eigen success page wilt.

De bestelling opzoeken via zonosCheckoutSessionId 

Wanneer u Close the checkout modal met een redirect URL gebruikt, kan het enkele seconden duren voordat de bestelling aan de checkout session is gekoppeld na de redirect. Lees zonosCheckoutSessionId uit de URL en poll de checkoutSession GraphQL query vanaf uw server met uw secret credential token totdat de bestelling klaar is. Roep dit nooit aan vanuit de browser — de secret credential token moet server-side blijven.

Stuur de query naar https://api.zonos.com/graphql met uw secret credential token uit Dashboard -> Settings -> Integrations als credentialToken request header.

Kan ik een melding ontvangen wanneer een bestelling is aangemaakt? 

Ja. Als u meldingen wilt ontvangen wanneer een bestelling is aangemaakt, kunt u in Dashboard onder het gedeelte Email van Checkout settings het e-mailadres invoeren van teamleden die moeten worden geïnformeerd wanneer een bestelling is aangemaakt, verzonden of geannuleerd.