{
  "openapi": "3.1.0",
  "info": {
    "title": "Ultraner API",
    "version": "1.0.0",
    "summary": "One API for payments across Africa — mobile money, cards, PayPal, wallets.",
    "description": "Ultraner connects African mobile-money networks into one checkout and API, with cross-border money movement and bridges to cards (Stripe) and PayPal. Live in Tanzania and Rwanda, expanding Africa-wide. All requests require a Bearer API key. See https://ultraner.com/docs for guides and https://ultraner.com/ai for AI-first integration resources.",
    "contact": { "name": "Ultraner Support", "email": "support@ultraner.com", "url": "https://ultraner.com/docs" },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://api.ultraner.com", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Payments", "description": "Accept mobile money and bank payments" },
    { "name": "Disbursements", "description": "Send money to mobile wallets and banks" },
    { "name": "Cross-border", "description": "Pay across countries, settle in local currency" },
    { "name": "Wallet", "description": "Balance, transfers and transactions" },
    { "name": "Escrow", "description": "Hold funds and release on completion" },
    { "name": "PayPal", "description": "International payers via PayPal" },
    { "name": "Stripe", "description": "Card payments via Stripe" },
    { "name": "Payment Links", "description": "Hosted, shareable checkout" }
  ],
  "paths": {
    "/v1/payments/express/mno": {
      "post": {
        "tags": ["Payments"],
        "summary": "Charge a mobile-money wallet",
        "operationId": "createMnoPayment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MnoChargeRequest" },
              "example": { "amount": 5000, "currency": "TZS", "provider": "Vodacom", "accountNumber": "255700000000", "externalId": "order_1001" }
            }
          }
        },
        "responses": {
          "200": { "description": "Charge initiated; USSD push sent to the payer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "400": { "$ref": "#/components/responses/ValidationError" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/payments/express/status/{reference}": {
      "get": {
        "tags": ["Payments"],
        "summary": "Get payment status",
        "operationId": "getPaymentStatus",
        "parameters": [{ "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/payments/express/bank": {
      "post": {
        "tags": ["Payments"],
        "summary": "Charge a bank account",
        "operationId": "createBankPayment",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankChargeRequest" } } } },
        "responses": {
          "200": { "description": "Charge initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "400": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/disbursements/lookup": {
      "post": {
        "tags": ["Disbursements"],
        "summary": "Resolve a recipient before sending",
        "operationId": "lookupDisbursement",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementLookupRequest" } } } },
        "responses": { "200": { "description": "Recipient details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementLookupResponse" } } } } }
      }
    },
    "/v1/disbursements": {
      "post": {
        "tags": ["Disbursements"],
        "summary": "Send money to a mobile wallet or bank",
        "operationId": "createDisbursement",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisbursementRequest" } } } },
        "responses": {
          "200": { "description": "Payout initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } },
          "400": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/crossborder/rates": {
      "get": {
        "tags": ["Cross-border"],
        "summary": "Get cross-border FX rates",
        "operationId": "getCrossborderRates",
        "parameters": [
          { "name": "from", "in": "query", "schema": { "type": "string" }, "example": "TZS" },
          { "name": "to", "in": "query", "schema": { "type": "string" }, "example": "RWF" }
        ],
        "responses": { "200": { "description": "Rate table", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/v1/crossborder": {
      "post": {
        "tags": ["Cross-border"],
        "summary": "Create a cross-border payment",
        "operationId": "createCrossborder",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrossborderRequest" } } } },
        "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } } }
      }
    },
    "/v1/wallet": {
      "get": {
        "tags": ["Wallet"],
        "summary": "Get wallet balances",
        "operationId": "getWallet",
        "responses": {
          "200": { "description": "Balances by currency", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Wallet" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/transfer": {
      "post": {
        "tags": ["Wallet"],
        "summary": "Transfer between Ultraner wallets",
        "operationId": "createTransfer",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequest" } } } },
        "responses": { "200": { "description": "Transfer completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } } }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": ["Wallet"],
        "summary": "List transactions",
        "operationId": "listTransactions",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": { "200": { "description": "Paged transactions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/v1/escrow": {
      "post": {
        "tags": ["Escrow"],
        "summary": "Create an escrow hold",
        "operationId": "createEscrow",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscrowRequest" } } } },
        "responses": { "200": { "description": "Escrow created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Escrow" } } } } }
      },
      "get": {
        "tags": ["Escrow"],
        "summary": "List escrow holds",
        "operationId": "listEscrow",
        "responses": { "200": { "description": "Escrow list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Escrow" } } } } } }
      }
    },
    "/v1/escrow/{escrow_code}/release": {
      "post": {
        "tags": ["Escrow"],
        "summary": "Release escrow to the recipient",
        "operationId": "releaseEscrow",
        "parameters": [{ "name": "escrow_code", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Escrow" } } } } }
      }
    },
    "/paypal/orders": {
      "post": {
        "tags": ["PayPal"],
        "summary": "Create a PayPal order",
        "operationId": "createPaypalOrder",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaypalOrderRequest" } } } },
        "responses": { "200": { "description": "Order created with approve_url", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/paypal/orders/{orderId}/capture": {
      "post": {
        "tags": ["PayPal"],
        "summary": "Capture a PayPal order",
        "operationId": "capturePaypalOrder",
        "parameters": [{ "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Captured", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/stripe/sessions": {
      "post": {
        "tags": ["Stripe"],
        "summary": "Create a Stripe checkout session",
        "operationId": "createStripeSession",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeSessionRequest" } } } },
        "responses": { "200": { "description": "Session created with checkout_url", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/v0/pay/resolve/{token}": {
      "get": {
        "tags": ["Payment Links"],
        "summary": "Resolve a hosted payment link",
        "operationId": "resolvePaymentLink",
        "security": [],
        "parameters": [{ "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Payment link details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }
      }
    },
    "/v0/pay/checkout": {
      "post": {
        "tags": ["Payment Links"],
        "summary": "Submit a hosted payment-link checkout",
        "operationId": "checkoutPaymentLink",
        "security": [],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
        "responses": { "200": { "description": "Checkout initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Pass your secret API key as `Authorization: Bearer <key>`." }
    },
    "responses": {
      "ValidationError": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "code": { "type": "string" }
        },
        "required": ["message", "code"]
      },
      "MnoChargeRequest": {
        "type": "object",
        "required": ["amount", "currency", "provider", "accountNumber"],
        "properties": {
          "amount": { "type": "integer", "description": "Amount in the smallest currency unit", "example": 5000 },
          "currency": { "type": "string", "enum": ["TZS", "RWF"], "example": "TZS" },
          "provider": { "type": "string", "description": "MNO operator code", "example": "Vodacom" },
          "accountNumber": { "type": "string", "description": "Payer phone in international format", "example": "255700000000" },
          "externalId": { "type": "string", "description": "Your idempotent reference" }
        }
      },
      "BankChargeRequest": {
        "type": "object",
        "required": ["amount", "currency", "bankCode", "accountNumber"],
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "bankCode": { "type": "string" },
          "accountNumber": { "type": "string" },
          "externalId": { "type": "string" }
        }
      },
      "DisbursementLookupRequest": {
        "type": "object",
        "required": ["provider", "accountNumber"],
        "properties": {
          "provider": { "type": "string", "example": "Airtel" },
          "accountNumber": { "type": "string", "example": "255700000000" }
        }
      },
      "DisbursementLookupResponse": {
        "type": "object",
        "properties": { "name": { "type": "string" }, "accountNumber": { "type": "string" }, "provider": { "type": "string" } }
      },
      "DisbursementRequest": {
        "type": "object",
        "required": ["amount", "currency", "provider", "accountNumber"],
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string", "example": "TZS" },
          "provider": { "type": "string", "example": "Airtel" },
          "accountNumber": { "type": "string", "example": "255700000000" },
          "externalId": { "type": "string" }
        }
      },
      "CrossborderRequest": {
        "type": "object",
        "required": ["amount", "fromCurrency", "toCurrency", "provider", "accountNumber"],
        "properties": {
          "amount": { "type": "integer" },
          "fromCurrency": { "type": "string", "example": "TZS" },
          "toCurrency": { "type": "string", "example": "RWF" },
          "provider": { "type": "string", "example": "MTN" },
          "accountNumber": { "type": "string", "example": "250780000000" }
        }
      },
      "TransferRequest": {
        "type": "object",
        "required": ["amount", "currency", "recipient"],
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "recipient": { "type": "string", "description": "Recipient Ultraner account or email" }
        }
      },
      "EscrowRequest": {
        "type": "object",
        "required": ["amount", "currency", "recipient"],
        "properties": {
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "recipient": { "type": "string" },
          "description": { "type": "string" }
        }
      },
      "Escrow": {
        "type": "object",
        "properties": {
          "escrowCode": { "type": "string" },
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "status": { "type": "string", "enum": ["held", "released", "disputed", "refunded"] }
        }
      },
      "PaypalOrderRequest": {
        "type": "object",
        "required": ["amount", "currency"],
        "properties": {
          "amount": { "type": "number", "example": 25.0 },
          "currency": { "type": "string", "example": "USD" },
          "returnUrl": { "type": "string" },
          "cancelUrl": { "type": "string" }
        }
      },
      "StripeSessionRequest": {
        "type": "object",
        "required": ["amount", "currency"],
        "properties": {
          "amount": { "type": "integer", "description": "Amount in cents", "example": 2500 },
          "currency": { "type": "string", "example": "usd" },
          "successUrl": { "type": "string" },
          "cancelUrl": { "type": "string" }
        }
      },
      "Wallet": {
        "type": "object",
        "properties": {
          "balances": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": { "currency": { "type": "string" }, "available": { "type": "integer" }, "pending": { "type": "integer" } }
            }
          }
        }
      },
      "PaymentResponse": {
        "type": "object",
        "properties": {
          "reference": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "processing", "success", "failed"] },
          "amount": { "type": "integer" },
          "currency": { "type": "string" },
          "provider": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}