Move Smarter. Deliver Faster.
Track Shipment
ODTC LOGISTICS · DEVELOPER CENTRE

API & Webhook Documentation

Everything your team needs to connect an application to ODTC Logistics, test safely and go live with confidence.

ODTC LOGISTICS · DEVELOPER DOCUMENTATION

ODTC API & Webhook Documentation

A practical integration guide for connecting websites, mobile apps, marketplaces, ERPs and business systems to ODTC Logistics. Register once, test safely in Sandbox, then request Production access when your integration is ready.

Open Developer PortalAPI Overview
API base URL

https://odtclogistics.com/odtc-api/odtc/v1/partner/v2

Use the same base URL for the selected environment.
Authentication

Bearer token · environment-specific credentials

Webhook security

HMAC-SHA256 · event ID deduplication · HTTPS

Download OpenAPI 3.1 JSON Get Postman collection

Complete API endpoint reference

All examples below use JSON. Replace sample identifiers and values with your real data. Responses are illustrative schemas; IDs, amounts, statuses and timestamps are generated by the live ODTC system.

Quote-only integration: The recommended minimal quote body contains pickup_lat, pickup_lng, dropoff_lat, dropoff_lng and vehicle_type. ODTC reverse-geocodes the coordinates and checks operating-state coverage. Existing detailed requests containing pickup/drop-off address, city and state fields remain supported. A quote never creates a booking or shipment, assigns a rider or debits money. Additional customer, recipient and parcel information belongs in the separate Create order request after the customer accepts the quote.

Where to find the HMAC-SHA256 secret: Sign in to Developer Workspace → Webhooks. Select Sandbox or Production, configure the HTTPS receiver and events, tick Generate / rotate signing secret when creating it for the first time, then save. Copy the secret from the one-time output immediately. The GET settings endpoint never reveals it; the API Bearer token is a different credential. Rotation immediately invalidates the previous secret for that environment.

GET · Health check

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/health

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

No request body.

Example response

{"success":true,"service":"ODTC Logistics Partner API","version":"v2","environment":"sandbox","timestamp":"2026-11-12T15:00:00+00:00"}

HTTP statuses: 200 · 401 · 403 · 429

GET · Wallet

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/wallet

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

No request body.

Example response

{"success":true,"environment":"production","balance":25000,"currency":"NGN","billing":{"mode":"hybrid","credit_limit":100000,"outstanding_credit":3010,"wallet_funding_required":false},"invoices":[{"invoice_reference":"ODTC-INV-EXAMPLE","amount":3010,"paid_amount":0,"status":"open","due_at":"2026-12-13T00:00:00+01:00"}],"ledger":[]}

HTTP statuses: 200 · 401 · 403 · 429

POST · Create quote (minimal coordinates)

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/quote

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

{"pickup_lat":6.4541,"pickup_lng":3.3947,"dropoff_lat":6.6018,"dropoff_lng":3.3515,"vehicle_type":"motorcycle"}

Example response

{"success":true,"quote_only":true,"booking_created":false,"quote_reference":"ODTC-QT-EXAMPLE","partner_quote_token":"SIGNED_QUOTE_TOKEN","distance_km":12.4,"eta_minutes":35,"amount":3010,"total_fare":3010,"currency":"NGN","expires_at":"2026-11-16T12:00:00"}

HTTP statuses: 200 · 400 · 422 · 503

POST · Create order

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

{"external_order_id":"STORE-1001","quote_reference":"QUOTE_FROM_PREVIOUS_STEP","customer_name":"Ada Okafor","customer_phone":"+2348000000000","customer_email":"ada@example.com","recipient_name":"Ada Okafor","recipient_phone":"+2348000000000","package_description":"Documents","delivery_instructions":"Call on arrival"}

Example response

{"success":true,"sandbox":false,"external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"amount":3010,"currency":"NGN","billing":{"mode":"hybrid","wallet_debited":2000,"credit_invoiced":1010,"wallet_balance":23000,"invoice_status":"open","invoice_reference":"ODTC-INV-EXAMPLE","invoice_due_at":"2026-12-13T00:00:00+01:00"},"status":"ready_for_dispatch","verification":{"pickup_code":"482913","delivery_code":"739251"},"verification_delivery":{"pickup_webhook_queued":true,"delivery_webhook_queued":true,"customer_email_sent":true,"action_required":false,"message":"Both pickup and delivery codes were issued when the Production order was accepted."}}

HTTP statuses: 201 · 200 duplicate · 400 · 402 · 422 · 500

GET · Retrieve order

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Path: external_id = your external_order_id.

Example response

{"success":true,"external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"status":"arrived_pickup","updated_at":"2026-11-12T15:20:00","estimated_delivery":null,"billing":{"mode":"hybrid","order_amount":3010,"wallet_debited":2000,"credit_invoiced":1010,"billing_status":"invoiced","invoice":{"invoice_reference":"ODTC-INV-EXAMPLE","amount":1010,"paid_amount":0,"status":"open","due_at":"2026-12-13T00:00:00+01:00"}},"rider":null}

HTTP statuses: 200 · 401 · 403 · 404 · 429

POST · Advance Sandbox lifecycle

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/sandbox/orders/{external_id}/advance

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Sandbox credentials only. Payload: {"status":"arrived_pickup"}. Advance in order: ready_for_dispatch, assigned, arrived_pickup, record synthetic pickup evidence and verify pickup; then advance to in_transit and arrived_dropoff, record synthetic delivery evidence and verify delivery. Invalid skips and backward transitions are rejected.

Example response

{"success":true,"sandbox":true,"simulated":true,"status":"arrived_pickup","tracking":[{"status":"arrived_pickup"}]}

HTTP statuses: 200 · 400 · 401 · 403 · 404 · 409

POST · Simulate Sandbox photo evidence

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/sandbox/orders/{external_id}/evidence

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Sandbox credentials only. Payload: {"proof_type":"pickup"} at arrived_pickup or {"proof_type":"delivery"} at arrived_dropoff. This stores synthetic metadata only; no image or live evidence record is created.

Example response

{"success":true,"sandbox":true,"simulated":true,"proof_type":"pickup","evidence":{"captured":true,"simulated":true}}

HTTP statuses: 200 · 400 · 401 · 403 · 404 · 409

GET · Tracking

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/tracking

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Path: external_id = your external_order_id.

Example response

{"success":true,"external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"status":"in_transit","estimated_delivery":null,"rider":null,"rider_location":null,"events":[]}

HTTP statuses: 200 · 401 · 403 · 404 · 429

POST · Verify pickup code

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verify-pickup

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

{"pickup_code":"482913"}

Example response

{"success":true,"verified":true,"stage":"pickup","external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"previous_status":"arrived_pickup","status":"picked_up","verified_at":"2026-11-12T15:30:00","message":"Pickup code verified successfully."}

HTTP statuses: 200 · 400 · 401 · 403 · 404 · 409 · 429 · 500

POST · Verify delivery code

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verify-delivery

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

{"delivery_code":"739251","recipient_name":"Ada Okafor","signature":"Ada Okafor confirms receipt of parcel"}

Example response

{"success":true,"verified":true,"stage":"delivery","external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","shipment_id":125,"previous_status":"arrived_dropoff","status":"delivered","verified_at":"2026-11-12T16:45:00","message":"Delivery code verified successfully."}

HTTP statuses: 200 · 400 · 401 · 403 · 404 · 409 · 429 · 500

POST · Cancel order

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/cancel

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Empty JSON object: {}

Example response

{"success":true,"status":"cancelled","wallet_refund_amount":2000,"prepaid_refund":2000,"paid_invoice_credit":0,"unpaid_invoice_voided":true}

HTTP statuses: 200 · 401 · 403 · 409 · 500

POST · Reissue verification code

Endpoint
https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verification/reissue

Headers
Authorization: Bearer CLIENT_ID.SECRET
Content-Type: application/json
Accept: application/json

Request payload

Empty JSON object: {}

Example response

{"success":true,"message":"A replacement code for the current handover stage was generated and queued to your signed webhook. Both initial codes are issued when the Production order is accepted; a replacement is also emailed to the customer when a customer email is stored.","code_stage":"pickup"}

HTTP statuses: 200 · 401 · 403 · 409 · 422 · 429 · 503

Developer diagnostics: Open Developer Workspace → API Monitoring to inspect each API request, safe headers, redacted request JSON and query parameters, redacted response JSON, HTTP status, latency and request ID. Use the request ID when contacting ODTC Support. Authorization values, API/webhook secrets, verification codes, signatures and customer personal data are never displayed in diagnostic logs.

Handover verification rules: Production uses real verification codes and the assigned rider’s private photo evidence. Pickup requires shipment status arrived_pickup and a private pickup photo uploaded by the assigned rider. Delivery requires arrived_dropoff or delivery_attempted, a private delivery photo from the assigned rider, plus recipient_name and typed recipient confirmation text (the signature field is text, not a drawn signature image). The API accepts the six-digit code for verification. Both pickup and delivery codes are returned in the authenticated successful Production order-creation response and generated when the Production order is accepted. The pickup code is used only at pickup; the delivery code must remain confidential until recipient handover. Both are delivered through the signed webhook as separate `verification.codes_issued` events and, when a customer email is supplied, in the customer email. The authenticated order-creation response already returns both codes; customer email and signed webhooks are optional additional channels. Incorrect attempts are limited to five per partner, shipment and stage per 15-minute window. Sandbox verification is supported with synthetic pickup code 123456 and delivery code 654321 after advancing to the matching stage and recording the matching synthetic photo-evidence metadata through the Sandbox evidence endpoint. Synthetic evidence is metadata only; no image is uploaded and no Production handover records are accessed or changed.

Webhook event catalogue

  • order.accepted — order accepted and ready for dispatch.
  • rider.assigned — a rider has been assigned.
  • rider.arrived_pickup — rider arrived at pickup.
  • pickup.verified — pickup handover verified.
  • parcel.photo_captured — private parcel photo evidence was recorded; the outbound payload contains proof metadata, not the image.
  • verification.codes_issued — a stage-specific verification code was issued to the subscribed secure receiver.
  • delivery.in_transit — parcel is in transit.
  • rider.arrived_dropoff — rider arrived at destination.
  • delivery.verified and delivery.completed — recipient verification and completion.
  • delivery.failed — delivery attempt failed.
  • order.cancelled — eligible order cancelled.

Each event uses an envelope containing id, type, created_at and data. Delivery is at-least-once; deduplicate by event ID and do not assume strict ordering. Retry attempts use exponential backoff and stop after the configured attempt ceiling. A manual retry is available for eligible failed/disabled events.

Sample payloads for every event

These are illustrative payload contracts. Replace example identifiers and timestamps. Verification code values are placeholders; the two initial verification.codes_issued events are sent at Production order acceptance, one for pickup and one for delivery; later reissue events replace only the requested stage code.

[
  {"id":"evt_example_01","type":"order.accepted","created_at":"2026-11-12T10:00:00Z","data":{"external_order_id":"STORE-1001","booking_reference":"ODTC-ABC123","status":"ready_for_dispatch"}},
  {"id":"evt_example_02","type":"verification.codes_issued","created_at":"2026-11-12T10:00:00Z","data":{"external_order_id":"STORE-1001","code_stage":"pickup","pickup_code":"[SIX_DIGIT_PICKUP_CODE]"}},
  {"id":"evt_example_03","type":"verification.codes_issued","created_at":"2026-11-12T10:00:00Z","data":{"external_order_id":"STORE-1001","code_stage":"delivery","delivery_code":"[SIX_DIGIT_DELIVERY_CODE]"}},
  {"id":"evt_example_04","type":"rider.assigned","created_at":"2026-11-12T10:05:00Z","data":{"external_order_id":"STORE-1001","rider":{"name":"Assigned Rider","phone":"[REDACTED IN MONITORING]","vehicle_type":"motorcycle"}}},
  {"id":"evt_example_05","type":"rider.arrived_pickup","created_at":"2026-11-12T10:15:00Z","data":{"external_order_id":"STORE-1001","status":"arrived_pickup"}},
  {"id":"evt_example_06","type":"parcel.photo_captured","created_at":"2026-11-12T10:16:00Z","data":{"external_order_id":"STORE-1001","proof_type":"pickup","captured_at":"2026-11-12T10:16:00Z"}},
  {"id":"evt_example_07","type":"pickup.verified","created_at":"2026-11-12T10:18:00Z","data":{"external_order_id":"STORE-1001","status":"picked_up"}},
  {"id":"evt_example_08","type":"delivery.in_transit","created_at":"2026-11-12T10:20:00Z","data":{"external_order_id":"STORE-1001","status":"in_transit"}},
  {"id":"evt_example_09","type":"rider.arrived_dropoff","created_at":"2026-11-12T10:45:00Z","data":{"external_order_id":"STORE-1001","status":"arrived_dropoff"}},
  {"id":"evt_example_10","type":"parcel.photo_captured","created_at":"2026-11-12T10:46:00Z","data":{"external_order_id":"STORE-1001","proof_type":"delivery","captured_at":"2026-11-12T10:46:00Z"}},
  {"id":"evt_example_11","type":"delivery.verified","created_at":"2026-11-12T10:48:00Z","data":{"external_order_id":"STORE-1001","status":"delivered"}},
  {"id":"evt_example_12","type":"delivery.completed","created_at":"2026-11-12T10:48:00Z","data":{"external_order_id":"STORE-1001","status":"delivered"}},
  {"id":"evt_example_13","type":"delivery.failed","created_at":"2026-11-12T11:00:00Z","data":{"external_order_id":"STORE-1002","status":"delivery_attempted"}},
  {"id":"evt_example_14","type":"order.cancelled","created_at":"2026-11-12T11:10:00Z","data":{"external_order_id":"STORE-1003","status":"cancelled"}}
]

Signature verification examples

Always verify the exact raw request bytes before parsing JSON. PHP: hash_hmac("sha256", $rawBody, $secret) and compare the result to the hex digest after sha256= using hash_equals(). JavaScript (Node): crypto.createHmac("sha256", secret).update(rawBody).digest("hex") and use timingSafeEqual(). Python: hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() and hmac.compare_digest(). Never verify a parsed-and-reserialized JSON body.

Complete webhook receiver examples — PHP, Node.js and Python

PHP

$rawBody = file_get_contents("php://input");
$provided = $_SERVER["HTTP_X_ODTC_SIGNATURE"] ?? "";
$expected = "sha256=" . hash_hmac("sha256", $rawBody, $webhookSecret);
if (!hash_equals($expected, $provided)) { http_response_code(401); exit; }
$event = json_decode($rawBody, true);
// Persist X-ODTC-Event-ID before applying side effects.

Node.js

const crypto = require("node:crypto");
const rawBody = req.rawBody; // Preserve raw bytes in your body parser.
const provided = req.get("X-ODTC-Signature") || "";
const expected = "sha256=" + crypto.createHmac("sha256", webhookSecret).update(rawBody).digest("hex");
const a = Buffer.from(expected); const b = Buffer.from(provided);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);
const event = JSON.parse(rawBody.toString("utf8"));

Python

import hashlib, hmac, json
raw_body = request.get_data(cache=True)
provided = request.headers.get("X-ODTC-Signature", "")
expected = "sha256=" + hmac.new(webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, provided):
    return ("invalid signature", 401)
event = json.loads(raw_body)

Persist event IDs using a unique constraint and return HTTP 2xx only after the receiver has safely accepted the event. Repeated event IDs must not repeat business side effects.

Field and environment rules

  • external_order_id: required, unique per developer and environment, maximum 190 characters; reuse for idempotent retries.
  • quote_reference: required; must belong to this developer/environment and remain unexpired and unused.
  • customer_name and customer_phone: required for Production orders; optional for Sandbox simulations.
  • verification.pickup_code / verification.delivery_code: actual six-digit values in the successful authenticated order-creation response only; never returned by order retrieval, tracking or logs.
  • recipient_name and signature: required for delivery verification.
  • parcel_weight: optional, greater than zero and at most 1000; dimensions are optional, greater than zero and at most 500 each.

Standard error response format

{"code":"odtc_verification_stage","message":"Shipment is not at the required pickup verification stage.","data":{"status":409}}

Common error examples

  • 401 odtc_auth — missing or invalid Bearer token.
  • 403 odtc_scope — credential lacks the endpoint's required scope.
  • 402 odtc_balance — Prepaid wallet balance is insufficient or the approved Postpaid/Hybrid credit limit would be exceeded.
  • 409 odtc_verification_stage — shipment has not reached the required handover stage.
  • 422 odtc_quote_invalid — quote is expired, consumed, cross-environment or not owned by this developer.
  • 429 odtc_rate_limit — API request limit reached; retry after the rate-limit window.
  • 503 odtc_verification_queue — verification-code webhook could not be queued; the previous code remains valid during reissue.

Recommended path: Create a developer account → verify email → wait for approval → create Sandbox credentials → test quotes and simulated orders → configure and test webhooks → request Production access.

1. How ODTC integrations work
HOW ODTC INTEGRATIONS WORK Your application connects to ODTC through the secure ODTC REST API. ODTC can send shipment updates back to your application through signed webhooks. Partner application → ODTC API: register, request an official delivery quote, submit an order and retrieve your own order, wallet and tracking information. ODTC → Partner application: receive signed event notifications such as order acceptance, rider assignment, pickup, delivery progress and completion. Sandbox and Production use separate credentials and data. Sandbox orders are simulations and do not create live shipments or debit a production partner wallet.
2. Get started and developer approval
GET STARTED 1. Open the ODTC Developer Portal at /developer/ and create a developer account. 2. Verify your email using the six-digit OTP. 3. Wait for ODTC approval. Email verification alone does not activate API access. 4. Sign in and create Sandbox credentials. 5. Configure a public HTTPS webhook receiver if you need event notifications. 6. Complete the Sandbox tests before requesting Production access. Keep API tokens and webhook secrets on your server. Never expose them in browser JavaScript, a public mobile app, source control or support screenshots.
3. API credentials and authentication
API AUTHENTICATION Send the environment-specific token in the Authorization header: Authorization: Bearer CLIENT_ID.SECRET Content-Type: application/json Accept: application/json Sandbox and Production credentials are separate. The full token is displayed once when created. ODTC stores a one-way secret hash. Revoked credentials and suspended or unapproved developer accounts are denied. Super Admin controls Production access, permitted scopes and per-credential rate limits. The default limit is 120 requests per minute and can be configured by ODTC administrators. WEBHOOK AUTHENTICATION ODTC signs the exact raw JSON request body using HMAC-SHA256. Verify X-ODTC-Signature before parsing JSON. The signature format is sha256= followed by the hexadecimal digest. Use X-ODTC-Event-ID to deduplicate events. Compare signatures with a constant-time comparison function.
4. Partner API v2 endpoints
PARTNER API V2 — CURRENT ROUTES Use only the authenticated Partner API v2 base URL: /odtc-api/odtc/v1/partner/v2 GET /health GET /wallet POST /quote POST /orders GET /orders/{external_id} GET /orders/{external_id}/tracking POST /orders/{external_id}/verify-pickup POST /orders/{external_id}/verify-delivery POST /orders/{external_id}/cancel POST /orders/{external_id}/verification/reissue The retired /odtc-api/odtc/v1/partner/orders and /odtc-api/odtc/v1/partner/health endpoints are legacy single-token routes and return HTTP 410. Do not use them for new integrations. Delivery verification accepts a six-digit delivery_code, recipient_name and signature text. The signature field stores typed recipient confirmation text; it is not a drawn signature image. A drawn signature requires a separate capture/upload workflow and is not represented by this endpoint. PRODUCTION BILLING ODTC Super Admin assigns each partner Prepaid, Postpaid or Hybrid billing and the applicable credit limit. Developer wallet funding is optional for account registration, approval, credentials and Sandbox testing. Prepaid Production orders debit the wallet; Postpaid orders invoice the approved credit line; Hybrid orders debit available wallet funds first and invoice the remaining approved credit. PRODUCTION VERIFICATION CODES Both pickup and delivery codes are generated when a Production order is accepted. ODTC sends them as separate signed verification.codes_issued events and, when a customer email is supplied, sends both to the customer. The partner can read both codes directly from the successful order-creation response; a signed webhook receiver is an optional additional channel. The pickup code is used only at pickup. The delivery code remains confidential until recipient handover. The assigned rider still captures the required private pickup and delivery photo evidence and enters the relevant customer-provided code at the corresponding stage. QUOTE-ONLY PARTNER API (CURRENT): POST /partner/v2/quote accepts pickup_lat, pickup_lng, dropoff_lat, dropoff_lng and vehicle_type as the minimum request. ODTC reverse-geocodes the coordinates and checks enabled Nigerian operating-state coverage. Existing detailed requests that include pickup_address, pickup_city, pickup_state, dropoff_address, dropoff_city and dropoff_state remain supported; coordinates are still required. Package description is optional at quotation stage. A quote returns quote_reference, amount/total_fare, distance, ETA, currency and expiry. It does not create a booking or shipment, assign a rider, debit a wallet or create an invoice. Only submit the separate POST /partner/v2/orders request after the customer accepts the quote. ASSIGNED RIDER CONTACT DETAILS For your own order, call GET /partner/v2/orders/{external_id} or GET /partner/v2/orders/{external_id}/tracking with your ODTC Partner Bearer token. After the rider accepts the assignment, read rider.name, rider.phone, rider.vehicle_type, rider.assignment_status and rider.assigned_at. Before acceptance or after a declined, expired, cancelled, returned or replaced offer, rider is null. Completed rider details remain available on the completed order. You may also subscribe to the signed rider.assigned webhook. These details are scoped to your own partner order; Sandbox rider data is simulated. CURRENT PRODUCTION CODE RESPONSE CONTRACT (Core 1.19.5): On successful POST /partner/v2/orders, read the actual six-digit values from verification.pickup_code and verification.delivery_code. The verification_delivery object reports optional email/webhook notification status only; a missing webhook subscription does not block order creation. Signed verification.codes_issued webhooks and customer_email remain optional additional channels. Reuse the same external_order_id after a timeout: an idempotent retry returns any still-actionable encrypted code values without creating another shipment or charging again. After pickup verification the pickup code is no longer returned; after delivery completion neither code is returned. Codes are never included in GET order, tracking or API activity logs.
5. Signed webhooks and event subscriptions
ODTC SIGNED WEBHOOKS Configure a separate public HTTPS callback URL and event subscription for each environment. ODTC sends an HTTP POST with Content-Type: application/json. Headers: • X-ODTC-Event-ID — unique event identifier. Store it and ignore duplicate processing. • X-ODTC-Signature — sha256= followed by the HMAC-SHA256 digest of the exact raw request body. • User-Agent — ODTC-Logistics-Webhooks/2.0. Supported event subscriptions include order.accepted, rider.assigned, rider.arrived_pickup, pickup.verified, parcel.photo_captured, verification.codes_issued, delivery.in_transit, rider.arrived_dropoff, delivery.verified, delivery.completed, delivery.failed and order.cancelled. Verify the signature against the raw request bytes before parsing JSON. Return HTTP 2xx only after the event has been durably accepted. Delivery is queued and at-least-once; your receiver must be idempotent. Retries may result in repeated delivery and strict event ordering is not guaranteed. WEBHOOK SIGNING SECRET (HMAC-SHA256): In Developer Workspace, open Webhooks / Webhook Manager, select Sandbox or Production, enter the HTTPS receiver URL, choose subscribed events and save. On the first save for an environment, ODTC automatically generates and displays the secret once in the secure output; copy it immediately into your server-side secret manager. To replace an existing secret, tick Generate / rotate signing secret and save. GET settings never reveals it. Sandbox and Production secrets are separate. Rotation invalidates the previous secret for that environment immediately, so coordinate the replacement with the receiver before rotating. This is not the API Client ID, Client Secret or Bearer token.
6. Integration examples
QUOTE REQUEST POST /partner/v2/quote Send pickup_address, pickup_city, pickup_state, pickup_lat, pickup_lng, dropoff_address, dropoff_city, dropoff_state, dropoff_lat, dropoff_lng and vehicle_type. Save quote_reference and expires_at. CURL TEMPLATE curl -X POST 'https://YOUR-ODTC-DOMAIN/odtc-api/odtc/v1/partner/v2/quote' \ -H 'Authorization: Bearer CLIENT_ID.SECRET' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ --data '{"pickup_address":"12 Marina Road","pickup_city":"Lagos Island","pickup_state":"Lagos","pickup_lat":6.4541,"pickup_lng":3.3947,"dropoff_address":"4 Allen Avenue","dropoff_city":"Ikeja","dropoff_state":"Lagos","dropoff_lat":6.6018,"dropoff_lng":3.3515,"vehicle_type":"motorcycle"}' CREATE AN ORDER POST /partner/v2/orders Send external_order_id, quote_reference, customer_name and customer_phone. Keep external_order_id unchanged for safe retries. Production requires sufficient partner wallet balance and the required verification webhook subscription. VERIFY A WEBHOOK (PHP) $raw = file_get_contents('php://input'); $expected = 'sha256=' . hash_hmac('sha256', $raw, $webhookSecret); if (!hash_equals($expected, $_SERVER['HTTP_X_ODTC_SIGNATURE'] ?? '')) { http_response_code(401); exit; } After signature verification, deduplicate X-ODTC-Event-ID, persist the event and return HTTP 2xx. Do not parse and re-serialize the JSON before signature verification. EVENT ENVELOPE {"id":"event-uuid","type":"delivery.completed","created_at":"ISO-8601 timestamp","data":{"shipment_id":123,"reference":"ODTC-REF","status":"completed"}} Never place API tokens or signing secrets in browser code. CURL — MINIMAL QUOTE (NO BOOKING CREATED) curl -X POST 'https://YOUR-ODTC-DOMAIN/odtc-api/odtc/v1/partner/v2/quote' \n -H 'Authorization: Bearer CLIENT_ID.SECRET' \n -H 'Content-Type: application/json' \n --data '{"pickup_lat":6.4541,"pickup_lng":3.3947,"dropoff_lat":6.6018,"dropoff_lng":3.3515,"vehicle_type":"motorcycle"}' The quote response includes quote_only=true and booking_created=false. Send customer, recipient and parcel details only in the separate order request after quote acceptance.
7. Response codes and errors
200 successful health check or duplicate order; 201 resource created; 400 malformed or missing fields; 401 missing/invalid token; 402 insufficient Prepaid wallet balance or ODTC-approved Postpaid/Hybrid credit limit; 403 account or Production access disabled; 409 state conflict; 422 invalid/expired/cross-partner quote or missing required webhook; 429 rate limit; 500/502/503 service, route-provider or storage failure. A network timeout is uncertain: retry using the same external_order_id.
8. Retries, duplicates and delivery guarantees
API REQUESTS Reuse the same external_order_id for idempotent order retries. Do not create a new external ID after a timeout until order status has been checked. WEBHOOK DELIVERY Developer webhook delivery is at-least-once with up to six attempts, using exponential backoff capped at one hour. Receivers must verify the raw-body HMAC signature and deduplicate by event ID. Reliable webhook delivery requires ODTC's scheduled event runner to be invoked at least once per minute by the hosting provider's server scheduler. Monitor pending, retry, failed and stale sending events in the Developer Workspace. Manual retry is available for eligible failed events.
9. Security and data handling
Use HTTPS for all API calls and callback URLs. Keep credentials on trusted backend servers. Use least-privilege scopes and separate Sandbox/Production secrets. Verify HMAC against the exact raw body before parsing. Deduplicate event IDs. Never trust partner-supplied prices, payment states, rider IDs or shipment IDs. ODTC remains authoritative for quotes, shipment state and dispatch. Avoid logging credentials or unnecessary personal data.
10. Sandbox testing and troubleshooting
1. Register a developer account and verify email OTP. 2. Wait for ODTC approval. 3. Create Sandbox credentials. 4. Call the authenticated health endpoint. 5. Request a quote and confirm the expiry. 6. Create a Sandbox order and confirm it is simulated with no live shipment or wallet debit. 7. Repeat with the same external_order_id and verify idempotency. 8. Configure a Sandbox HTTPS webhook receiver and verify HMAC signatures. 9. Confirm duplicate event IDs are ignored. 10. Inspect API and webhook activity logs. Resolve all failed tests before requesting Production access. QUOTE ACCEPTANCE TESTS: Submit a coordinate-only quote and verify quote_only=true and booking_created=false. Confirm no booking, shipment, rider assignment, invoice or wallet debit is created. Repeat using the legacy detailed address payload and verify it still works. Test invalid coordinates, unresolvable locations, disabled operating states and disabled vehicle types.
11. Production launch checklist
Before Production: HTTPS enabled; Production access approved; Production credentials stored securely; callback URL verified; direct pickup and delivery codes present in the authenticated order-creation response; quote and order tests passed; duplicate order handling passed; HMAC verification passed; webhook deduplication passed; retries and monitoring configured; ODTC billing policy assigned and credit limit approved where applicable; wallet funded only if required by Prepaid billing; support and incident contacts agreed.
12. Supported scope and boundaries
The supported partner contract is Partner API v2 and the documented signed webhook events. Do not assume internal ODTC service routes are public partner endpoints. Production order creation uses ODTC’s authoritative quote and ODTC-assigned Prepaid, Postpaid or Hybrid billing policy; the partner cannot override pricing or mark an order paid. Partner wallet funding is currently an ODTC administrator operation. Rider assignment remains controlled by ODTC operations. Delivery is queued and at-least-once, not exactly-once. Production reliability requires a functioning server scheduler, monitored queues and target-environment acceptance tests. SIGNATURE CLARIFICATION: The delivery API signature field is typed recipient confirmation text, not a drawn signature image. Native Android/iOS background GPS requires a separately built and signed native application; the browser rider workspace cannot guarantee tracking while the browser is suspended. Offline queueing must never persist verification codes, credentials, customer addresses or typed confirmations in plaintext.
Live endpoint quick reference
Health GET https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/health Quote POST https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/quote Create order POST https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders Wallet GET https://odtclogistics.com/odtc-api/odtc/v1/partner/v2/wallet Webhook receiver Your public HTTPS callback URL, configured separately for Sandbox and Production.
Node.js HMAC-SHA256 receiver example

Verify the signature against the exact raw request body before parsing JSON. Configure your framework to retain the raw bytes.

const crypto = require('crypto');
const rawBody = req.rawBody; // exact bytes received, before JSON parsing
const signature = req.headers['x-odtc-signature'] || '';
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.ODTC_WEBHOOK_SECRET).update(rawBody).digest('hex');
const a = Buffer.from(signature);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
  res.status(401).send('Invalid signature');
  return;
}
const event = JSON.parse(rawBody.toString('utf8'));
// Persist event.id for deduplication before processing; return 2xx when accepted.
res.status(200).send('accepted');

The documentation describes the supported partner contract. Internal service endpoints are not public integration APIs. For security, never share credentials in tickets or email.