Split Payment & Reconciliation Guide

This guide is for Platform Partners who use the WeatherIT Insurance API to generate quotes but process payments via their own merchant facilities. To ensure insurance coverage is activated correctly, you must utilise "Split Payment" logic at the point of sale. This ensures that the premium is routed to WeatherIT while your primary product is routed to your account.

1. Architectural Overview

sequenceDiagram
    participant C as Customer
    participant P as Partner Platform
    participant GW as Payment Gateway
    participant API as WeatherIT API

    C->>P: Accepts quote at checkout
    P->>API: POST /quotes<br/>Get pricing + tax breakdown
    API-->>P: pricing_options[] with quote_id

    rect rgb(240, 248, 255)
        Note over P,GW: Split Payment
        P->>GW: Charge total amount<br/>(partner product + insurance premium)
        GW->>GW: Split funds<br/>Partner account ← product amount<br/>WeatherIT account ← premium amount
        GW-->>P: transaction_id
    end

    P->>API: POST /quotes/{id}/purchase<br/>customer + transactionId
    API-->>P: Active policy + policy_number
    P-->>C: Booking + policy confirmation

When a customer accepts a quote, your integration must perform a three-step process:

Quote: Fetch pricing and tax details from the /quotes endpoint.
Payment: Execute a split transaction via your Payment Gateway (Windcave, Stripe, or Adyen).
Activation: Send the transaction reference to our /purchase endpoint to activate the policy.

Data Mapping from WeatherIT Spec

WeatherIT API Response Field	Description	Your Gateway Mapping
`pricing_options[].quote_id`	Unique UUID for the policy option.	Primary Reference for the split.
`premium.total_premium`	Total amount to be collected for WeatherIT.	Amount for the insurance split.
`premium.tax_breakdown`	Dynamic object (e.g., `gst`, `stamp_duty`).	Metadata for tax compliance.

Note: Amounts used in examples below (e.g., $100.00 and $10.00) are illustrative examples only. Your implementation must use the dynamic values returned by the API.

Gateway Implementation Examples

Stripe (Connect Transfers)

If you use Stripe Connect, you collect the total funds and then "Transfer" the premium to the WeatherIT account.

{
  "amount": 110, 
  "currency": "aud",
  "transfer_group": "PARTNER_BOOKING_ID_123", 
  "metadata": {
    "booking_id": "PARTNER_BOOKING_ID_123",
    "quote_id": "QUOTE_ID_FROM_WEATHERIT",
    "base_premium": "8.50",
    "gst": "0.85",
    "stamp_duty": "0.65"
  },
  "transfer_data": {
    "amount": 100, 
    "destination": "WEATHERIT_STRIPE_ACCOUNT_ID"
  }
}

Adyen (Balance Platform)

Adyen uses a splits array to instruct the ledger how to partition funds at the moment of authorisation.

{
  "amount": { "value": 110, "currency": "AUD" },
  "reference": "PARTNER_BOOKING_ID_123",
  "splits": [
    {
      "amount": { "value": 100 },
      "type": "Default",
      "account": "YOUR_ACCOUNT_ID"
    },
    {
      "amount": { "value": 10 },
      "type": "Insurance",
      "account": "WEATHERIT_ACCOUNT_ID",
      "reference": "QUOTE_ID_FROM_WEATHERIT",
      "description": "GST:0.85|SD:0.65"
    }
  ]
}

Policy Activation (Critical Step)

Once the payment is successful, you must notify the WeatherIT API to move the policy from quote to active status.

{
  "customer": {
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Smith",
    "phone": "+61444000222"
  },
  "payment": {
    "transactionId": "GATEWAY_TRANSACTION_ID_123"
  },
  "bookingReference": "PARTNER_BOOKING_ID_123"
}

Compliance Responsibilities

Tax Invoicing: You must issue the customer a Tax Invoice itemising the premium, GST, and Stamp Duty as provided in the /quotes response.
Reconciliation: The quote_id must be passed in the payment reference field. Policies cannot be activated without a verified transaction ID linked to a valid Quote ID.