Developer docs

Attach delivery rate

POST /escrow/:reference/delivery/attach — bind a quoted rate to a merchant escrow.

HTTP

POST https://www.harrenapay.com/api/public/v1/escrow/:reference/delivery/attach

Escrow must be yours (matched by API key + reference).
Sets delivery_mode to managed and creates a delivery_shipments row.
Carrier booking happens after the escrow is funded and the seller has accepted — use book / retry if needed.
Live keys only — hpay_test_ returns 403.
Delivery fee is recorded on the shipment; it is not added to the escrow amount.

Body

Field	Type	Notes
rate_id	string	From /delivery/rates.
carrier_name	string	Carrier display name from the rate.
delivery_fee_kobo	integer	Fee in kobo (≥ 0).
pickup_address_id	string	From rates response.
delivery_address_id	string	From rates response.
parcel_id	string	From rates response.
pickup_address	object	Full pickup address payload.
dropoff_address	object	Full dropoff address payload.

cURL

curl -X POST https://www.harrenapay.com/api/public/v1/escrow/order_4821/delivery/attach \
  -H "Authorization: Bearer hpay_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_id": "rate_…",
    "carrier_name": "GIG Logistics",
    "delivery_fee_kobo": 350000,
    "pickup_address_id": "…",
    "delivery_address_id": "…",
    "parcel_id": "…",
    "pickup_address": { "line1": "12 Marina", "city": "Lagos", "state": "Lagos" },
    "dropoff_address": { "line1": "4 Admiralty Way", "city": "Lekki", "state": "Lagos" }
  }'

200 response

JSON

{
  "ok": true,
  "delivery_shipment_id": "uuid",
  "tracking_number": null
}

tracking_number is set once booking succeeds (after fund + seller accept, or via retry).