Guides

Scenario 1: Sensible Weather is Merchant of Record

Suggest Edits

When Sensible Weather is the Merchant of Record (MoR) for Weather Guarantee purchases, we are responsible for charging the customer for the cost of the Weather Guarantee and refunding the customer if they cancel their Weather Guarantee.

The most common payments flow in this scenario is as follows:

  1. Customer's cart includes both their primary booking (e.g. tickets, lodging nights, tee times) and the Weather Guarantee for the booking. The total cart amount is ($booking + $booking_taxes) + ($weather_guarantee + $weather_guarantee_taxes).
  2. Customer enters payment information once and clicks pay to checkout.
  3. The partner splits the payment into two separate charges. The first charge is for $booking + $booking_taxes, which the partner charges the customer using their preferred payment processing method. The second charge is for $weather_guarantee + $weather_guarantee_taxes. Implementation specifics will vary, but the customer's payment instrument will be charged for the cost of the Weather Guarantee with Sensible.
  4. Sensible Weather will create an active Weather Guarantee after the charge succeeds
  5. Future refunds of the Weather Guarantee are handled by Sensible Weather.

The steps above are the abstracted version of the preferred approach for handling payments. Specific implementations are detailed below.

📘

Note: When Sensible is the MoR, we are required to collect and remit sales tax on the Weather Guarantee. Sales tax for the Weather Guarantee is calculated based on the billing address of the customer. As a result, we require partners to use our AssessTaxes endpoint to add sales tax to the quote when we are the MoR. See the Tax Assessment Requirements section for more details.

Approach 1: AcceptAndCharge with plain text payments information

The AcceptAndCharge endpoint enables partners to accept and charge for a Weather Guarantee by passing Sensible Weather payments information as part of the request. This is the preferred approach for payment processing and is PCI DSS certified to ensure all payments information is handled securely.

  1. Partner calls CreateGuaranteeQuote with the name, location, dates, and cost of the booking

  2. Partner presents the quote to the customer and the customer adds the quote to their cart

  3. Partner collects billing address information for the customer

  4. Partner calls the AssessTaxes endpoint with the quote ID (from step 1) and the customer billing address. This endpoint adds the correct sales tax to the quote object. Partner should update the cart to reflect the updated cost of the Weather Guarantee with tax included.

  5. Customers enters payment details and clicks pay/confirm/checkout

  6. Partner calls the AcceptAndCharge endpoint with the payment object in the below request.

    1. Endpoint: https://gateway.payments.protect.sandbox.sensibleweather.io/tokenize/proxy/accept-and-charge

    2. Request Headers

      1. TX-Proxy-Key: {{txProxyKey}} This value will be provided by the Sensible Weather team during onboarding and will vary between sandbox and production environments
      2. Authorization: Bearer {{protectBearerToken}} This auth token will follow the same procedure as outlined the standard Accept Guarantee Quote endpoint

    3. Sample Request:

      {
    "guarantee_quote_id": "cce750c6-78f0-4697-bf0e-17fe5744e882" ,
    "reservation_id": "R1294868", 
    "user": {
        "name": "Lou Reed",
        "phone": "+18129005555",
        "email": "[email protected]"
    },
    "payment": {
        "card": {
            "number": "4242424242424242",
            "exp_month": "12",
            "exp_year": "2025",
            "cvc": "000"
        }
    },
    "billing_address": {
        "address_line_1": "123 Main St",
        "city": "Los Angeles",
        "region": "CA",
        "country": "USA",
        "postal_code": "90069"
    }
}

  7. Partner handles the response:

    1. The response will have the following form:
    2. {
    "id": "e72d5143-37c6-4504-8b0f-ff8278e9af33",
    "product_id": "a556c381-59dd-4555-a601-f77059d62334",
    "created_at": "2024-03-18T12:56:04Z",
    "coverage_start_date": "2024-07-10",
    "coverage_end_date": "2024-07-11",
    "coverage_start_hour": "08:00:00 -0500",
    "coverage_end_hour": "22:00:00 -0500",
    "lang_locale": "en-US",
    "wholesale_price": 100,
    "suggested_price": 111.99,
    "user_email": "[email protected]",
    "tax_amount": 0,
    "tax_rate": 0,
    "price_charged": 111.99,
    "reservation_id": "R1294868",
    "currency": "USD",
    "exposure_name": "Devil's Tomstone Campsite 14A",
    "exposure_latitude": 39.0847222222,
    "exposure_longitude": -96.36,
    "exposure_total_coverage_amount": 1000,
    "exposure_protections": [
        {
            "name": "rainfall",
            "upper_threshold": 0.0015,
            "unit": "meter"
        }
    ],
    "payout_tiers": [
        {
            "number_of_hours": 3,
            "payout_amount": 150.26
        }
    ],
    "documents": [
        {
            "name": "Terms and Conditions",
            "link": "https://www.sensibleweather.com/guarantee-terms-and-conditions"
        },
        {
            "name": "View our Privacy Policy",
            "link": "https://www.sensibleweather.com/sensible-weather-privacy-policy"
        }
    ]
}
    3. Store the id from the AcceptAndCharge response. This id is the GuaranteeID and can be used for managing the guarantee via the GetGuaranteeByID and CancelGuarantee endpoints.
    4. If an error is received, retry with exponential backoff. We recommend 3 retries. If all retries fail, then the Weather Guarantee was not created and we did not charge the customer. This information should be surfaced to the customer during the checkout flow on the partners site.

If the API returns a success response, the partner can assume that the payment was charged correctly and the Weather Guarantee is active.

Approach 2: Network tokens

📘

Coming Soon

Network Tokens replace traditional card details with a unique digital identifier, enhancing the security of online and mobile transactions by preventing the exposure of sensitive card information. This approach mitigates fraud and ensures a more secure ecosystem for both merchants and consumers. Partners that already use network tokens can leverage them when facilitating payment of a Weather Guarantee. Contact us to learn more about leveraging network tokens in your Sensible Weather integration.

Other Approaches

We are constantly working with our partners to support new ways of processing Weather Guarantee payments. Please reach out if your payments flow requires a different approach than we've listed above.

Updated 7 months ago