Payment & Policy
After Submit: review the amount, take payment, verify it and issue the policy.
Payment options
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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| quotation_id | string | 500 | Yes | Quotation Id (encrypted) |
| lang_code | string | 2 | Yes | Request 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": []
}
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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| quotation_id | string | 500 | Yes | Quotation Id (encrypted) |
| quotation_id_parent | string | 500 | Conditional | Add when the quotation has a parent (quotation_id_parent from Read) |
| offer_id | string | 20 | Conditional | Selected offer's id; "" for a group offer |
| offer_group_id | string | 20 | Conditional | Selected group offer's id; "" for a single offer |
| offer_amount | number | - | Yes | Amount to pay from Review |
| trans_track_id | string | - | Fixed | "0" before payment |
| trans_fee | number | - | Fixed | 0 before payment |
| lang_code | string | 2 | Yes | Request 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"
}
Payment Link
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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| quotation_id | string | 500 | Yes | Quotation Id (encrypted) |
| offer_id | string | 20 | Conditional | Selected offer's id; "" for a group offer |
| offer_group_id | string | 20 | Conditional | Selected group offer's id; "" for a single offer |
| lang_code | string | 2 | Yes | Request language: en, ar |
| mode | string | - | Fixed | "payment" |
| amount | string | - | Yes | Amount to pay, as a string, e.g. "57.666" |
| save_card_on_success | boolean | - | Optional | Save the customer's card after a successful payment |
| finalize_request_type | string | 50 | Yes | The 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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| track_id2 | string | - | Yes | Tracking reference from the gateway's return URL |
| payment_status | string | - | Yes | success on the success page, failed on the failure page |
| payment_gateway | string | - | Yes | The gateway code pg_code, e.g. Thawani, SUHAR_INTL |
{
"track_id2": "<reference>",
"payment_status": "success",
"payment_gateway": "Thawani"
}
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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| quotation_id | string | 500 | Yes | data.qoutation_id from VerifyTransaction |
| lang_code | string | 2 | Yes | Request 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
| Field | Type | Limit | Required | Description |
|---|---|---|---|---|
| Id | string | - | Yes | Tracking 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=....