# Sell Insurance API

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.

## Endpoint
- **Method**: POST
- **URL**: https://sandbox.moolre.com/open/sales/insurance

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| Content-Type | string | Yes | Send application/json. |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your Private API Key for the paying wallet. |
| Idempotency-Key | string | No | Optional. A repeat of the same request with the same key returns the first response instead of selling again. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | 1 sells a new motor policy; 2 renews an existing policy. |
| accountnumber | string | Yes | Your insurance agent wallet account number. It is charged the premium. |
| externalref | string | Yes | 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 | string | Yes | 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 | object | Yes | 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. |
| currency | string | No | Optional. Must be GHS when sent. |

## Response (200 Policy issued (IS20))
The policy was issued: txstatus 1, stage issued. The example values are illustrative.

```json
{
  "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": []
  }
}
```

## Response (200 Processing (IS21))
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.

```json
{
  "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": []
  }
}
```

## Response (200 In progress, no reply (ASL11))
The API got no readable answer within its time limit. The sale may still go through; it is reported as pending, never as failed.

```json
{
  "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": []
  }
}
```

## Response (200 Not issued, refunded (IS22))
The insurer refused the policy and the charge was refunded: txstatus 2. A new purchase is safe.

```json
{
  "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": []
  }
}
```

## Response (200 Not issued, refund pending (IS23))
The policy was not issued and the refund is being processed. Check Sales Status until txstatus is 2.

```json
{
  "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": []
  }
}
```

## Response (200 Invalid policy (IS06))
Nothing is charged. errors lists each invalid field by its path; data is the first one.

```json
{
  "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": []
  }
}
```

## Response (200 Premium differs (IS10))
The premium is not the current price. Nothing is charged. Quote again and send that premium.

```json
{
  "status": "0",
  "code": "IS10",
  "message": "The premium does not match the current price (1250.00)",
  "data": "premium",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Reference already used (ASL08))
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.

```json
{
  "status": "0",
  "code": "ASL08",
  "message": "extid/externalref is required and must be unique.",
  "data": "extid/externalref",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Response (200 Unknown error (IS30))
The sale may have been charged. Check Sales Status with the externalref.

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

## Before you begin

Insurance is sold from a wallet that Moolre has registered as an insurance sales agent (the Insurance sales product). Register it in the Moolre App by creating a Sell on Our Platform service, choosing the Insurance product and linking your GHS wallet, or contact Moolre Support to be set up. The accountnumber you send must be your own GHS wallet; any other wallet is refused. Insurance is sold in GHS only.

Call these endpoints from your server with your Moolre username as X-API-USER and your Private API Key as X-API-KEY: never put the private key in a browser or a mobile app. Quote, Vehicles, VIN lookup and Covers only read: nothing is charged and no externalref is needed. Only Sell Insurance charges the wallet.

## Before you sell

1. [List the covers](https://docs.moolre.com/api/sales/insurance/covers) to choose pol_type and cover_type.
2. [Find the vehicle](https://docs.moolre.com/api/sales/insurance/vin) from its VIN, or [search the vehicle list](https://docs.moolre.com/api/sales/insurance/vehicles), to get modelno, modeldesc, bodytype, engcc, tonnage and noseats.
3. [Quote the cover](https://docs.moolre.com/api/sales/insurance/quote) for the start date and seats and use its premium.
4. Send the purchase with a unique externalref.

## Premium

For a new policy, send the premium that Quote returns for the chosen cover, using the quote for the same start date as the policy commencement date (com_date, or today when it is in the past) and the same number of seats as policy.motor.noseats. The price is checked again before you are charged: when it differs by more than 0.01 the request is refused with IS10, nothing is charged, and the quote must be fetched again. For a renewal, send the renewal premium due; the amount you send is the amount charged.

## Money and commission

The wallet is charged the full premium. Moolre pays a 10% commission on an issued policy (new or renewal) to the same wallet as a separate credit, after the policy is issued. If the commission cannot be paid straight away it stays pending (commission_status pending) and is paid later; you do not need to do anything. A policy that is not issued earns no commission.

A purchase that is refused before charging (IS03 to IS17 and the ASL codes) charges nothing. When the insurer definitely refuses the policy the charge is refunded (IS22). If the refund cannot be made straight away the sale shows IS23 and the refund is retried; it is never marked failed in the meantime.

## Handle pending and uncertain results

IS21 and ASL11 mean the policy is still being confirmed with the insurer. They are not a failure and not an issued policy. The same applies when a request times out or returns ASL06 or IS30: the sale may still have gone through. Never resend the purchase with a new externalref. Check Sales Status with idtype 1 and the original externalref until txstatus is final: 1 means issued, and only 2 means the policy was not issued and the charge was refunded, so a new purchase is safe. txstatus 0 with stage refund_pending (IS23) means the policy was not issued and the refund is being processed.

## Repeating a purchase with the same externalref

An externalref is used once per wallet. A second purchase with an externalref the wallet has already used, by any sale, is refused with status 0 and code ASL08 (data names the field, extid/externalref), HTTP 409 with X-Moolre-Http-Status: strict and 200 otherwise. It is the same reply airtime and data give. Nothing is charged, nothing is sent to the insurer and the original sale is not changed. The reply does not contain the original sale: look it up with [Sales Status](https://docs.moolre.com/api/sales/status) (idtype 1 and the original externalref).

The check is on the externalref only. A repeat with a different premium, policy or type is refused with ASL08 as well, and never starts a second sale; a repeat whose premium or policy is malformed gets that field's own refusal (ASL16, ASL17, ASL09) first. A sale refused before it was charged (IS06, IS10 and the other refusals) leaves its externalref free. A refunded sale (IS22) leaves it used: sell again with a new externalref. In the rare case that two requests with the same externalref arrive almost together, the second can instead return the first sale's current state (code IS20, IS21, IS22 or IS23, with data.duplicate true), still without a second charge.

To let a safe retry return the first response, send an Idempotency-Key header: the same key with the same request returns the stored first response for 24 hours (marked replayed in meta), and the same key with a different request is refused with IDEM01.

## New motor policy (type 1)

Example request:

```json
{
  "type": 1,
  "accountnumber": "100000100002",
  "externalref": "your-extid",
  "premium": "1250.00",
  "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"
    }
  }
}
```

Policy fields (type 1):

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| policy.pol_type | string | Yes | Policy type from Covers, for example PRIVATE_INDIVIDUAL_X_1. |
| policy.cover_type | string | Yes | Cover type from Covers and Quote, for example third_party. |
| policy.com_date | string | Yes | Commencement date as DD/MM/YYYY. |
| policy.exp_date | string | Yes | Expiry date as DD/MM/YYYY, after com_date. |
| policy.sum_insured | number | Yes | Sum insured in GHS, above 0. |
| policy.benefits | array | No | Send an empty array. |
| policy.customer.nationality | string | Yes | Two letter country code, for example GH. |
| policy.customer.client_type | string | Yes | I for an individual or C for a commercial client. |
| policy.customer.gender | string | Yes | M or F. |
| policy.customer.first_name | string | Yes | First name. |
| policy.customer.last_name | string | Yes | Last name. |
| policy.customer.phone_number | string | Yes | Customer phone number, for example 0240000000. |
| policy.customer.ghana_card_no | string | Yes | Ghana Card number. |
| policy.customer.ghana_card_exp_date | string | Yes | Ghana Card expiry date as DD/MM/YYYY. |
| policy.customer.dob | string | Yes | Date of birth as DD/MM/YYYY. |
| policy.customer.digital_address | string | Yes | Ghana Post digital address. |
| policy.customer.occupation | string | No | Occupation. |
| policy.customer.post_code | string | No | Post code. |
| policy.customer.home_address | string | No | Home address. |
| policy.customer.post_address | string | No | Postal address. |
| policy.customer.email | string | No | Email address. An invalid address is left out rather than refused. |
| policy.motor.vehregno | string | Yes | Vehicle registration number. |
| policy.motor.yrmanuf | integer | Yes | Year of manufacture, from 1900 up to the current year. |
| policy.motor.color | string | Yes | Vehicle colour. |
| policy.motor.chasno | string | Yes | Chassis number. |
| policy.motor.certref | string | Yes | Certificate reference. |
| policy.motor.modelno | string | Yes | Model number, from Vehicles. |
| policy.motor.modeldesc | string | Yes | Model description, from Vehicles. |
| policy.motor.bodytype | string | Yes | Body type, from Vehicles. |
| policy.motor.engcc | integer | Yes | Engine capacity in cc, from Vehicles. |
| policy.motor.noseats | integer | Yes | Number of seats, from Vehicles. Use the same value as seats in Quote. |
| policy.motor.tariff | integer | Yes | Tariff code, a whole number above 0. |
| policy.motor.vehuse | integer | Yes | Vehicle use code, a whole number above 0. |
| policy.motor.vehregyear | string | Yes | Year the vehicle was registered. |
| policy.motor.engno | string | No | Engine number. |
| policy.motor.tonnage | string | No | Tonnage, from Vehicles when it applies. |
| policy.motor.is_ev | integer | No | 1 for an electric vehicle, otherwise 0. |

## Renewal (type 2)

Example request:

```json
{
  "type": 2,
  "accountnumber": "100000100002",
  "externalref": "your-renewal-extid",
  "premium": "1250.00",
  "currency": "GHS",
  "policy": {
    "pol_no": "POLICY-NUMBER",
    "payment_date": "01/12/2026"
  }
}
```

Policy fields (type 2):

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| policy.pol_no | string | Yes | Number of the policy to renew. |
| policy.payment_date | string | Yes | Payment date as DD/MM/YYYY. |
| policy.sum_insured | number | No | Sum insured in GHS, above 0. |
| policy.gender | string | No | M or F. |
| policy.dob | string | No | Date of birth as DD/MM/YYYY. |
| policy.phone_number | string | No | Customer phone number. |
| policy.email | string | No | Email address. |
| policy.occupation | string | No | Occupation. |
| policy.nationality | string | No | Two letter country code. |
| policy.ghana_card_no | string | No | Ghana Card number. |
| policy.ghana_card_exp_date | string | No | Ghana Card expiry date as DD/MM/YYYY. |

## Codes

Application codes, not HTTP status codes. ASL codes come from the API; codes starting IS come from the sales server and are returned unchanged. The ASL codes shared with airtime and data (ASL00, ASL03, ASL05, ASL06, ASL08 to ASL13) keep their meanings.

| Code | Meaning | Next step |
| --- | --- | --- |
| ASL00 | Authentication error. | Check X-API-USER and X-API-KEY. |
| ASL03 | Request incomplete. | Send type, accountnumber, externalref, premium and policy. |
| ASL05 | type invalid. | Send type 1 (new motor policy) or 2 (renewal). |
| ASL06 | Unknown error; the sale may still have been charged. | Check Sales Status with idtype 1 and the original externalref. Never resend with a new externalref. |
| ASL08 | externalref (or extid) is missing, longer than 128 characters, or already used on this wallet. | Send a unique externalref of at most 128 characters for each new sale. When it was already used nothing is charged and the earlier sale is not changed; the reply does not carry that sale, so look it up with Sales Status (idtype 1). HTTP 409 with X-Moolre-Http-Status: strict, otherwise 200. |
| ASL09 | Currency invalid: insurance is sold in GHS only. | Send currency GHS or leave it out. |
| ASL10 | The wallet is not a GHS wallet. | Sell from your GHS insurance agent wallet. |
| ASL11 | Insurance sale in progress: no readable reply from the sales server in time. | The sale may still go through. Check Sales Status with the original externalref. Do not resend. |
| ASL12 | The wallet is inactive. | Check the wallet with Moolre Support. |
| ASL13 | Account number not found or currency invalid. | Check accountnumber. |
| ASL16 | premium is required and must be an amount above 0.00. | Send the premium as a decimal amount in GHS with at most 2 decimals. |
| ASL17 | policy is required and must be an object. | Send policy as a JSON object with the fields for the type. |
| IS01 | Sales are temporarily unavailable, please try again in a few minutes. | Nothing was done or charged. Try again shortly with the same externalref. |
| IS02 | Not authorised. | accountnumber must be your own insurance agent wallet and the request must use your API user and key. |
| IS03 | Type must be 1 (new motor policy) or 2 (renewal). | Send type 1 or 2. |
| IS04 | extid is required (maximum 128 characters). | Send a unique externalref of at most 128 characters. |
| IS05 | A valid premium is required. | Send the premium as an amount above 0.00. |
| IS06 | Check the policy details. | data names the first field; errors lists every invalid field by its path, for example policy.customer.gender. Nothing is charged. |
| IS07 | This wallet is not registered as an insurance sales agent, or is not a GHS wallet. | Contact Moolre Support to register a GHS wallet. Nothing is charged. |
| IS08 | There is an issue with your agent setup, please contact support. | Contact Moolre Support. Nothing is charged. |
| IS09 | No price could be got from the insurer for this cover. | Ask again later. Nothing is charged. |
| IS10 | The premium does not match the current price. | The message states the current price. Get a fresh Quote and send that premium. Nothing is charged. |
| IS11 | Insurance sales are not available right now, please try again later. | Nothing is charged. Try again later. |
| IS12 | Your wallet is completing a transaction now, please try again in a moment. | Nothing is charged. Try again with the same externalref. |
| IS13 | Insufficient balance. | Fund the wallet with at least the premium. Nothing is charged. |
| IS14 | The insurance wallet is busy, please try again in a moment. | Nothing is charged. Try again with the same externalref. |
| IS15 | This extid has already been used on this wallet. Send the purchase again with a new extid. | The externalref belongs to another sale or transaction. Check it with Sales Status before using a new one. A repeat of your own sale is normally answered with ASL08 before it reaches this check. |
| IS16 | The same request is being processed in parallel. | Do not send it again. Check Sales Status with the externalref. |
| IS17 | The purchase could not be started, nothing was charged. | Try again later. |
| IS20 | Policy issued (status 1, txstatus 1). | Read data.policy for the policy number and document links. |
| IS21 | Policy processing (status 1, txstatus 0). | Not issued yet. Check Sales Status with the original externalref. Do not resend. |
| IS22 | Policy not issued, the charge was refunded (status 0, txstatus 2). | Read refundid. A new purchase is now safe, with a new externalref: the old one stays used (ASL08). |
| IS23 | Policy not issued, the refund is pending (status 0, txstatus 0). | Moolre is processing the refund. Check Sales Status; a new purchase is safe only once txstatus is 2. |
| IS30 | An unknown error occured, TRANSACTION MAY BE SUCCESSFUL, Please Check. | The purchase may have been charged. Check Sales Status with the original externalref. Never resubmit with a new one. |

## Fields every response can carry

These fields are additive: existing fields keep their names, order and types.

| Field | Meaning |
| :--- | :--- |
| meta | Always present, last in the object. meta.replayed is true only when the response is the stored answer to a repeated Idempotency-Key (absent otherwise). meta.requestid is the unique id of the request (also the X-Request-Id response header): quote it when you contact support. meta.notices is always an array, empty when there is nothing to report; each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See [Deprecations](https://docs.moolre.com/guides/deprecations). |

There is no outcome field. Decide the result from status, code and, on payment and transfer endpoints, data.txstatus (0 pending, 1 succeeded, 2 failed). These codes mean the result is unknown and may still succeed, so treat them as pending and check the status: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, IS30, SYS500. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.

Send X-Moolre-Http-Status: strict to receive real HTTP status codes (400, 401, 403, 404, 409, 422, 429, 5xx) instead of HTTP 200. See [Responses and request IDs](https://docs.moolre.com/guides/responses).
