{"openapi":"3.0.0","info":{"title":"Neupa WhatsApp and M-Pesa APIs","version":"1.0.0","description":"WhatsApp messaging and tenant-scoped M-Pesa collection APIs."},"servers":[{"url":"https:\/\/neupa.co.ke\/api\/v1\/whatsapp","description":"Production Server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"api_key"},"BearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"ApiKeyAuth":[]}],"paths":{"\/status":{"get":{"summary":"Get Instance Status","description":"Returns the current connection state of your WhatsApp instance","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"state":"connected","status":"active","phone":"254700000000","profile_name":"John Doe"}}}}}}}},"\/start":{"post":{"summary":"Start Session","description":"Starts the WhatsApp session for the given instance","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"state":"initializing"}}}}}}}},"\/sync":{"post":{"summary":"Sync Session State","description":"Syncs the current session state from the engine","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"state":"connected","status":"active"}}}}}}}},"\/qr":{"get":{"summary":"Get QR Code","description":"Returns the QR code image (base64 PNG) to link your WhatsApp account","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"reset","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"qr":"data:image\/png;base64,iVBORw0KGgo..."}}}}}}}},"\/send":{"post":{"summary":"Send Message","description":"Sends text, images, documents (including PDFs), audio, or other files. Media can be supplied by public URL or a multipart upload up to 14 MB.","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"},"type":{"type":"string","enum":["text","media"]},"media":{"type":"object","properties":{"url":{"type":"string"},"mimeType":{"type":"string"},"fileName":{"type":"string"},"caption":{"type":"string"}}}},"required":["to"]}},"multipart\/form-data":{"schema":{"type":"object","properties":{"to":{"type":"string"},"message":{"type":"string"},"type":{"type":"string","enum":["text","media"]},"media_url":{"type":"string","format":"uri"},"media_mime_type":{"type":"string"},"media_file":{"type":"string","format":"binary"},"caption":{"type":"string"}},"required":["to","type"]}}}},"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"id":"3EB0C767D97B42B1B6C5","to":"254712345678","timestamp":1719230400}}}}}}}},"\/webhooks":{"get":{"summary":"List Webhooks","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":[{"id":1,"url":"https:\/\/yourapp.com\/webhook","events":["message","status"],"active":true}]}}}}}},"post":{"summary":"Register Webhook","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}},"required":["url"]}}}},"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"id":2,"url":"https:\/\/yourapp.com\/whatsapp-webhook","events":["message","status"]}}}}}}}},"\/webhooks\/{id}":{"delete":{"summary":"Delete Webhook","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"message":"Webhook deleted"}}}}}}},"\/messages":{"get":{"summary":"Get Message Logs","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"messages":[{"id":1,"direction":"outbound","to":"254712345678","message":"Hello!","status":"sent"}],"total":42,"page":1}}}}}}}},"\/linked-numbers\/{linkedNumber}\/messages":{"get":{"summary":"Get Message Logs for a Linked Number","description":"Returns paginated message history for the linked number. The API key must belong to the linked number in the path.","parameters":[{"name":"linkedNumber","in":"path","required":true,"schema":{"type":"integer"}},{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["incoming","outgoing"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message logs returned successfully","content":{"application\/json":{"example":{"success":true,"data":{"stats":{"total":42,"incoming":20,"outgoing":22,"last_at":"2026-11-09T10:00:00Z"},"messages":[{"id":1,"direction":"incoming","from":"254712345678","to":"254700000000","message":"Hello","status":"received","timestamp":"2026-11-09T10:00:00Z"}],"pagination":{"current_page":1,"last_page":1,"per_page":50,"total":1}}}}}},"401":{"description":"API key missing or invalid"},"403":{"description":"The API key does not belong to the linked number in the path"}}}},"\/broadcast":{"post":{"summary":"Send Broadcast Message","description":"Send a single message to multiple recipients at once","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"recipients":{"type":"array","items":{"type":"object","properties":{"phone":{"type":"string"},"name":{"type":"string"}},"required":["phone"]}},"label":{"type":"string"},"type":{"type":"string"},"media_url":{"type":"string"}},"required":["message","recipients"]}}}},"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"batch_id":5,"status":"completed","total":3,"sent":3,"failed":0}}}}}}},"get":{"summary":"List Broadcasts","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"stats":{"total_batches":12,"total_sent":847},"batches":[]}}}}}}}},"\/broadcast\/{id}":{"get":{"summary":"Get Broadcast Result","parameters":[{"name":"api_key","in":"query","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Success","content":{"application\/json":{"example":{"success":true,"data":{"id":5,"status":"completed","total":3,"sent":3,"failed":0}}}}}}}},"\/config":{"servers":[{"url":"https:\/\/neupa.co.ke\/api\/v1\/mpesa","description":"M-Pesa Gateway"}],"get":{"summary":"Get the authenticated merchant configuration","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Configuration state. Daraja secrets are never returned.","content":{"application\/json":{"example":{"success":true,"configured":true,"config":{"destination_type":"paybill","shortcode":"123456","account_reference":null,"environment":"sandbox","credentials_configured":true}}}}}}},"post":{"summary":"Save merchant Daraja credentials and payment destination","description":"Send all three Daraja secrets on initial setup or credential rotation. Omit all three to retain the saved credentials when updating other fields.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["destination_type","shortcode"],"properties":{"destination_type":{"type":"string","enum":["till","paybill","paybill_ref"]},"shortcode":{"type":"string","description":"Merchant Till or PayBill number"},"account_reference":{"type":"string"},"consumer_key":{"type":"string","writeOnly":true},"consumer_secret":{"type":"string","writeOnly":true},"passkey":{"type":"string","writeOnly":true},"environment":{"type":"string","enum":["sandbox","production"]},"label":{"type":"string"}}}}}},"responses":{"200":{"description":"Configuration saved. Secret values are not returned."},"422":{"description":"Invalid destination or incomplete credentials."}}}},"\/stk-push":{"servers":[{"url":"https:\/\/neupa.co.ke\/api\/v1\/mpesa","description":"M-Pesa Gateway"}],"post":{"summary":"Initiate an STK Push for the authenticated merchant","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["phone","amount"],"properties":{"phone":{"type":"string","example":"0712345678"},"amount":{"type":"integer","minimum":1},"account_reference":{"type":"string"},"description":{"type":"string","maxLength":13},"callback_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"STK Push accepted; response includes transaction_id and checkout_request_id."},"403":{"description":"API access is disabled for this account."},"422":{"description":"Invalid request or merchant configuration."}}}},"\/check-status":{"servers":[{"url":"https:\/\/neupa.co.ke\/api\/v1\/mpesa","description":"M-Pesa Gateway"}],"post":{"summary":"Check a transaction owned by the authenticated merchant","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["transaction_id"],"properties":{"transaction_id":{"type":"integer"}}}}}},"responses":{"200":{"description":"Current transaction state."},"404":{"description":"Transaction not found for this merchant."}}}},"\/c2b\/register":{"servers":[{"url":"https:\/\/neupa.co.ke\/api\/v1\/mpesa","description":"M-Pesa Gateway"}],"post":{"summary":"Register C2B callbacks for the authenticated merchant PayBill","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"C2B callback URLs registered."},"422":{"description":"Merchant configuration invalid or Daraja registration failed."}}}}}}