Contact us

V 1.3.5 - Insurance API

Version 1.3.5

Major changes:

  1. Add new operation POST /subscriptions/{insuranceSubscriptionId}/_cancel

  2. Change of response of GET /eligible-solutions

  3. Patches

Eligibility

Retrieve eligible insurance solutions

get

Retrieve eligible insurances solutions given a buyer country. As a result, you will obtain a list of insurances solutions codes with their related merchant kits. A merchant kit will allow you to display insurance visual name, label, description , logo and product terms to the customer. An empty json object is returned if no solution is eligible.

Authorizations
Query parameters
buyerBillingCountrystringRequired
Responses
200
The financed amount and country is eligible
application/json
get
GET /baas/prod/insurance/api/v1/eligible-solutions HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "solutions": [
    {
      "solutionCode": "SCFR3XY",
      "familyCode": "SC",
      "marketCode": "FR for France or DE for Germany",
      "conditions": "xxx",
      "communicationKit": {
        "solutionCode": "SCSPFR",
        "visualTitle": "Payez en 3 ou 4 fois",
        "visualInformationIcon": "XXX/XXX.ico (url icon)",
        "visualAdditionalInformation": "xxx",
        "visualLegalText": "xxx",
        "visualTableImage": "https://merchant.kit/uri/table.png",
        "visualLogo": "https://merchant.kit/uri/productTerms.ico",
        "visualInformationNoticeURL": "https://merchant.kit/uri/productTerms.pdf",
        "visualProductTermsURL": "https://merchant.kit/uri/productTerms.pdf"
      }
    }
  ]
}

Items

Create item

post

Request and create an item by probing the Insurance institution. As the result, you will get an item Id required for any insurance quotation.

Authorizations
Body
solutionCodestringRequired

ID of the BaaS product used

Example: CIFRWE-DXCOPattern: ^CI\w{4}-\w{4}$
skustringRequired

Item Stock Keeping Unit

Example: ZG011AQA
merchantItemIdstringRequired

The identifier of the item from merchant

Example: 8c6450c2-b142-11ed-afa1-0242ac120002
brandstringRequired

Item brand

Example: Beats
modelstringRequired

Item model

Example: Beats Solo3
titlestringRequired

Item title

Example: Beats Solo3 Wireless On-Ear Headphones
descriptionstringRequired

Item description

Example: Headphone Chip, Class 1 Bluetooth, 40 Hours of Listening Time, Built-in Microphone - Black (Latest Model)
characteristicsstringRequired

Item characteristics

Example: With up to 40 hours of battery life, Beats Solo3 wireless is your perfect everyday headphone...
categorystringRequired

Item category

Example: Headphones & Earbuds
Responses
201
Successful Response
application/json
post
POST /baas/prod/insurance/api/v1/items HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 462

{
  "solutionCode": "CIFRWE-DXCO",
  "sku": "ZG011AQA",
  "merchantItemId": "8c6450c2-b142-11ed-afa1-0242ac120002",
  "brand": "Beats",
  "model": "Beats Solo3",
  "title": "Beats Solo3 Wireless On-Ear Headphones",
  "description": "Headphone Chip, Class 1 Bluetooth, 40 Hours of Listening Time, Built-in Microphone - Black (Latest Model)",
  "characteristics": "With up to 40 hours of battery life, Beats Solo3 wireless is your perfect everyday headphone...",
  "category": "Headphones & Earbuds"
}
{
  "id": "abe12340-b1f5-11ed-afa1-0242ac120002"
}

Searches for Insurance Eligibility of the given item

post

Search for Insurance eligibility of the given item. As a result you will get a list of insurances options with their prices estimation and descriptions. So the buyer could pick one of the list for getting a quotation.

Authorizations
Body
solutionCodestringRequired

ID of the BaaS product used

Example: CIFRWE-DXCOPattern: ^CI\w{4}-\w{4}$
itemIdstringRequired

The identifier of the Item from producer moonshot

Example: abe12340-b1f5-11ed-afa1-0242ac120002
pricenumber · floatRequired

The item price

Example: 29.9
Responses
200
Product is eligible
application/json
post
POST /baas/prod/insurance/api/v1/items/_search-insurances HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "solutionCode": "CIFRWE-DXCO",
  "itemId": "abe12340-b1f5-11ed-afa1-0242ac120002",
  "price": 29.9
}
{
  "itemId": "abe12340-b1f5-11ed-afa1-0242ac120002",
  "solutionCode": "SCSPFR",
  "insurances": [
    {
      "id": "ABC001",
      "price": 49.9,
      "description": "Extension de garantie 2 ans"
    }
  ]
}

Quotations

Evaluate a quotation for the item and related price

post

Evaluate a quotation for the item and related price and a choosen insurance option by the buyer. As a result, you will get the insurance price confirmed. Important: a quotation will expire after a delay. Make sure the quotation is not expired before using it.

Authorizations
Body

Insurance Quotation Request Object

solutionCodestringRequired

ID of the BaaS product used

Example: CIFRWE-DXCOPattern: ^CI\w{4}-\w{4}$
itemIdstringRequired

item identifier

Example: 2343234567
itemPricenumber · floatRequired

price of the item

Example: 100.25
insuranceIdstringRequired

insurance identifier

Example: ABCD002
Responses
201
initiate an insurance quotation
application/json
post
POST /baas/prod/insurance/api/v1/quotations HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "solutionCode": "CIFRWE-DXCO",
  "itemId": "2343234567",
  "itemPrice": 100.25,
  "insuranceId": "ABCD002"
}
{
  "quoteId": "b01b69ed-c1b0-496f-8fb6-150554e34d23",
  "itemPrice": 100.25,
  "expirationDate": "2022-07-28T22:25:51.000Z"
}

Subscriptions

Retrieve a list of insurance subscriptions

get

You can list all your subscriptions or filter only some ones by specifying a reference such as a basket id. the response will contain subscription Id, dates, times, status, your references, amount financed ... Main use case: Use this API to retrieve status a insurance subscription by refering a basket Id. Important: The list is paginated

Authorizations
Query parameters
merchantBasketIdstringOptional
pageinteger · int32OptionalDefault: 1
pageSizeinteger · int32OptionalDefault: 20
Responses
200
List of insurance subscriptions
application/json
get
GET /baas/prod/insurance/api/v1/subscriptions HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "totalItemCount": 1,
  "subscriptions": [
    {
      "insuranceSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "registrationTimestamp": "2025-06-27T09:42:09.568Z",
      "lastUpdateTimestamp": "2025-06-27T09:42:09.568Z",
      "solutionCode": "SCFR3XY",
      "marketTypeCode": "FR",
      "duration": "2 ans",
      "merchantBasketId": "061be358-acb1-11ed-afa1-0242ac120002",
      "consolidatedStatus": "Initialized",
      "insuredItemPrice": 1199.99,
      "insuredItemCategory": "Small appliance",
      "producerQuoteInsurancePrice": 56.34
    }
  ]
}

Initiate a insurance subscription at the insurance institution side

post

To initiate a insurance subscription you will have to complete the requested parameters from the context of your checkout page of which identity, address of the buyer, Insurance ID choosen, insurance items details ... You can refer your insurance susbsription with your order or basket id. As a result you will get a insurance subscription Id with status "subscribed"

Important: the "solutionCode" is the parameter that determine the Producer's solution such as warrenty extension choosen by the buyer in the checkout page

Authorizations
Body
solutionCodestringRequired

ID of the BaaS product used

Example: CIFRWE-DXCOPattern: ^CI\w{4}-\w{4}$
quoteIdstringRequired
insuranceIdstringRequired
merchantBasketIdstringRequired

ID of the basket of the current transaction, as given by the merchant (thirdparty)

Example: 647aeb24-a89c-11ed-afa1-0242ac120002
merchantBuyerIdstringRequired

ID of the buyer (final customer), as given by the merchant (thirdparty)

Example: 44226c6c-aca7-11ed-afa1-0242ac120002
producerQuoteExpirationDatestring · dateRequired

Expiration date of the quote given before entering the subscription process

producerQuoteInsurancePricenumber · floatRequired

Price of the policy subscribed, given by the quotation

Example: 56.34
Responses
201
initiate an insurance subscription
application/json
post
POST /baas/prod/insurance/api/v1/subscriptions HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 877

{
  "solutionCode": "CIFRWE-DXCO",
  "quoteId": "text",
  "insuranceId": "text",
  "merchantBasketId": "647aeb24-a89c-11ed-afa1-0242ac120002",
  "merchantBuyerId": "44226c6c-aca7-11ed-afa1-0242ac120002",
  "producerQuoteExpirationDate": "2025-06-27",
  "producerQuoteInsurancePrice": 56.34,
  "buyer": {
    "contact": {
      "lastName": "Dupont",
      "firstName": "Paul",
      "email": "[email protected]",
      "mobilePhoneNumber": "07 55 55 66 66",
      "phoneNumber": "07 55 55 66 66"
    },
    "address": {
      "streetNumber": 147,
      "streetNumberSuffix": "B",
      "streetName": "main street",
      "streetNameComplement": "block 47",
      "zipCode": "92060",
      "cityName": "Paris",
      "regionName": "Île-de-France",
      "countryCode": "FR"
    }
  },
  "insuredItem": {
    "id": "M12345785513211",
    "label": "ROBOT PÂTISSIER À BOL RELEVABLE 4,8L - HEAVY DUTY 5KPM5",
    "brandName": "LG",
    "price": 1199.99,
    "currencyCode": "EUR",
    "orderId": "OD456742",
    "category": "Small appliance",
    "sku": "ZG011AQA",
    "insurancePrice": 100.25
  }
}
{
  "insuranceSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "consolidatedStatus": "Initialized"
}

Retrieve a specific insurance subscription

get

You get all details of an insurance subscription. You will have to provide a insurance subscription Id previously obtained as listed or initiated.

Authorizations
Path parameters
insuranceSubscriptionIdstringRequired
Responses
200
Specific Insurance subscription
application/json
get
GET /baas/prod/insurance/api/v1/subscriptions/{insuranceSubscriptionId} HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "insuranceSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "registrationTimestamp": "2025-06-27T09:42:09.568Z",
  "lastUpdateTimestamp": "2025-06-27T09:42:09.568Z",
  "marketTypeCode": "FR",
  "duration": "2 ans",
  "merchantBasketId": "647aeb24-a89c-11ed-afa1-0242ac120002",
  "consolidatedStatus": "Initialized",
  "solutionCode": "PSCFR3X",
  "clientId": "44f5060e-a89c-11ed-afa1-0242ac120002",
  "thirdPartyReferenceId": "647aeb24-a89c-11ed-afa1-0242ac120002",
  "familyCode": "CI",
  "merchantBuyerId": "44226c6c-aca7-11ed-afa1-0242ac120002",
  "buyer": {
    "contact": {
      "lastName": "Dupont",
      "firstName": "Paul",
      "email": "[email protected]",
      "mobilePhoneNumber": "07 55 55 66 66",
      "phoneNumber": "07 55 55 66 66"
    },
    "address": {
      "streetNumber": 147,
      "streetNumberSuffix": "B",
      "streetName": "main street",
      "streetNameComplement": "block 47",
      "zipCode": "92060",
      "cityName": "Paris",
      "regionName": "Île-de-France",
      "countryCode": "FR"
    }
  },
  "insuredItem": {
    "id": "M12345785513211",
    "label": "ROBOT PÂTISSIER À BOL RELEVABLE 4,8L - HEAVY DUTY 5KPM5",
    "brandName": "LG",
    "price": 1199.99,
    "currencyCode": "EUR",
    "orderId": "OD456742",
    "category": "Small appliance",
    "sku": "ZG011AQA",
    "insurancePrice": 100.25
  },
  "producerQuoteInsurancePrice": 56.34
}

Cancellations

Request a cancellation according to a specific insuranceSubscriptionId

post

Request a cancellation according to a specific insuranceSubscriptionId. As a response, you will get the confirmation of the cancellation.

Authorizations
Path parameters
insuranceSubscriptionIdstringRequired
Body
cancellationStatusstring · enumOptionalPossible values:
originstringOptional
Responses
204
Insurance cancellation confirmation response
*/*
Responseobject
post
POST /baas/prod/insurance/api/v1/subscriptions/{insuranceSubscriptionId}/_cancel HTTP/1.1
Host: api.scalexpert.societegenerale.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "cancellationStatus": "cancelled",
  "origin": "text"
}
{}

Download OpenApi specs:

37KB
swagger_insurance_1.3.5.yaml
PreviousV 1.3.8 - Insurance APINextV 1.1 - Insurance API

Last updated

Was this helpful?