Skip to content

Sell Insurance

POST
/open/sales/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.

history

Request History

Your request history will appear here.

Headers

X-API-USER stringrequired

Your Moolre username.

X-API-KEY stringrequired

Your Private API Key for the paying wallet.

Content-Type stringrequired

Send application/json.

Idempotency-Key stringoptional

Optional. A repeat of the same request with the same key returns the first response instead of selling again.

Body Params

typeintegerrequired

1 sells a new motor policy; 2 renews an existing policy.

accountnumberstringrequired

Your insurance agent wallet account number. It is charged the premium.

externalrefstringrequired

Your unique reference for this sale, at most 128 characters, unique per wallet. extid is accepted as an alternative field name; send only one.

premiumstringrequired

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.

policyobjectrequired

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.

currencystringoptional

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": []
  }
}
statusstring
1 for IS20 and also for IS21 and ASL11 (pending). Use data.txstatus to tell issued from pending.
codestring
IS20 issued.
data.txstatusinteger
0 pending, 1 issued, 2 not issued and refunded.
data.stagestring
awaiting_insurer, issued, refund_pending, refunded or needs_review.
data.referencestring
Moolre reference of the sale; use it as id with idtype 3.
data.transactionidinteger
Transaction ID of the charge; use it as id with idtype 2.
data.premium / data.chargedstring
Premium and amount charged to the wallet, equal.
data.commissionstring
Commission as a decimal string; 0.00 until the policy is issued.
data.commission_statusstring or null
paid or pending once issued; null before.
data.refundidinteger or null
Refund transaction ID when refunded.
data.provider_messagestring
The insurer message for the sale.
data.policyobject or null
Once issued: pol_no, certificate_url, sticker_no, sticker_url and brown_card_url, plus other details from the insurer.

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.

Language

curl --request POST \     --url 'https://api.moolre.com/open/sales/insurance' \     --header 'X-API-USER: Your Username' \     --header 'X-API-KEY: YOUR_API_KEY' \     --header 'Content-Type: application/json' \     --data '{  "type": 1,  "accountnumber": "",  "externalref": "",  "premium": "",  "currency": "GHS",  "policy": {    "pol_type": "PRIVATE_INDIVIDUAL_X_1",    "cover_type": "third_party",    "com_date": "01/12/2026",    "exp_date": "30/11/2027",    "sum_insured": 200000,    "benefits": [],    "customer": {      "nationality": "GH",      "client_type": "I",      "gender": "M",      "first_name": "Kwame",      "last_name": "Mensah",      "phone_number": "0240000000",      "ghana_card_no": "GHA-000000000-0",      "ghana_card_exp_date": "01/01/2030",      "occupation": "Trader",      "dob": "01/01/1990",      "post_code": "",      "home_address": "12 Example Street, Accra",      "post_address": "P.O. Box 1, Accra",      "digital_address": "GA-000-0000",      "email": "kwame@example.com"    },    "motor": {      "vehregno": "GR-1234-26",      "yrmanuf": 2020,      "color": "WHITE",      "chasno": "CHASSIS000000001",      "engno": "",      "tariff": 1,      "certref": "CERT-0001",      "vehuse": 1,      "modelno": "1234",      "modeldesc": "TOYOTA COROLLA",      "bodytype": "SALOON",      "engcc": 1600,      "tonnage": "",      "noseats": 5,      "is_ev": 0,      "vehregyear": "2020"    }  }}'

Response

Body

{  "status": "0",  "code": "IS30",  "message": "An unknown error occured, TRANSACTION MAY BE SUCCESSFUL, Please Check.",  "data": "all",  "go": null,  "meta": {    "requestid": "req_c68f4c66115c26725c796242",    "notices": []  }}