If you are using ByBits' Stripe integration, here is how to create a policy with payments.

Step 1. Create a Stripe payment intent

Use the POST /payments endpoint to create a Stripe payment intent. This will be needed when taking card payments on the client side.

Example JSON Body

{ 
    "type": "CREATE_PAYMENT_INTENT", 
    "product_reference": "bybits_usage", 
    "amount": 1000 
}

Example response

{ 
    "type": "CREATE_PAYMENT_INTENT", 
    "payment_provider_customer_ref": "cus_JyMzf3HpAkJw", 
    "payment_provider_transaction_ref": "pi_1JKQF5ErCACt4akxB287Q",
    "payment_temporary_token": "pi_1JKQF5ErCACt4akxB287QUwH_secret_dd" 
}

Step 2. Collect and confirm payment with Stripe

On the client side, credit card information needs to be collected. Stripe offer Stripe Elements and plenty of examples.

Then, confirm the payment using stripe.confirmCardPayment function from Stripe's SDK. An example can be found in submitting a payment in Step 3 of Stripe's quickstart guide.

The clientSecret provided in the example below needs to be the payment_temporary_token value from the response found in Step 1

Take care to setup_future_usage to 'off_session'.

Code Example

stripe.confirmCardPayment( 
    clientSecret, <--- This is payment_temporary_token value from the response in step 1. i.e. "pi_1J7ePXErCACt4akxDikMyjkw_secret_zckGvakAEmN"  { 
     payment_method: { 
         card: card, 
     }, 
     setup_future_usage: 'off_session' 
});

Example Response

{ 
    "id": "pi_1JKQF5ErCACt4akxB287QUwH", 
    "object": "payment_intent", 
    "amount": 320000, 
    "canceled_at": null, 
    "cancellation_reason": null, 
    "capture_method": "automatic", 
    "client_secret": "pi_1JKQF5ErCACt4akxB287QUwH_secret_ddQUHsT2b3zN7nT7YEJgCC2AX",  "confirmation_method": "automatic", 
    "created": 1628007203, 
    "currency": "gbp", 
    "description": null, 
    "last_payment_error": null, 
    "livemode": false, 
    "next_action": null, 
    "payment_method": "pm_1JKQF5ErCACt4akxMS1TyzYf", 
    "payment_method_types": [ 
    "card" 
 ], 
    "receipt_email": null, 
    "setup_future_usage": "off_session", 
    "shipping": null, 
    "source": null, 
    "status": "succeeded" 
}

Step 3. Create the Policy

Create your policy as usual and provide any fees such as admin and cancellation fees as shown below. When a mid-term adjustment is made on a policy using the admin portal or POST /policys,  the upfront_premium and mta_fee from the pricing block will be used to calculate a payment or refund if no payment_amount is provided in a payment block. This is also the case when using the policy cancellation feature in the admin portal or using DEL /policys. A refund is calculated pro-rota. Then any cancellation fees, and admin fees will be also be applied accordingly.

The payment json block will also need to be provided (as shown below) when creating a policy to associate the payment with the policy. This is so that when it comes to cancellations or MTAs. The amounts will be processed via Stripe.

Http request

POST /policys

Example JSON body

{ 
  "policy": { 
    "compulsory_excess": 100, 
    "voluntary_excess": 100, 
    "address": { 
    "line_1": "Flat 1, 11 The Street", 
    "line_2": "Little Hampton", 
    "line_3": "Burton-on-the-water", 
    "city": "Stroud", 
    "county": "", 
    "country": "GB", 
    "postcode": "W53TR" 
 }, 
    "usage": "SDP", 
    "cover": "Comprehensive", 
    "auto_renew": true, 
    "start_date": 1625094000,  
    "end_date": 1656630000, 
    "billing_day_date": 30, 
    "underwriter_reference": "Zurich", 
    "underwriter_policy_reference": "AXABM000001", 
    "product_reference": "by_bits_usage", 
    "policy_year": 2021, 
    "inception_date": 1625094000, 
    "subscription_frequency": 0 
 }, 
   "proposer": { 
     "title": "003", 
     "first_names": "Chuen", 
     "last_names": "Lee", 
     "email": "dave@fakeemail.co.uk", 
     "phone_number": "+447999000011", 
     "children": 1, 
     "has_medical_conditions": false, 
     "has_informed_dvla_medical_conditions": false, 
     "ncd": 5, 
     "dob": "1980-12-31", 
     "licence_type": "F", 
     "employment": "E", 
     "occupation": "51D", 
     "business": "077",
     "licence_issued_date": "2000-12-31",  "residency_date": "2000-12-31",  "has_criminal_conviction": false,  "convictions": [ 
     { 
         "code": "AC10", 
         "date": "2018-01-01",  "points": 3, 
         "ban": 0 
     }], 
     "claims": [ 
      { 
         "code": "A", 
         "date": "2016-01-01",  "at_fault": false,  "ncd_lost": false  
      }] 
 }, 
   "vehicle": { 
     "reg": "WO123XX", 
     "vin": "YV1UZ25UCK1337428",  "body_type": "01", 
     "type": "01", 
     "make": "tesla", 
     "model": "S", 
     "colour": "black", 
     "group_rating_50": 21, 
     "group_rating_20": 10, 
     "abi_code": "01001000", 
     "engine": 1650, 
     "fuel": "001", 
     "owner": "1", 
     "keeper": "E", 
     "estimated_yearly_mileage": 10000,  "purchase_date": "2016-01-01",  "manufacture_date": "2016-01-01",  "current_value": 1000, 
     "is_rhd": true, 
     "seats": 1, 
     "is_parked_home": true, 
     "is_import": true, 
     "modifications": [ 
         "1" 
     ] 
 }, 
     "additional_drivers": [{ 
         "relationship": "P", 
         "title": "003", 
         "first_names": "Dave",  "last_names": "Jones",  "email": "dave@jones.com",
         "mobile_number": "+447999000011", 
         "children": 1, 
         "has_medical_conditions": true, 
         "has_informed_dvla_medical_conditions": false,  "ncd": 1, 
         "dob": "1980-12-31", 
         "licence_type": "F", 
         "employment": "E", 
         "occupation": "51D", 
         "business": "077", 
         "licence_issued_date": "2000-12-31", 
         "residency_date": "2000-12-31", 
         "has_criminal_conviction": false, 
     "convictions": [{ 
         "code": "AC10", 
         "date": "2018-01-01", 
         "points": 3, 
         "ban": 0 
     }], 
     "claims": [{ 
         "code": "A", 
         "date": "2016-01-01", 
         "at_fault": false, 
         "ncd_lost": false 
     }] 
 }], 
 "pricing": { 
        "quote_reference": "747a0a2b-55bd-4a9b-af38-315dd0a89612",  "quote_version_reference": "dc6df20a-6cb2-4890-9226-039790a89c63",  "quote_model_reference": "7189fefa-c290-415e-84cf-e5effec402f3",
    "total_excess": 0, 
    "subscription_installments": 0, 
    "commission_rate": 10, 
    "ipt_rate": 12.5, 
    "base_premium": 3071.51, 
    "upfront_rate": 3071.51, 
    "upfront_premium": 3071.51, 
    "subscription_rate": 0, 
    "subscription_premium": 0, 
    "usage_rate": 0, 
    "usage_premium": 0, 
    "estimated_distance": 2000, 
    "yearly_premium_estimate": 3071.51, 
    "withhold_fee": 20, 
    "deposit_fee": 30, 
    "admin_fee": 50, 
    "mta_fee": 20, 
    "cancel_fee": 10 
 },
 "payment": {  
    "provider_payment_reference": "pi_1JKQF5ErCACt4akxB287QUwH",  
    "payment_method_id": "pm_1JKQF5ErCACt4akxMS1TyzYf", 
    "provider_customer_reference": "cus_JyMZJZcfWRjDjV", 
    "payment_provider": "stripe" 
 } 
}

The payment block

  • provider_payment_reference - This is id value from the stripe.confirmCardPayment function found in Step 2.
  • payment_method_id - This is the payment_method value from the stripe.confirmCardPayment function found in Step 2.
  • provider_customer_reference - This is the payment_provider_customer_ref value from the response found in Step 1.
  • payment_provider - This is set to stripe.