CargoMov Merchant API

Turn store orders into trackable CargoMov deliveries.

A secure server-to-server integration for real-time quotations, authoritative payment checks, idempotent shipment creation, customer tracking and delivery webhooks.

Open Merchant dashboard Download CargoMov Merchant API

Base URL

Production gateway

https://europe-west1-cargomov-ghana.cloudfunctions.net/cargoMovMerchantApi/v1/merchant

Store-bound sandbox and live credentials120 requests per minute by defaultJSON requests and responses over HTTPS

Quick start

Create your first sandbox quote

Approve the Merchant account, create a sandbox store and generate a key in the Merchant dashboard. Keep the key on your server. Then request a quote using verified map coordinates.

Create a quote

curl -X POST "https://europe-west1-cargomov-ghana.cloudfunctions.net/cargoMovMerchantApi/v1/merchant/quotes" \
  -H "CargoMov-Key: $CARGOMOV_MERCHANT_KEY" \
  -H "CargoMov-Store: $CARGOMOV_STORE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup": {
      "address": "Osu, Accra",
      "lat": 5.5560,
      "lng": -0.1820,
      "ghanaPostGps": "GA-123-4567"
    },
    "dropoff": {
      "address": "Community 25, Tema",
      "lat": 5.7412,
      "lng": 0.0302
    }
  }'

Authentication

Send the one-time Merchant key in the CargoMov-Key header and identify its connected store with CargoMov-Store. Keep both values in secure server-side environment variables. Never place the secret in browser code, a mobile app or source control.

Environments and keys

cmv_sandbox_... writes only to isolated test records. cmv_live_... can create real CargoMov delivery work. Rotation immediately revokes the previous active key.

Delivery workflow

A controlled order-to-shipment sequence

Connect a store

Create a sandbox store, register its approved website origins and complete CargoMov verification.

Request a quote

Send precise pickup and delivery coordinates. Quotes use CargoMov vehicle pricing and expire after 15 minutes.

Verify payment

Verify the Paystack reference on your server. Never trust payment state supplied by a browser.

Create the shipment

Submit the selected quote with a stable idempotency key when the goods are ready.

Reference

Merchant endpoints

Method	Path	Permission	Purpose
POST	`/quotes`	quotes:create	Create an authoritative delivery quote.
GET	`/quotes/{quoteId}`	quotes:read	Retrieve a quote owned by this store.
POST	`/payments/verify`	shipments:create	Verify a Paystack payment against Merchant metadata.
POST	`/shipments`	shipments:create	Create one shipment safely using an Idempotency-Key.
GET	`/shipments/{shipmentId}`	shipments:read	Retrieve a store-owned shipment.
GET	`/shipments/{shipmentId}/tracking`	tracking:read	Read current delivery and driver-assignment state.
POST	`/shipments/{shipmentId}/cancel`	shipments:create	Cancel an unassigned shipment.
GET	`/services`	Authenticated	List enabled CargoMov vehicle services.
GET	`/coverage`	Authenticated	Read the current service-coverage policy.
GET	`/account`	Authenticated	Read the credential-bound Merchant and store status.

Idempotent creation

Create a shipment exactly once

Quote valid for 15 minutes

Use the same idempotency key when retrying the same store order. CargoMov returns the original shipment for an identical retry and rejects the key if the request payload changed.

Create a shipment

curl -X POST "https://europe-west1-cargomov-ghana.cloudfunctions.net/cargoMovMerchantApi/v1/merchant/shipments" \
  -H "CargoMov-Key: $CARGOMOV_MERCHANT_KEY" \
  -H "CargoMov-Store: $CARGOMOV_STORE_ID" \
  -H "Idempotency-Key: store-order-4821" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "QUOTE_ID",
    "serviceId": "pickup",
    "merchantOrderId": "ORD-4821",
    "paymentReference": "PAYSTACK_REFERENCE",
    "goodsReady": true,
    "recipient": {
      "name": "Ama Mensah",
      "phone": "+233XXXXXXXXX"
    }
  }'

Delivery webhooks

Receive shipment changes automatically

Register an HTTPS endpoint from the Merchant integration workspace. CargoMov signs the exact JSON body using HMAC-SHA256 and retries temporary failures with exponential backoff for up to eight attempts.

shipment.createdshipment.updatedshipment.deliveredshipment.cancelledtracking.updatedorder.updated

Verification checklist

Read the raw request bodyCalculate HMAC-SHA256 with the signing secretCompare signatures in constant timeProcess every event idempotently

Errors

Keep the request ID

Error responses include a stable code, safe message and request ID. Log the request ID—not the customer payload or complete API key—when contacting CargoMov support.

Error response

{
  "ok": false,
  "error": "failed-precondition",
  "message": "The selected quote has expired.",
  "requestId": "mreq_..."
}

Production checklist

Complete testing with a sandbox store.Keep API keys in a server-side secret manager.Use a unique idempotency key for every store order.Verify payment before shipment creation.Test duplicate requests and webhook retries.Rotate or revoke credentials after suspected exposure.

Integration support

Ready to connect your store?

Start in sandbox or contact CargoMov for production onboarding.

Download API contract Contact support