Insurance Booking - Post Login

Insurance

Insurance Booking - Post Login

Customers can see available insurance options on Citibank Online/Mobile application and buy insurance that fit their needs.

Hong Kong

India

Malaysia

Singapore

Api's Called

Insurance
Customers

Entry point for customers to apply for products

Logged-in customers can apply for insurance directly from the My Accounts page of Citibank Online/Mobile application

Zoom In

Display insurance options

Customers can select the type of insurance they want to purchase. 

Zoom In

Display policy choices

Customers may review a selection of eligible policies and choose their preferred option.

Upon choosing the option, customer gets redirected to partner's website.

Zoom In

Customer Consent

Customers can authorize Citi to share their data with third-party providers that they trust by clicking on 'Authorize'. After successful authorization, an access token is issued to the third party.

Refer to the API callouts for information about retrieving an authorization code and access token.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Authorization Code Grant: Retrieve authorization code using JWT

The third-party calls this API with the JWT token, the customer is then shown the consent page with the details of the data that will be shared with the third party for this journey. Once the customer selects "Agree," an AuthCode is generated and is returned to the third-party. 

Endpoint

Hong Kong: GET /authCode/oauth2/jwt/authorize

India: GET /authCode/oauth2/jwt/authorize

Malaysia: GET /authCode/oauth2/jwt/authorize

Singapore: GET /authCode/oauth2/jwt/authorize

Parameters

PATH

NA

Query

jwt

response_type=code

client_id

scope

countryCode

businessCode

locale

state

redirect_uri

 

View Api Callout 2 >
×

Use Case Callout

Retrieve Access Token

The third-party calls Citi with the Auth code. Citi then checks if Auth code is not expired and is still valid. In addition, Citi also checks if the Client ID and Secret are valid. Upon successful validation, Citi generates a customer specific token and returns it 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

The third-party calls the Customer Profile API to fetch the details of the customer. Citi then checks if the MFA was successful for the customer’s session. If the MFA is not triggered for the current session, Citi returns a 403 error to the third-party. 

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

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 Product detail

Customers can view more details about the product in partners page.

Third party uses the customer profile information to display the details.

Zoom In

API(s) Callout

View Api Callout 1 >
×

Use Case Callout

Customer Profile

After receiving the success response from the MFA validation, the third-party calls the Customer Profile API again to fetch the necessary customer 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

View Api Callout 2 >
×

Use Case Callout

Create And Update Offers

This API is used to create or update an offer for a customer.

Third party will use this API to update the offer status to Citibank.

Endpoint

Hong Kong: GET /v1/sales/customers/offers

Malaysia: GET /v1/sales/customers/offers

Singapore: GET /v1/sales/customers/offers

Parameters

PATH

NA

Query

Body

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

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

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 and purchase the policy.

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.

Variation for India: This API will save the request and returns a 403 error to the third-party for MFA OTP. 

 

Endpoint

Hong Kong: POST /v1/insurance/bookings

India: POST /v1/insurance/bookings

Malaysia: POST /v1/insurance/bookings

Singapore: POST /v1/insurance/bookings

Parameters

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