{"openapi":"3.1.0","info":{"title":"MadaPay Hosted API","version":"1.0.0","description":"High-performance, non-custodial multi-tenant payment gateway and orchestration API for Madagascar (MVola, Orange Money, Airtel Money, Papi, FiveOne, Alefa).","contact":{"name":"MadaPay API Support","url":"https://madapay.mg"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.madapay.mg","description":"Production API Gateway"},{"url":"http://localhost:3000","description":"Local Development Server"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key (mp_test_... or mp_live_...)","description":"Authenticate using your scoped project API key."}},"schemas":{"PaymentMethod":{"type":"string","enum":["mvola","orange_money","airtel_money"]},"PaymentStatus":{"type":"string","enum":["pending","processing","succeeded","failed","cancelled","expired"]},"Payment":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"reference":{"type":"string"},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"amount":{"type":"integer","description":"Amount in Malagasy Ariary (MGA)"},"currency":{"type":"string","enum":["MGA"]},"status":{"$ref":"#/components/schemas/PaymentStatus"},"customerPhone":{"type":"string"},"customerEmail":{"type":"string","nullable":true},"customerName":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"action":{"type":"object","nullable":true},"underReview":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","reference","provider","paymentMethod","amount","currency","status","customerPhone","createdAt"]},"PaymentLink":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"amount":{"type":"integer"},"currency":{"type":"string","enum":["MGA"]},"allowedMethods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"maxUses":{"type":"integer"},"usedCount":{"type":"integer"},"status":{"type":"string","enum":["active","completed","expired","cancelled"]},"redirectUrl":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","code","title","amount","currency","allowedMethods","status","createdAt"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","nullable":true}},"required":["code","message"]}},"required":["error"]}}},"security":[{"BearerAuth":[]}],"paths":{"/health":{"get":{"summary":"Liveness Probe","description":"Returns health status and memory usage of the process.","security":[],"responses":{"200":{"description":"Healthy"}}}},"/ready":{"get":{"summary":"Readiness Probe","description":"Checks database connectivity and readiness.","security":[],"responses":{"200":{"description":"Ready"},"503":{"description":"Database disconnected"}}}},"/providers/status":{"get":{"summary":"Provider Diagnostics","description":"Returns list of supported providers and reachability without initiating real payments.","security":[],"responses":{"200":{"description":"Provider status list"}}}},"/v1/payments":{"post":{"summary":"Create Payment","description":"Initiate a mobile money payment through the configured provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":100},"currency":{"type":"string","enum":["MGA"],"default":"MGA"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"customer":{"type":"object","properties":{"phone":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["phone"]},"reference":{"type":"string"},"idempotencyKey":{"type":"string"},"metadata":{"type":"object"},"providerData":{"type":"object"}},"required":["amount","paymentMethod","customer"]}}}},"responses":{"201":{"description":"Payment initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized"},"409":{"description":"Idempotency conflict"}}},"get":{"summary":"List Payments","description":"List tenant payments with pagination.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Payment list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}}}}}}}},"/v1/payments/{id}":{"get":{"summary":"Get Payment by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Payment not found"}}}},"/v1/payments/by-reference/{reference}":{"get":{"summary":"Get Payment by Merchant Reference","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Payment not found"}}}},"/v1/payment-links":{"post":{"summary":"Create Payment Link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer","minimum":100},"currency":{"type":"string","enum":["MGA"],"default":"MGA"},"allowedMethods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"maxUses":{"type":"integer","default":1},"expiresAt":{"type":"string","format":"date-time"},"redirectUrl":{"type":"string","format":"uri"}},"required":["title","amount"]}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}}}},"get":{"summary":"List Payment Links","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}}}}}}}}}},"/v1/payment-links/code/{code}":{"get":{"summary":"Get Public Checkout Details","security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"404":{"description":"Payment link not found"}}}},"/v1/payment-links/code/{code}/pay":{"post":{"summary":"Pay Payment Link (Public Checkout Execution)","security":[],"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"customerPhone":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string"},"providerData":{"type":"object"}},"required":["paymentMethod","customerPhone"]}}}},"responses":{"200":{"description":"Payment initiated"},"400":{"description":"Link expired or invalid payment"}}}},"/v1/keys":{"post":{"summary":"Issue API Key","description":"Generate a new API key. The full key is returned ONLY once in this response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["sandbox","production"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["name","environment"]}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object","properties":{"apiKey":{"type":"object"},"fullKey":{"type":"string","description":"One-time plaintext key reveal"}}}}}}}},"get":{"summary":"List API Keys (Prefix only)","responses":{"200":{"description":"List of keys with prefixes"}}}},"/v1/webhooks/endpoints":{"post":{"summary":"Register Webhook Endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"secret":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}},"required":["url","secret","events"]}}}},"responses":{"201":{"description":"Endpoint registered"}}},"get":{"summary":"List Registered Webhook Endpoints","responses":{"200":{"description":"List of endpoints"}}}}}}