API & Webhook Documentation
Everything your team needs to connect an application to ODTC Logistics, test safely and go live with confidence.
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 Overviewhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2
Bearer token · environment-specific credentials
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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/health
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/wallet
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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)
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/quote
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/sandbox/orders/{external_id}/advance
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/sandbox/orders/{external_id}/evidence
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/tracking
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verify-pickup
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verify-delivery
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/cancel
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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
Endpointhttps://odtclogistics.com/odtc-api/odtc/v1/partner/v2/orders/{external_id}/verification/reissue
HeadersAuthorization: Bearer CLIENT_ID.SECRETContent-Type: application/jsonAccept: 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.verifiedanddelivery.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_nameandcustomer_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_nameandsignature: 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
2. Get started and developer approval
3. API credentials and authentication
4. Partner API v2 endpoints
5. Signed webhooks and event subscriptions
6. Integration examples
7. Response codes and errors
8. Retries, duplicates and delivery guarantees
9. Security and data handling
10. Sandbox testing and troubleshooting
11. Production launch checklist
12. Supported scope and boundaries
Live endpoint quick reference
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.
