Bima Bima API Docs v1

Payment & Policy

After Submit: review the amount, take payment, verify it and issue the policy.

Review

Returns the same data as Read, but only the chosen offer in request_result.offers[0] (with its selected optional covers) and the amounts in payment. You need to make a POST call to the following url: POST/v1/Quotation/Review

FieldTypeLimitRequiredDescription
quotation_idstring500YesQuotation Id (encrypted)
lang_codestring2YesRequest language: en, ar
{ "quotation_id": "dldTUytwK0tReHpW...", "lang_code": "en" }
"payment": { "gross_amount": 54.5, "tax_amount": 0.844, "net_amount": 55.344, "vat_amount": 2.322, "total_premium": 57.666, "discount_amount": 0, "total_amount": 57.666, "cross_sell_data": [] }
Amount to pay Use payment.total_amount (fallback total_premium). Before Submit, Review answers 600 Invalid request.

Finalize

Freezes the quotation before payment; after Finalize the quote can no longer change. You need to make a POST call to the following url: POST/v1/Quotation/Finalize

FieldTypeLimitRequiredDescription
quotation_idstring500YesQuotation Id (encrypted)
quotation_id_parentstring500ConditionalAdd when the quotation has a parent (quotation_id_parent from Read)
offer_idstring20ConditionalSelected offer's id; "" for a group offer
offer_group_idstring20ConditionalSelected group offer's id; "" for a single offer
offer_amountnumber-YesAmount to pay from Review
trans_track_idstring-Fixed"0" before payment
trans_feenumber-Fixed0 before payment
lang_codestring2YesRequest language: en, ar
{ "quotation_id": "dldTUytwK0tReHpW...", "offer_id": "102328", "offer_group_id": "", "offer_amount": 57.666, "trans_track_id": "0", "trans_fee": 0, "lang_code": "en" }

Creates the payment page for the finalized quotation. Send the customer to data.checkoutUrl. You need to make a POST call to the following url: POST/v1/Payment/GetPaymentLink

FieldTypeLimitRequiredDescription
quotation_idstring500YesQuotation Id (encrypted)
offer_idstring20ConditionalSelected offer's id; "" for a group offer
offer_group_idstring20ConditionalSelected group offer's id; "" for a single offer
lang_codestring2YesRequest language: en, ar
modestring-Fixed"payment"
amountstring-YesAmount to pay, as a string, e.g. "57.666"
save_card_on_successboolean-OptionalSave the customer's card after a successful payment
finalize_request_typestring50YesThe quotation's request_type_code, e.g. MOTOR_PRIVATE_INSURANCE, TRAVEL_INSURANCE
{ "quotation_id": "dldTUytwK0tReHpW...", "offer_id": "102328", "offer_group_id": "", "lang_code": "en", "mode": "payment", "amount": "57.666", "save_card_on_success": false, "finalize_request_type": "MOTOR_PRIVATE_INSURANCE" }

After the gateway

The gateway returns to your payment result page with a tracking reference in the query (track_id2, TrackID2, trackId2, tracking_id or TrackID) and the gateway code pg_code. Then call, in order:

1. Verify Transaction

Confirms the payment result. You need to make a POST call to the following url: POST/v1/Payment/VerifyTransaction

FieldTypeLimitRequiredDescription
track_id2string-YesTracking reference from the gateway's return URL
payment_statusstring-Yessuccess on the success page, failed on the failure page
payment_gatewaystring-YesThe gateway code pg_code, e.g. Thawani, SUHAR_INTL
{ "track_id2": "<reference>", "payment_status": "success", "payment_gateway": "Thawani" }
Field name spelling On success, data.qoutation_id (spelt this way) is the paid quotation. Use it in the next step.

2. Auto Issue Policy

Issues the policy for the paid quotation. You need to make a POST call to the following url: POST/v1/Policy/AutoIssuePolicy

FieldTypeLimitRequiredDescription
quotation_idstring500Yesdata.qoutation_id from VerifyTransaction
lang_codestring2YesRequest language: en, ar
{ "quotation_id": "dldTUytwK0tReHpW...", "lang_code": "en" }

3. Payment Details

Returns the receipt details for the payment. You need to make a POST call to the following url: POST/v1/Payment/GetPaymentDetails

FieldTypeLimitRequiredDescription
Idstring-YesTracking reference from the gateway's return URL
{ "Id": "<reference>" }

Track the policy

Use Quotation/Track to follow the request: Pending = paid, policy being issued; Completed = issued and sent. Issued policy files can be downloaded through /v1/Document/Download?drefid=....