Sell Insurance
Sell a motor insurance policy to a customer, paid from your insurance agent wallet: type 1 issues a new motor policy and type 2 renews an existing policy. The wallet is charged the full premium and you earn a 10% commission on the issued policy. The insurer can take up to a minute to answer, so a pending result is normal: confirm it with Sales Status.
Request History
Your request history will appear here.
Headers
Your Moolre username.
Your Private API Key for the paying wallet.
Send application/json.
Optional. A repeat of the same request with the same key returns the first response instead of selling again.
Body Params
1 sells a new motor policy; 2 renews an existing policy.
Your insurance agent wallet account number. It is charged the premium.
Your unique reference for this sale, at most 128 characters, unique per wallet. extid is accepted as an alternative field name; send only one.
Premium in GHS, as a decimal amount above 0.00. For type 1, the premium Quote returned for the cover. For type 2, the renewal premium due.
Policy details. For type 1: pol_type, cover_type, com_date, exp_date, sum_insured, benefits, customer and motor. For type 2: pol_no, payment_date and optional customer details. Field tables are below.
Optional. Must be GHS when sent.
Responses
The policy was issued: txstatus 1, stage issued. The example values are illustrative.
{
"status": "1",
"code": "IS20",
"message": "The insurance policy has been issued.",
"data": {
"txstatus": 1,
"stage": "issued",
"reference": "SALE-REFERENCE",
"transactionid": 123456789,
"externalref": "your-extid",
"accountnumber": "10XXXXXXXXXXXX",
"premium": "1250.00",
"charged": "1250.00",
"commission": "125.00",
"commission_status": "paid",
"refundid": null,
"provider_message": "Policy created",
"policy": {
"pol_no": "POLICY-NUMBER",
"certificate_url": "https://example.com/certificate",
"sticker_no": "STICKER-NUMBER",
"sticker_url": "https://example.com/sticker",
"brown_card_url": "https://example.com/brown-card"
}
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The insurer has not answered definitively. The wallet is charged and the policy is not issued yet. Check Sales Status with the externalref; do not send again.
{
"status": "1",
"code": "IS21",
"message": "Your policy is being confirmed with the insurer. Check again shortly.",
"data": {
"txstatus": 0,
"stage": "awaiting_insurer",
"reference": "SALE-REFERENCE",
"transactionid": 123456789,
"externalref": "your-extid",
"accountnumber": "10XXXXXXXXXXXX",
"premium": "1250.00",
"charged": "1250.00",
"commission": "0.00",
"commission_status": null,
"refundid": null,
"provider_message": "",
"policy": null
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The API got no readable answer within its time limit. The sale may still go through; it is reported as pending, never as failed.
{
"status": "1",
"code": "ASL11",
"message": "Insurance sale in progress, please check its status.",
"data": {
"txstatus": 0,
"stage": "awaiting_insurer",
"transactionid": "Pending",
"externalref": "your-extid",
"premium": "1250.00"
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The insurer refused the policy and the charge was refunded: txstatus 2. A new purchase is safe.
{
"status": "0",
"code": "IS22",
"message": "The policy could not be issued. You have not been charged.",
"data": {
"txstatus": 2,
"stage": "refunded",
"reference": "SALE-REFERENCE",
"transactionid": 123456789,
"externalref": "your-extid",
"accountnumber": "10XXXXXXXXXXXX",
"premium": "1250.00",
"charged": "1250.00",
"commission": "0.00",
"commission_status": null,
"refundid": 123456790,
"provider_message": "Policy could not be created",
"policy": null
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The policy was not issued and the refund is being processed. Check Sales Status until txstatus is 2.
{
"status": "0",
"code": "IS23",
"message": "The policy could not be issued. Your refund is being processed.",
"data": {
"txstatus": 0,
"stage": "refund_pending",
"reference": "SALE-REFERENCE",
"transactionid": 123456789,
"externalref": "your-extid",
"accountnumber": "10XXXXXXXXXXXX",
"premium": "1250.00",
"charged": "1250.00",
"commission": "0.00",
"commission_status": null,
"refundid": null,
"provider_message": "Policy could not be created",
"policy": null
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}Nothing is charged. errors lists each invalid field by its path; data is the first one.
{
"status": "0",
"code": "IS06",
"message": "Check the policy details: Gender must be \"M\" or \"F\"",
"data": "policy.customer.gender",
"go": null,
"errors": {
"policy.customer.gender": "Gender must be \"M\" or \"F\"",
"policy.motor.vehregno": "Vehicle registration number is required"
},
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The premium is not the current price. Nothing is charged. Quote again and send that premium.
{
"status": "0",
"code": "IS10",
"message": "The premium does not match the current price (1250.00)",
"data": "premium",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The externalref was already used on this wallet. Nothing is charged and the original sale is not changed. The reply does not carry the original sale: look it up with Sales Status (idtype 1 and the externalref). It is HTTP 409 when you send X-Moolre-Http-Status: strict, otherwise 200.
{
"status": "0",
"code": "ASL08",
"message": "extid/externalref is required and must be unique.",
"data": "extid/externalref",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}The sale may have been charged. Check Sales Status with the externalref.
{
"status": "0",
"code": "IS30",
"message": "An unknown error occured, TRANSACTION MAY BE SUCCESSFUL, Please Check.",
"data": "all",
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}Fields every response can carry
On failures, read code, message and data (the first failing field). meta is always present and holds requestid (also the X-Request-Id header), notices and, only on idempotent replays, replayed. There is no outcome field: use status, code and data.txstatus. Send X-Moolre-Http-Status: strict to receive real HTTP status codes. See Responses and request IDs and Errors and status codes.
