Add Sendam delivery to your checkout.

1. 1

   Step 1: Get a key

   Open Integrations in the business dashboard and create a secret key. It is shown once, so save it in your server’s environment straight away. A business can hold up to five active keys, and revoking one takes effect at once.

   To try the API this minute, use the public sandbox key sk_test_sendam_demo_4f9a2c7e1b8d3f60. This call checks that a key works: a 200 with a list means yes, a 401 means no.

   curl · check your keyCopy

   curl "https://YOUR-SENDAM-DOMAIN/api/v1/shipments?limit=1" \
     -H "Authorization: Bearer sk_test_sendam_demo_4f9a2c7e1b8d3f60"
   

2. 2

   Step 2: Quote the delivery

   Send the drop-off and you get the price your wallet will be charged, VAT included. pickup is optional and defaults to your saved shop address. Show total and delivery_window at checkout.

   curl · POST /quotesCopy

   curl https://YOUR-SENDAM-DOMAIN/api/v1/quotes \
     -H "Authorization: Bearer sk_test_sendam_demo_4f9a2c7e1b8d3f60" \
     -H "Content-Type: application/json" \
     -d '{
       "dropoff": { "lat": 6.447, "lng": 3.473 },
       "parcel": { "size": "small" }
     }'
   

   Response200Copy

   {
     "object": "quote",
     "currency": "NGN",
     "total": 4550,
     "vat": 300,
     "delivery_fee": 4250,
     "protection_fee": 0,
     "discount": 450,
     "distance_km": 17.7,
     "eta_minutes": 89,
     "delivery_window": "Tomorrow, 9am – 1pm",
     "vehicle": "bike",
     "express": false,
     "crosses_bridge": true,
     "wallet_balance": 41400
   }
   

3. 3

   Step 3: Create the shipment

   When the order is paid on your side, book the rider. The delivery fee is debited from your prepaid wallet and the shipment joins the dispatch queue. Always send an Idempotency-Key, so a retry can never book two riders.

   curlNode.jsPHP

   Copy

   curl https://YOUR-SENDAM-DOMAIN/api/v1/shipments \
     -H "Authorization: Bearer sk_test_sendam_demo_4f9a2c7e1b8d3f60" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "reference": "ORDER-10492",
       "dropoff": {
         "name": "Ngozi Nwosu",
         "phone": "08031234567",
         "landmark": "Opposite Mega Chicken, yellow gate",
         "street": "14 Admiralty Way",
         "area": "Lekki Phase 1",
         "lat": 6.447,
         "lng": 3.473
       },
       "parcel": {
         "description": "2 Ankara gowns",
         "size": "small",
         "declared_value": 35000
       }
     }'
   

   Response201Copy

   {
     "id": "SND-V7EGM",
     "object": "shipment",
     "reference": "ORDER-10492",
     "status": "ready",
     "status_label": "Finding a rider",
     "city": "lagos",
     "vehicle": "bike",
     "express": false,
     // pickup: your saved shop address, because none was sent
     "dropoff": {
       "name": "Ngozi Nwosu",
       "phone": "08031234567",
       "landmark": "Opposite Mega Chicken, yellow gate",
       "street": "14 Admiralty Way",
       "area": "Lekki Phase 1",
       "lat": 6.447,
       "lng": 3.473,
       "notes": null
     },
     "parcel": { "description": "2 Ankara gowns", "size": "small", "declared_value": 35000, "protection": false },
     "price": { "currency": "NGN", "total": 4550, "vat": 300, "delivery_fee": 4250, "protection_fee": 0, "discount": 450 },
     "distance_km": 17.7,
     "delivery_window": "Tomorrow, 9am – 1pm",
     "see_am_first": null,
     "rider": null,
     "eta_minutes": null,
     "failure_reason": null,
     "tracking_url": "https://YOUR-SENDAM-DOMAIN/track/SND-V7EGM",
     "buyer_confirmation_url": null,
     "events": [
       { "status": "awaiting_payment", "at": "2026-11-10T22:40:02.154Z", "note": "Order created" },
       { "status": "ready", "at": "2026-11-10T22:40:02.154Z", "note": "Paid from wallet" }
     ],
     "created_at": "2026-11-10T22:40:02.154Z",
     "updated_at": "2026-11-10T22:40:02.154Z"
   }
   

   That is the whole integration. Save id against your order, send your customer the tracking_url (a public live-map page), and either poll GET /shipments/{id} or let webhooks tell you when the status changes.

awaiting_confirmationWaiting for buyer

Paid, and waiting for the receiver to confirm their pin (and to pay the item price, for See Am First). Only happens when you send buyer_confirms_address or see_am_first. buyer_confirmation_url is set while the shipment is here.

readyFinding a rider

Paid and confirmed. In the dispatch queue, waiting for a rider to accept.

assignedRider on the way to pickup

A rider has accepted and is heading to the pickup. rider and eta_minutes are now filled in. This is the last status you can cancel from.

at_pickupRider at pickup

The rider is at the pickup address.

picked_upPicked up

The parcel has been scanned and photographed, and is on its way.

arrivingArriving soon

The rider is about five minutes from the door.

deliveredDelivered

The receiver’s 4-digit delivery code matched. Final. With See Am First, this is the moment the money is released to you.

failedDelivery attempt failed

The delivery attempt did not succeed; failure_reason says why. Any See Am First payment is refunded to the buyer, the parcel heads back to you, and a return fee of 50% of the delivery fee is charged to your wallet.

returnedReturned to sender

A failed parcel is back with the sender. Final.

cancelledCancelled

Cancelled before pickup. Final. The delivery fee is back in your wallet.

The pill beside each status is its status_label, which you can show to customers as it is. The first entry in events is always awaiting_payment (“Order created”). API shipments are paid from your wallet in the same instant, so they never rest there, and no webhook is sent for it. Orders booked in the dashboard for the buyer to pay can show it in the list endpoint.

curl https://YOUR-SENDAM-DOMAIN/api/v1/shipments \
  -H "Authorization: Bearer sk_test_sendam_demo_4f9a2c7e1b8d3f60" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "reference": "ORDER-10493",
    "dropoff": {
      "name": "Ngozi Nwosu",
      "phone": "08031234567",
      "place_id": "lekki-admiralty",
      "landmark": "Opposite Mega Chicken, yellow gate"
    },
    "parcel": { "description": "2 Ankara gowns", "size": "small" },
    "see_am_first": { "item_price": 35000 }
  }'

{
  "id": "SND-ASFEZ",
  "object": "shipment",
  "reference": "ORDER-10493",
  "status": "awaiting_confirmation",
  "status_label": "Waiting for buyer",
  "parcel": { "description": "2 Ankara gowns", "size": "small", "declared_value": 35000, "protection": false },
  "price": { "currency": "NGN", "total": 4550, "vat": 300, "delivery_fee": 4250, "protection_fee": 0, "discount": 450 },
  "see_am_first": { "item_price": 35000, "fee": 550, "status": "pending" },
  "tracking_url": "https://YOUR-SENDAM-DOMAIN/track/SND-ASFEZ",
  "buyer_confirmation_url": "https://YOUR-SENDAM-DOMAIN/confirm/SND-ASFEZ"
  // …other shipment fields
}

• The fee is 1.5% of the item price, at least ₦100 and capped at ₦2,000. It is taken from the payout when the money is released, never upfront. On ₦35,000 the fee is ₦550, so ₦34,450 reaches your sales balance.
• The buyer always confirms their address on a See Am First shipment, whether or not you send buyer_confirms_address. parcel.declared_value is set to the item price.
• Cancel before pickup and a buyer who has already paid is refunded automatically.
• In this sandbox no WhatsApp message is actually sent. Open buyer_confirmation_url yourself to play the buyer, and the shipment carries on from there.

POST /webhooks/sendam HTTP/1.1
Content-Type: application/json
User-Agent: Sendam-Webhooks/1.0
X-Sendam-Event: shipment.delivered
X-Sendam-Delivery: evt_<event id>
X-Sendam-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

{
  "id": "evt_<event id>",
  "type": "shipment.delivered",
  "created_at": "2026-11-10T22:46:05.861Z",
  "data": {
    "id": "SND-V7EGM",
    "object": "shipment",
    "reference": "ORDER-10492",
    "status": "delivered",
    "status_label": "Delivered"
    // …the full shipment object, exactly as GET /shipments/{id} returns it
  }
}

Event types

shipment.<status>

Every status change, one type per status: shipment.ready, shipment.assigned, shipment.delivered, shipment.cancelled and so on.

escrow.released

A See Am First buyer accepted the item and their code released the money to you. Sent alongside shipment.delivered.

escrow.refunded

A See Am First payment went back to the buyer, because the delivery failed or the shipment was cancelled after they had paid.

ping

You pressed “Send test event” on the Integrations page. data is a short message, not a shipment.

For shipment and escrow events, data is the full shipment object as it stood when the event was created.

Verify the signature

Anyone can POST to a public URL, so check every event really came from Sendam. Take t and v1 from X-Sendam-Signature, compute an HMAC-SHA256 of <t>.<raw body> with your signing secret, and compare the hex result with v1. Use the raw request body, byte for byte, before any JSON parsing.

import crypto from "node:crypto";
import express from "express";

const app = express();

// The signature covers the raw bytes, so use express.raw() on this route, not express.json().
app.post("/webhooks/sendam", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Sendam-Signature") ?? "";
  const { t, v1 = "" } = Object.fromEntries(header.split(",").map((part) => part.split("=")));

  const expected = crypto
    .createHmac("sha256", process.env.SENDAM_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest("hex");

  const valid = v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300; // ignore anything older than 5 minutes
  if (!valid || !fresh) return res.status(400).send("Bad signature");

  const event = JSON.parse(req.body);
  // event.id is also in X-Sendam-Delivery: store it and skip ids you have already handled.
  if (event.type === "shipment.delivered") {
    // mark the order with reference event.data.reference as delivered
  }

  res.sendStatus(204); // answer first, do slow work in a queue
});

app.listen(3000);

• Answer within 8 seconds

  Return any 2xx status. We stop waiting after 8 seconds and mark the delivery as failed, so acknowledge first and do slow work in a queue.

• Treat webhooks as a nudge

  In this build each event is attempted once, and a failure shows in the delivery log. If you miss one, GET /shipments/{id} always has the truth.

• Handle each event once

  The event id is repeated in X-Sendam-Delivery. Store the ids you have processed and skip any you see again.

• Do not rely on order

  Events for quick successive changes can arrive close together or out of order. Trust data.status and data.events, not arrival order.

Webhook URLs must use https://. Plain http:// is accepted only for localhost and 127.0.0.1 while you develop.

• Send an Idempotency-Key header on every POST /shipments. Your own order number is ideal. Keys are scoped to your business.
• A repeat returns the first shipment. The same key gives you back the shipment that was already created, in its current state, and your wallet is not charged again. The body of the repeat is not compared, so use a new key for a genuinely new shipment.
• A key is only used up by a success. If the first attempt failed with validation_failed or insufficient_balance, fix the problem and retry with the same key.
• Retry on timeouts, network errors and 5xx, with the same key and a growing pause between attempts. Do not retry other 4xx responses unchanged; they will fail the same way.
• Everything else is naturally safe. Quotes and reads change nothing, and cancelling twice returns the same cancelled shipment. To double-check an order, look it up with GET /shipments?reference=….

• Coming soon

  Shopify

  Sendam rates at checkout and a shipment booked when an order is paid.

• Coming soon

  WooCommerce

  A WordPress plugin that adds Sendam as a shipping method.

• Coming soon

  Bumpa

  Book Sendam riders from the orders you already manage in Bumpa.

• Live

  Lagos

  Mainland and Island

• Coming soon

  Abuja

  Not yet available

• Coming soon

  Port Harcourt

  Not yet available

• A pickup or drop-off outside the Lagos service area is rejected with 422 validation_failed, with the reason under fields.pickup or fields.dropoff. Quote first and you will find out before your customer pays.
• Crossing between Mainland and Island adds a bridge surcharge to the price (crosses_bridge: true on the quote), and express is only available within one side.