Insurance Booking - Pre Login

Insurance

Insurance Booking - Pre Login

Customers can see available options and buy insurance that fit their needs without leaving the third-party platform.

Hong Kong

India

Malaysia

Singapore

Api's Called

Insurance

Showcase insurance offers

Customers learn about Citi-connected offers for insurance plans on a third-party platform.
Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Authorize code grant: Retrieve authorization code

This API is used to call the 3 legged oAuth Citi page to authenticate the customer.

Endpoint

Hong Kong: GET /authCode/oauth2/authorize

India: GET /authCode/oauth2/authorize

Malaysia: GET /authCode/oauth2/authorize

Singapore: GET /authCode/oauth2/authorize

Parameters

PATH

NA

Query

response_type=code

client_id

scope

countryCode

businessCode

locale

state

redirect_uri

Body

NA

Secure identification

Customers can log in to Citi securely with their Citi User ID and password.

Zoom In

Customer Consent

Customers can authorize Citi to share their data with trusted third-party providers.
Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Retrieve Access Token

After successful authentication, customers will see the consent page. There they can review the data that will be shared with the partner. If a customer agrees, we’ll generate an authorization token and send it to the partner.

The steps are as follows:

  1. Partner calls the API below with an authorization code
  2. Citi checks if the authorization code is valid and has not expired
  3. Citi also checks if the partner’s client ID and secret are valid
  4. Upon successful validation, Citi generates an authorization token and returns to partner

Endpoint

Hong Kong: POST /authCode/oauth2/token/<countryCode>/<businessCode>

India: POST /authCode/oauth2/token/<countryCode>/<businessCode>

Malaysia: POST /authCode/oauth2/token/<countryCode>/<businessCode>

Singapore: POST /authCode/oauth2/token/<countryCode>/<businessCode>

Parameters

PATH

countryCode

businessCode

Query

NA

FormData

grant_type

code

redirect_uri

One-Time Pin (OTP) validation

Consenting customers can receive an OTP from Citi on their registered mobile number and then validate it. Once validated, Citi will share the customer’s profile details with the third-party and customers will be directed to the third-party site.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Customer Profile

Partner to call the customer profile API to fetch the details of the customer. Citi to check if  session-level Multi-Factor Authentication (MFA) was successful for the customer’s session. If the MFA isn’t done for the current session, Citi will return a 403 error to the partner.

Endpoint

Hong Kong: GET /partner/v1/customers/profiles

India: GET /partner/v1/customers/profiles

Malaysia: GET /partner/v1/customers/profiles

Singapore: GET /partner/v1/customers/profiles

 

Parameters

PATH

NA

Query

addressType

Body

NA

View Api Callout 2 >
×

Use Case Callout

Multi-Factor Authentication (MFA)

The partner calls the Citi MFA page. The customer enters the One-Time Pin (OTP) sent to their registered mobile number, and Citi validates the OTP. After a successful OTP authentication, Citi responds with success or error (in case validation failed) on the redirect URL registered by the partner. Please note: the MFA APIs aren’t available in the sandbox.

Endpoint

Hong Kong: /oauth2/mfa

India: /oauth2/mfa

Malaysia: /oauth2/mfa

Singapore: /oauth2/mfa

Parameters

PATH

Query

client_id

mfaCode

redirect_uri

Body

Response
<<Partner Redirect URI>>?mfaStatus=success&state=<<echo back whatever is sent in request>>

View Api Callout 3 >
×

Use Case Callout

Customer Profile for MFA

After receiving the “success” response through Multi-Factor Authentication validation, the partner calls the customer profile API again to fetch the customer’s demo details.

Endpoint

Hong Kong: GET /partner/v1/customers/profiles

India: GET /partner/v1/customers/profiles

Malaysia: GET /partner/v1/customers/profiles

Singapore: GET /partner/v1/customers/profiles

 

Parameters

PATH

NA

Query

addressType

Body

NA

Insurance options

After authentication, customers may review a selection of eligible products and choose their preferred option. 

Zoom In

Underwriting Questionnaire

After selecting a product, customers take a questionnaire in order to proceed.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Customer Insurance Risk Score

This API is used to retrieve insurance details including re-insurer model, pre-underwriting score and propensity score.

Based on this score Partner can show appropriate questionare to customer.

Endpoint

Hong Kong: GET /partner/v1/insurance/customers/risks

India: GET /partner/v1/insurance/customers/risks

Malaysia: GET /partner/v1/insurance/customers/risks

Singapore: GET /partner/v1/insurance/customers/risks

 

Parameters

PATH

NA

Query

NA

Body

NA

Product Disclosure Sheet

Customers review the product details in the product disclosure sheet in order to proceed.

Zoom In

Customer can request for a call back

In case customer has any query and wants to discuss further, there is an option for call back.
Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Capture Customer CallBack Or DropOff Details

This API is used to capture the drop off and Call back information.

Endpoint

Hong Kong: POST /v1/customers/callbackOrDropOff

India: POST /v1/customers/callbackOrDropOff

Malaysia: POST /v1/customers/callbackOrDropOff

Singapore: POST /v1/customers/callbackOrDropOff

 

Parameters

PATH

NA

Query

NA

Body

CaptureCustomerCallBackOrDropOffDetailsRequest

Customer Declaration

Customers can review and agree to the insurer's terms and conditions of the selected insurance product.

Zoom In

Purchase the policy

Customers can select which Citi account they’d like to use at purchase.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

InsuranceSourceAccountEligibility

This API returns customer’s source accounts eligible for insurance booking.

Endpoint

Hong Kong: GET /v1/insurance/bookings/sourceAccounts

India: GET /v1/insurance/bookings/sourceAccounts

Malaysia: GET /v1/insurance/bookings/sourceAccounts

Singapore: GET /v1/insurance/bookings/sourceAccounts

Parameters

PATH

NA

Query

NA

Body

NA

View Api Callout 2 >
×

Use Case Callout

CustomerInsuranceBooking

This API will debit the customer and pass the policy details to the insurance host.

Endpoint

Hong Kong: POST /v1/insurance/bookings

India: POST /v1/insurance/bookings

Malaysia: POST /v1/insurance/bookings

Singapore: POST /v1/insurance/bookings

Parameters

NA

PATH

NA

Body

CustomerInsuranceBookingRequest

One-Time Pin (OTP) validation before payment

Customers receive an OTP from Citi on their registered mobile number and then validate it.

After receiving the success response from the MFA validation, the third-party calls the CustomerInsuranceBookingConfirmation API and once OTP is validated, Citi will debit the premium and book the insurance policy.

Note: This is applicable only for India.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

MFA 

The third-party calls Citi's MFA page, whereby the customer enters their OTP code, sent to their registered mobile number. Citi then validates the OTP. After successful authentication, Citi will respond back with a success or error (in case validation failed) on the redirect URL registered by the third-party.  The MFA API is not available on the sandbox.

Endpoint

Hong Kong: /oauth2/mfa

India: /oauth2/mfa

Malaysia: /oauth2/mfa

Singapore: /oauth2/mfa

Parameters

PATH

Query

client_id

mfaCode

redirect_uri

Body

Response - 
<<Partner Redirect URI>>?mfaStatus=success&state=<<echo back whatever is sent in request>>

View Api Callout 2 >
×

Use Case Callout

CustomerInsuranceBookingConfirmation

This API will debit the customer and pass the policy details to the insurance host. This API will be called after the MFA OTP is successfully validated.

Endpoint

India: POST /v1/insurance/bookings/confirmation

Parameters

PATH

NA

Body

CustomerInsuranceBookingConfirmationRequest

Booking Confirmation

Customers can receive an acknowledgment on booking confirmation along with the policy number.

Zoom In