Product Delivery

📘
In order to initiate a product delivery request, regardless of the payment channel, you will just apply some modifications to the essential steps mentioned in the payment API flow guide.

1. Order Registration Request:

The request will be the same the normal request mentioned in payment API flow guide, except:

adding the "delivery_needed" key to be "true".
adding the "shipping_data" object to your request.
adding the "shipping_details" object to your request.

Your order registration request should look like this one:

{
    "auth_token": "ZXlKaGlPaUpJVXpVeE1pSX1Y0NJmV5Sn...", // auth token obtained from step1
  "delivery_needed": "false",
  "merchant_id": "28",      // merchant_id obtained from step 1
  "amount_cents": "100",
  "currency": "EGP",
  "merchant_order_id": 5,
    "shipping_data": {
        "apartment": "1", 
        "email": "[email protected]", 
        "floor": "4", 
        "first_name": "customer_name",
        "street": "Test", 
        "building": "testing", 
        "phone_number": "01234567",
        "shipping_method": "PKG", 
        "postal_code": "01898", 
        "city": "New Cairo", 
        "country": "Egypt",
        "last_name": "customer_name", 
        "state": "Cairo"
    },
  "shipping_details": {
        "notes" : " test",
        "number_of_packages": 1,
        "weight" : 1,
        "weight_unit" : "Kilogram",
        "length" : 1,
        "width" :1,
        "height" :1,
        "contents" : "product of some sorts"
    },
}

field	Description	Type	Required
auth_token	Authentication token, which is valid for one hour from the creation time.	string	Yes
delivery_needed	This boolean indicates whether delivery is needed or not.	bool	Yes
amount_cents	The amount value of the order to be created.	string( int )	Yes
currency	The currency the order will be displayed in.	string (currency)	Yes
items	A list object to populate more than one product or service within one order (currently not supported for delivery).	list( {key: value} )	Yes, ( can be passed as empty list )
shipping_data	The location the delivery will be made to.	JSON	Yes (for delivery)
shipping_details	The package details that will be shipped.	JSON	Yes

Sample Response:

{
    "id": 296,
    "created_at": "2019-04-14T20:13:27.940682",
    "delivery_needed": "true",
    "merchant": {
        "id": 1,
        "created_at": "2019-03-25T14:54:02.917413",
        "phones": [
            "0123456789"
        ],
        "company_emails": [
            "[email protected]"
        ],
        "company_name": "test1",
        "state": "",
        "country": "EGY",
        "city": "",
        "postal_code": "",
        "street": ""
    },
    "collector": {
        "id": 1,
        "created_at": "2019-03-25T14:53:20.861373",
        "phones": [],
        "company_emails": [],
        "company_name": "logix",
        "state": "Heliopolis",
        "country": "egypt",
        "city": "cairo",
        "postal_code": "123456",
        "street": "Marghany"
    },
    "amount_cents": 1000,
    "shipping_data": {
        "id": 272,
        "first_name": "customer_name",
        "last_name": "customer_name",
        "street": "Test",
        "building": "testing",
        "floor": "4",
        "apartment": "1",
        "city": "New Cairo",
        "state": "Cairo",
        "country": "Egypt",
        "email": "[email protected]",
        "phone_number": "01234567",
        "postal_code": "01898",
        "extra_description": " ",
        "shipping_method": "PKG",
        "order_id": 296,
        "company_name": "",
        "order": 296
    },
    "shipping_details": {
        "id": 217,
        "cash_on_delivery_amount": 0,
        "cash_on_delivery_type": "",
        "latitude": "null",
        "longitude": "null",
        "is_same_day": 0,
        "number_of_packages": 1,
        "weight": "null",
        "weight_unit": "null",
        "length": "null",
        "width": "null",
        "height": "null",
        "delivery_type": "PUD",
        "return_type": "null",
        "order_id": 296,
        "contents": "",
        "notes": "",
        "package_type": "YP",
        "order": 296
    },
    "currency": "EGP",
    "is_payment_locked": "false",
    "is_return": "false",
    "is_cancel": "false",
    "is_returned": "false",
    "is_canceled": "false",
    "merchant_order_id": "null",
    "wallet_notification": "null",
    "paid_amount_cents": 0,
    "notify_user_with_email": "false",
    "items": [],
    "order_url": "https://accept.paymobsolutions.com/i/cP",
    "commission_fees": 0,
    "delivery_fees_cents": 2200,
    "delivery_vat_cents": 4,
    "payment_method": "tbc",
    "merchant_staff_tag": "null",
    "api_source": "OTHER",
    "pickup_data": "null",
    "pickup_within_days": "null",
    "token": "cP",
    "url": "https://accept.paymobsolutions.com/i/cP"
}

👍
Now, continue your integration flow as mentioned in the payment API flow guide.
Then add the following API calls to your integration flow.

Tracking

Now Assuming the payment was successful the delivery will be automatically scheduled from the contracted location of pickup to the shipping_data provided in the order creation. Accept Delivery APIs provide an API for tracking the status of the order (status updates times vary depending on collector).

To Access the API a request is sent with to collect the status of the delivery using the below URL format:

URL: https://accept.paymob.com/api/ecommerce/orders/{order_id}/delivery_status

method: GET

content-type: QUERY PARAMS

Headers: Authorization ==> Bearer {token}

Replacing the {order_id} in the URL with the actual order id and the {token} with the actual access token. The expected statuses of return can be one of the following:

Status	Meaning/Description
Scheduled	The order has been scheduled for pickup.
Contacting Merchant	The collector is contacting the merchant to validate pickup details.
Picking Up	The order is being picked up at the merchant pickup location.
Courier Received	The order has been picked by the courier and is en route to the warehouse for distribution.
At Warehouse	The order is at the warehouse for sorting.
Agent Out	The order is out of the warehouse.
On Route	The order is en route to the shipping location.
At Customer	The delivery agent is at the customer.
Delivery Failed	The delivery agent failed to reach the customer ( not available ).
Delivered	The order has been delivered to the customer successfully.
Canceled	the order has been canceled by the customer ( customer refused to accept the package ).
Return Scheduled	The order has been scheduled to be returned to the merchant.
Package Returned	The order has been returned to the merchant.
Delayed	The order has been delayed due to unforeseen circumstances.
Damaged	The order has been damaged on the way.
On Hold	the order is on hold by an authoritative figure ( customs, police, shipping authority)
Held For Payment	the order is on hold by authoritative figure awaiting payment ( customs, police, shipping authority)

This will return the following response:

[
    {
        "order": 314,
        "merchant": 1,
        "collector": 1,
        "created_at": "2019-04-15T15:29:10.985520",
        "status": "Scheduled",
        "extra_description": "2019-04-15 15:29:09.644444: Data Received\n",
        "gps_long": "null",
        "gps_lat": "null",
        "id": 31,
        "callback_responses": []
    }
]

Preparing your package for Delivery

To be compliant with collector regulations for shipping, some preparation has to be applied to the package:

Packaging: as agreed on with collector
AirwayBill: to be attached to the package during shipping, and to be handed to the collector agent on pickup

URL: https://accept.paymob.com/api/ecommerce/orders/{order_id}/airway_bill

method: GET

content-type: QUERY PARAMS

Headers: Authorization ==> Bearer {token}

Replacing the {order_id} in the URL with the actual order id and the {token} with the actual access token. This will return a pdf file to be printed.