> For new integrations, EasyParcel recommends the NextGen API: https://developer.easyparcel.com/

# Purchase Insurance

> EasyParcel API · Malaysia · MarketPlace · version 1.4.0.0
> Page: https://developers.easyparcel.com/my/marketplace/purchase-insurance · Markdown: https://developers.easyparcel.com/my/marketplace/purchase-insurance.md · PDF: https://developers.easyparcel.com/pdf/Malaysia_MarketPlace_1.4.0.0.pdf

This step involves both ordering and making payments for the orders placed. Authenticated users can make single insurance order payments. Single order payment specifically refers to the payment for a single parcel. Various payment conditions may arise, such as insufficient credit (when the user account lacks sufficient funds for payment) or sufficient credit (when there are adequate funds available for payment).

## Endpoint

- Method: `POST`
- Demo URL: `https://demo.connect.easyparcel.my/?ac=EPInsurancePurchase`
- Live URL: `https://connect.easyparcel.my/?ac=EPInsurancePurchase`
- Body: `application/x-www-form-urlencoded`. Nested fields use PHP `http_build_query` names, e.g. `bulk[0][pick_code]`.
- Action: `EPInsurancePurchase`

## Request parameters

### Request L1

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `api` | string(25) | Yes | Obtain from a registered account. |
| `awb` | string(25) | Yes | The Air Waybill (AWB) number. |
| `parcel_content_value` | double(8,2) | Yes | The declared value of the parcel content. |
| `courier` | string(25) | Yes | Shipment courier. (Refer to [Appendix IV](https://developers.easyparcel.com/my/marketplace/appendix/insurance-courier-list.md)) |
| `coll_country` | string(2) | Yes | The country code of the collection address, limited to 'MY' or 'SG'. |
| `deli_country` | string(2) | Yes | Receiver country code.Refer to ISO 3166-2 |
| `coll_state` | string(35) | Yes | Sender’s state. (Refer to [Appendix III](https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md)) |
| `deli_state` | string(35) | Yes | Receiver state. |
| `parcel_category_id` | int(2) | Yes | The parcel category id (Refer to Get Parcel Category API) |
| `parcel_content` | string(35) | Yes | The content of the parcel. |
| `parcel_content_type` | string(8) | Yes | The type of parcel content, limited to 'document' or 'parcel'. |
| `parcel_content_currency_code` | string(3) | Yes | The currency code of the parcel content. |
| `parcel_content_weight` | double(8,2) | Yes | The weight of the parcel content. |
| `coll_name` | string(35) | Yes | Sender name. |
| `coll_company` | string(35) | No | Sender company |
| `coll_mobile_code` | string(2) | Yes | Sender mobile country mobile , eg: 60 |
| `coll_mobile` | string(16) | Yes | Sender mobile number |
| `coll_alternative_mobile_code` | string(2) | No | Sender alternative mobile country mobile , eg: 60 |
| `coll_alternative_mobile` | string(16) | No | Sender  alternative mobile number |
| `coll_email` | string(35) | No | Sender email |
| `deli_name` | string(35) | Yes | Receiver name. |
| `deli_company` | string(35) | No | Receiver company name. |
| `deli_mobile_code` | string(2) | Yes | Receiver mobile country mobile , eg: 60 |
| `deli_mobile` | string(35) | Yes | Receiver mobile number. |
| `deli_alternative_mobile_code` | string(2) | No | Receiver alternative mobile country mobile , eg: 60 |
| `deli_alternative_mobile` | string(35) | No | Receiver alternative mobile number. |
| `deli_email` | string(35) | No | Receiver email address. |
| `coll_address_1` | string(35) | Yes | Sender's address line 1. |
| `coll_address_2` | string(35) | No | Sender's address line 2. |
| `coll_postcode` | string(10) | Yes | Sender's postcode. |
| `coll_city` | string(35) | Yes | Sender city |
| `deli_address_1` | string(35) | Yes | Receiver address line 1. |
| `deli_address_2` | string(35) | No | Receiver address line 2. |
| `deli_postcode` | string(10) | Yes | Receiver  postcode. |
| `deli_city` | string(35) | Yes | Receiver city.. |
| `shipment_date` | date | Yes | The date of the shipment in the format YYYY-MM-DD. |

## Sample code

### PHP

```php
<?php
$domain = "http://demo.connect.easyparcel.my/?ac=";

$action = "EPInsurancePurchase";
$postparam = array(
    'api' => 'xxxxxx',
    'awb' => 'TESTDomestic',
    'parcel_content_value' => '250',
    'courier' => 'EP-CR05',
    'coll_country' => 'MY',
    'deli_country' => 'MY',
    'coll_state' => 'png',
    'deli_state' => 'png',
    'parcel_category_id' => '12',
    'parcel_content' => 'testing',
    'parcel_content_type' => 'parcel',
    'parcel_content_currency_code' => 'MYR',
    'parcel_content_weight' => '123',
    'coll_name' => '12313',
    'coll_company' => 'Testing Company',
    'coll_mobile_code' => '60',
    'coll_mobile' => '162631234',
    'coll_alternative_mobile_code' => '60',
    'coll_alternative_mobile' => '123456789',
    'coll_email' => 'test@easyparcel.com',
    'deli_name' => 'Receiver Testing',
    'deli_company' => 'Receiver Testing Company',
    'deli_mobile_code' => '60',
    'deli_mobile' => '123456789',
    'deli_alternative_mobile_code' => '',
    'deli_alternative_mobile' => '',
    'deli_email' => 'receiver@easyparcel.com',
    'coll_address_1' => 'testing',
    'coll_address_2' => 'testing 2',
    'coll_postcode' => '11950',
    'coll_city' => 'penang',
    'deli_address_1' => 'test receiver',
    'deli_address_2' => 'test receiver 2',
    'deli_postcode' => '11950',
    'deli_city' => 'penang',
    'shipment_date' => '2024-05-11',
);

$url = $domain.$action;
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postparam));
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

ob_start();
$return = curl_exec($ch);
ob_end_clean();
curl_close($ch);

$json = json_decode($return);
echo "<pre>"; print_r($json); echo "</pre>";
?>
```

### cURL

```bash
curl -X POST 'http://demo.connect.easyparcel.my/?ac=EPInsurancePurchase' \
  --data-urlencode 'api=xxxxxx' \
  --data-urlencode 'awb=TESTDomestic' \
  --data-urlencode 'parcel_content_value=250' \
  --data-urlencode 'courier=EP-CR05' \
  --data-urlencode 'coll_country=MY' \
  --data-urlencode 'deli_country=MY' \
  --data-urlencode 'coll_state=png' \
  --data-urlencode 'deli_state=png' \
  --data-urlencode 'parcel_category_id=12' \
  --data-urlencode 'parcel_content=testing' \
  --data-urlencode 'parcel_content_type=parcel' \
  --data-urlencode 'parcel_content_currency_code=MYR' \
  --data-urlencode 'parcel_content_weight=123' \
  --data-urlencode 'coll_name=12313' \
  --data-urlencode 'coll_company=Testing Company' \
  --data-urlencode 'coll_mobile_code=60' \
  --data-urlencode 'coll_mobile=162631234' \
  --data-urlencode 'coll_alternative_mobile_code=60' \
  --data-urlencode 'coll_alternative_mobile=123456789' \
  --data-urlencode 'coll_email=test@easyparcel.com' \
  --data-urlencode 'deli_name=Receiver Testing' \
  --data-urlencode 'deli_company=Receiver Testing Company' \
  --data-urlencode 'deli_mobile_code=60' \
  --data-urlencode 'deli_mobile=123456789' \
  --data-urlencode 'deli_alternative_mobile_code=' \
  --data-urlencode 'deli_alternative_mobile=' \
  --data-urlencode 'deli_email=receiver@easyparcel.com' \
  --data-urlencode 'coll_address_1=testing' \
  --data-urlencode 'coll_address_2=testing 2' \
  --data-urlencode 'coll_postcode=11950' \
  --data-urlencode 'coll_city=penang' \
  --data-urlencode 'deli_address_1=test receiver' \
  --data-urlencode 'deli_address_2=test receiver 2' \
  --data-urlencode 'deli_postcode=11950' \
  --data-urlencode 'deli_city=penang' \
  --data-urlencode 'shipment_date=2024-05-11'
```

## Response

### Response L1

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `result` | array | Result for Purchase Insurance |  |
| `status` | string(7) | Get rate status is Success / Fail |  |
| `error_code` | int(5) | Error Code | Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md) |
| `error_remark` | string(100) | Error Message | Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md) |
| `error_detail` | object | Error Details | Only show detail when error code under 1001 |
| `api_status` | string(10) | API Validation result | Refer to [Appendix I](https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md) |

### Response L2

| Field | Type | Description | Remarks |
| --- | --- | --- | --- |
| `email` | string(35) | The email address of the login email. |  |
| `name` | string(35) | The name of the sender. |  |
| `payment_number` | string(10) | The payment reference number associated with the transaction. |  |
| `insurance_amount` | decimal(8,2) | The quoted amount for insurance coverage. |  |
| `parcel_content_value` | decimal(8,2) | The declared value of the parcel content. |  |
| `awb` | string(25) | The Air Waybill (AWB) number provided for tracking purposes. |  |
| `shipment_date` | date | The date of shipment for the parcel. |  |
| `deli_name` | string(35) | Receiver name. |  |
| `parcel_content` | string(35) | Description or contents of the parcel. |  |
| `amount` | decimal(8,2) | The total amount associated with the transaction. |  |
| `send_email_status` | string(100) | The status indicates whether the email notification has been sent. |  |

## Response samples

### Success

```json
{
  "result":{
    "email":"test@easyparcel.com",
    "name":"12313",
    "payment_number":"EC-HXELB",
    "insurance_amount":6.25,
    "parcel_content_value":"250",
    "awb":"TESTDomestic",
    "shipment_date":"2024-05-11T00:00:00.000Z",
    "deli_name":"Receiver Testing",
    "parcel_content":"testing",
    "amount":6.25,
    "send_email_status":"email sent"
  },
  "status":"Success",
  "error_code":0,
  "error_remark":"",
  "error_detail":"",
  "api_status":"Success"
}
```

### Fail

```json
{
  "result":[
    
  ],
  "status":"",
  "error_code":"3",
  "error_remark":"Required api key",
  "api_status":"Error"
}
```

## Referenced appendices

Copied from the appendix pages linked above.

### Appendix IV: Insurance Courier List

Source: https://developers.easyparcel.com/my/marketplace/appendix/insurance-courier-list.md

| Courier | Courier Name |
| --- | --- |
| EP-CR0H | KEX Express |
| EP-CR01 | UTS |
| EP-CR03 | Aramex |
| EP-CR05 | Skynet |
| EP-CR0C | DHLeC |
| EP-CR0DS | Flash Express |
| EP-CR0A | Pos Laju |
| EP-CR0DP | J&T Express |
| EP-CR0DK | Pickupp |
| EP-CR0DU | Ninjavan |
| EP-CR0D3 | J&T Cargo |
| EP-CR0U | TNT |
| EP-CR0DH | Best Express |
| EP-CR0D1 | City-Link Express |
| EP-CR0T | FedEx |
| EP-CR06 | Aramex International |

### Appendix III: State Code List

Source: https://developers.easyparcel.com/my/marketplace/appendix/state-code-list.md

| Short State Name | Full State Name |
| --- | --- |
| jhr | Johor |
| kdh | Kedah |
| ktn | Kelantan |
| mlk | Melaka |
| nsn | Negeri Sembilan |
| phg | Pahang |
| prk | Perak |
| pls | Perlis |
| png | Pulau Pinang |
| sgr | Selangor |
| trg | Terengganu |
| kul | Kuala Lumpur |
| pjy | Putra Jaya |
| srw | Sarawak |
| sbh | Sabah |
| lbn | Labuan |

### Appendix I: API Return Status

Source: https://developers.easyparcel.com/my/marketplace/appendix/api-return-status.md

| api_status | error_code | error_remark | Explanation |
| --- | --- | --- | --- |
| Success | 0 |  |  |
| Error | 1 | Required authentication key | Missing authentication param |
| Error | 2 | Invalid authentication key |  |
| Error | 3 | Required api key | Missing API key param |
| Error | 4 | Invalid api key |  |
| Error | 5 | Unauthorized user | Invalid API key |
| Error | 6 | Required bulk array |  |
| Error | 7 | Required bulk data insert format in array |  |
| Error | 8 | Invalid account |  |
| Error | 9 | Unverified account. Please kindly verify your account at easyparcel.com |  |
| Error | 1000 | Missing / Invalid Parameter | If a required parameter is missing or an invalid value is entered, the error will be displayed in the error_detail field. |
| Error | 1002 | Invalid User Account | The user does not have a wallet associated with the relevant country. |
| Error | 1003 | Invalid parcel category, you should refer to Get Parcel Category API | Invalid parcel category, you should refer to Get Parcel Category API |
| Error | 1004 | Invalid collection/ delivery postcode |  |
| Error | 1005 | Invalid collection/delivery state | If the value is "Pulau Penang," an error will occur because our system only accepts state codes. |
| Error | 1006 | Invalid courier | Incorrect Courier code |
| Error | 3001 | Shipment insured | This tracking number has previously purchased insurance through EasyParcel, cannot buy insurance again |
| Error | 3002 | Shipment delivered | The status of this tracking number shipment is "delivered", not allow to buy insurance |
| Error | 3003 | Not under claim coverage | The courier insurance provides coverage for parcel contents up to RM200. However, since you entered a parcel content value of RM100, it does not qualify for claim coverage. |
| Error | 3004 | Only support international/domestic shipment | For example, Fedex only supports international shipments to buy insurance |
| Error | 3005 | No Cover | If the collection state or delivery location is not within the insurance coverage area, an error message along with a description will be displayed. |
| Error | 9999 | Unknown error | If this error occurs, please contact our support team for assistance. |

Support: WhatsApp EasyParcel API Support — https://api.whatsapp.com/send/?phone=6042023160

Published by EasyParcel Sdn Bhd (1028666-H).
