{
  "info": {
    "_postman_id": "switch-lock-v1-collection",
    "name": "SwitchLock API v1",
    "description": "Pre-built collection for the SwitchLock / Switchlock API. Set the four collection variables (apiKey, companyId, userId, baseUrl) and every request is ready to fire. All endpoints use x-api-key and x-company-id headers. Amounts are always in cents (e.g. $250.00 = 25000).",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.switchlock.co.zw",
      "type": "string",
      "description": "Base URL for all requests. Change to https://staging-api.switchlock.co.zw for staging or http://localhost:3005 for local development."
    },
    {
      "key": "apiKey",
      "value": "",
      "type": "string",
      "description": "Your API key. Format: sl_live_... — returned once from POST /v1/core/companies/api-keys."
    },
    {
      "key": "companyId",
      "value": "",
      "type": "string",
      "description": "Your company ID. Format: cmp_... — returned from POST /v1/core/companies."
    },
    {
      "key": "userId",
      "value": "",
      "type": "string",
      "description": "A user ID within your company. Format: usr_... — returned from POST /v1/identity/users."
    },
    {
      "key": "escrowId",
      "value": "",
      "type": "string",
      "description": "An escrow contract ID. Format: esc_... — returned after a payment is funded."
    },
    {
      "key": "paymentLinkId",
      "value": "",
      "type": "string",
      "description": "A payment link ID. Format: lnk_... — returned from POST /v1/payments/generate-escrow-payment-link."
    }
  ],
  "item": [
    {
      "name": "Auth",
      "description": "Authentication endpoints. Login to get a short-lived Bearer token, then use API keys for server-to-server calls.",
      "item": [
        {
          "name": "Login",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/auth/login",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "auth", "login"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"admin@acme.co.zw\",\n  \"password\": \"SuperSecret123!\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Authenticate as a company administrator. Returns a short-lived accessToken (JWT) and a refreshToken. Use the accessToken to create API keys, then switch to x-api-key for server-to-server calls."
          }
        },
        {
          "name": "Refresh Token",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/auth/refresh",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "auth", "refresh"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"refreshToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Exchange a valid refreshToken for a new accessToken without re-entering credentials."
          }
        },
        {
          "name": "Logout",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Authorization", "value": "Bearer {{accessToken}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/auth/logout",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "auth", "logout"]
            },
            "description": "Invalidate the current session and revoke the refresh token."
          }
        },
        {
          "name": "Get Current User",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{accessToken}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/auth/me",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "auth", "me"]
            },
            "description": "Return the profile of the currently authenticated user."
          }
        }
      ]
    },
    {
      "name": "Payments",
      "description": "Generate payment links, trigger buyer OTPs, accept payments into escrow, and fetch link state. The generate and accept flows are the core payment path.",
      "item": [
        {
          "name": "Generate Escrow Payment Link",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "x-idempotency-key", "value": "ide_replace_with_stable_uuid" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/generate-escrow-payment-link",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "generate-escrow-payment-link"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sellerId\": \"{{userId}}\",\n  \"amount\": 25000,\n  \"currency\": \"USD\",\n  \"externalReference\": \"ORDER-001\",\n  \"description\": \"Laptop stand purchase\",\n  \"items\": [\n    {\n      \"name\": \"Laptop Stand\",\n      \"quantity\": 1,\n      \"pricePerUnit\": 25000\n    }\n  ]\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Create a shareable checkout URL for a buyer to pay a specific seller. Amount is in cents. Returns a paymentUrl to send to the buyer and a paymentLinkId to track status. Requires a stable x-idempotency-key — use a UUID tied to your internal order ID."
          }
        },
        {
          "name": "Get Payment Link Details (public)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/link-details/:secureHash",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "link-details", ":secureHash"],
              "variable": [
                {
                  "key": "secureHash",
                  "value": "aB3xK9mN2p",
                  "description": "The short hash from the end of the paymentUrl."
                }
              ]
            },
            "description": "Public endpoint — no API key required. Returns the payment summary for the checkout page: seller name, currency, line items, and current status."
          }
        },
        {
          "name": "Request Checkout OTP (public)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/request-checkout-otp",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "request-checkout-otp"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"mobileNumber\": \"+263771234567\",\n  \"paymentLinkId\": \"{{paymentLinkId}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Called from the buyer's device. Sends a one-time PIN to the buyer's mobile number via WhatsApp (or SMS fallback). No API key required."
          }
        },
        {
          "name": "Accept Payment (public)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/accept-payment",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "accept-payment"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"paymentLinkId\": \"{{paymentLinkId}}\",\n  \"mobileNumber\": \"+263771234567\",\n  \"otp\": \"847201\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Called from the buyer's device. Validates the OTP and moves funds from the buyer's wallet into escrow. On success, escrow status transitions from PENDING to FUNDED. No API key required."
          }
        },
        {
          "name": "List Payment Links",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/payment-links?page=1&limit=20",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "payment-links"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "status", "value": "PENDING", "disabled": true },
                { "key": "sellerId", "value": "", "disabled": true }
              ]
            },
            "description": "Return a paginated list of all payment links for your company. Filter by status (PENDING, FUNDED, COMPLETED, EXPIRED, CANCELLED) or sellerId."
          }
        },
        {
          "name": "Get Payment Link by ID",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/payment-links/{{paymentLinkId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "payment-links", "{{paymentLinkId}}"]
            },
            "description": "Fetch the full record for a single payment link including its associated escrow contract ID once funded."
          }
        },
        {
          "name": "Cancel Payment Link",
          "request": {
            "method": "PATCH",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/payment-links/{{paymentLinkId}}/cancel",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "payment-links", "{{paymentLinkId}}", "cancel"]
            },
            "description": "Cancel a PENDING payment link. Cannot be undone once the link has been funded."
          }
        },
        {
          "name": "EFT Checkout Registration",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/eft/register-checkout",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "payments", "eft", "register-checkout"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"paymentLinkId\": \"{{paymentLinkId}}\",\n  \"provider\": \"PAYNOW\",\n  \"buyerEmail\": \"buyer@example.co.zw\",\n  \"buyerPhone\": \"+263771234567\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Register a payment link with the EFT provider (e.g. Paynow) and get a redirect URL for the buyer to complete payment via bank transfer or mobile money."
          }
        }
      ]
    },
    {
      "name": "Escrow",
      "description": "Manage escrow contracts. Escrow is automatically created when a payment link is funded. Use these endpoints to release funds, raise disputes, inspect the state machine, and handle milestone-based releases.",
      "item": [
        {
          "name": "List Escrow Contracts",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow?page=1&limit=20",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "status", "value": "FUNDED", "disabled": true },
                { "key": "buyerId", "value": "", "disabled": true },
                { "key": "sellerId", "value": "", "disabled": true }
              ]
            },
            "description": "Return all escrow contracts for your company, paginated. Filter by status: PENDING, FUNDED, RELEASED, DISPUTED, CANCELLED, REFUNDED."
          }
        },
        {
          "name": "Get Escrow by ID",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow/{{escrowId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow", "{{escrowId}}"]
            },
            "description": "Fetch the full escrow record including buyer, seller, timeline events, milestones (if any), and current status."
          }
        },
        {
          "name": "Release Escrow to Seller",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow/{{escrowId}}/release",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow", "{{escrowId}}", "release"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"Goods delivered and confirmed by buyer\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Release held funds to the seller. Call this from your server once you have confirmed the goods or service has been delivered. Transitions escrow status from FUNDED to RELEASED."
          }
        },
        {
          "name": "Raise Dispute",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow/{{escrowId}}/dispute",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow", "{{escrowId}}", "dispute"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"ITEM_NOT_RECEIVED\",\n  \"description\": \"The laptop stand was not delivered within the agreed 3-day window.\",\n  \"raisedBy\": \"{{userId}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Open a dispute on a FUNDED escrow. Funds remain locked until the dispute is resolved. Accepted reasons: ITEM_NOT_RECEIVED, ITEM_NOT_AS_DESCRIBED, SELLER_UNRESPONSIVE, OTHER."
          }
        },
        {
          "name": "Refund Escrow to Buyer",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow/{{escrowId}}/refund",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow", "{{escrowId}}", "refund"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"Dispute resolved in buyer's favour — item never shipped.\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Return held funds to the buyer. Can be called by an admin when a dispute is resolved in the buyer's favour, or to void a funded escrow before delivery begins."
          }
        },
        {
          "name": "Release Milestone",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/escrow/{{escrowId}}/milestones/:milestoneId/release",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "escrow", "{{escrowId}}", "milestones", ":milestoneId", "release"],
              "variable": [
                {
                  "key": "milestoneId",
                  "value": "mls_01HXYZ...",
                  "description": "ID of the milestone to release."
                }
              ]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"reason\": \"Phase 1 deliverable accepted\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Release the funds for a single milestone within a milestone-based escrow. The remaining milestones continue to be held."
          }
        }
      ]
    },
    {
      "name": "Identity",
      "description": "Create and manage users (buyers and sellers) within your company. Each user gets a ledger with USD and ZiG accounts on creation.",
      "item": [
        {
          "name": "Create User",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/identity/users",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "identity", "users"]
            },
            "body": {
              "mode": "formdata",
              "formdata": [
                { "key": "mobileNumber", "value": "+263771234567", "type": "text" },
                { "key": "idNumber", "value": "63-123456-A-00", "type": "text" },
                { "key": "firstName", "value": "Tendai", "type": "text" },
                { "key": "lastName", "value": "Moyo", "type": "text" },
                { "key": "email", "value": "tendai@example.co.zw", "type": "text" },
                { "key": "idDocument", "value": "", "type": "file", "disabled": true, "description": "Optional: national ID or passport scan (PDF/JPG)" }
              ]
            },
            "description": "Register a new user under your company. Automatically provisions a ledger with USD and ZiG accounts. The returned id is used as sellerId in payment link requests."
          }
        },
        {
          "name": "Get User by ID",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/identity/users/{{userId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "identity", "users", "{{userId}}"]
            },
            "description": "Fetch a user's profile including KYC level, linked accounts, and wallet balances."
          }
        },
        {
          "name": "List Users",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/identity/users?page=1&limit=20",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "identity", "users"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "kycLevel", "value": "BASIC", "disabled": true },
                { "key": "search", "value": "", "disabled": true }
              ]
            },
            "description": "Return all users for your company, paginated. Optionally filter by KYC level (NONE, BASIC, VERIFIED) or search by name, email, or mobile number."
          }
        },
        {
          "name": "Update User KYC Level",
          "request": {
            "method": "PATCH",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/identity/users/{{userId}}/kyc",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "identity", "users", "{{userId}}", "kyc"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"kycLevel\": \"VERIFIED\",\n  \"verifiedBy\": \"manual-review\",\n  \"notes\": \"ID document verified in person.\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Promote a user's KYC level. VERIFIED users have higher transaction limits. Accepted levels: NONE, BASIC, VERIFIED."
          }
        },
        {
          "name": "Delete User",
          "request": {
            "method": "DELETE",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/identity/users/{{userId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "identity", "users", "{{userId}}"]
            },
            "description": "Soft-delete a user. Their ledger and transaction history are retained for audit purposes. Cannot be deleted if they have a funded escrow in progress."
          }
        }
      ]
    },
    {
      "name": "Ledger",
      "description": "Query ledger accounts and transaction history. Ledgers are automatically created with each user and company. Read-only — balances move through payment and escrow operations, not direct ledger writes.",
      "item": [
        {
          "name": "Get Ledger by User",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/ledger/users/{{userId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "ledger", "users", "{{userId}}"]
            },
            "description": "Fetch the ledger and all account balances for a specific user. Returns USD and ZiG account IDs and current balances."
          }
        },
        {
          "name": "Get Account Balance",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/ledger/accounts/:accountId/balance",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "ledger", "accounts", ":accountId", "balance"],
              "variable": [
                {
                  "key": "accountId",
                  "value": "acc_01HUSD...",
                  "description": "The account ID from the user's ledger."
                }
              ]
            },
            "description": "Return the current balance and currency for a single ledger account."
          }
        },
        {
          "name": "List Transactions for Account",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/ledger/accounts/:accountId/transactions?page=1&limit=20",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "ledger", "accounts", ":accountId", "transactions"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "type", "value": "DEBIT", "disabled": true },
                { "key": "from", "value": "2026-01-01", "disabled": true },
                { "key": "to", "value": "2026-12-31", "disabled": true }
              ],
              "variable": [
                {
                  "key": "accountId",
                  "value": "acc_01HUSD..."
                }
              ]
            },
            "description": "Return paginated transaction history for a ledger account. Each entry includes amount, type (DEBIT/CREDIT), reference, and counterparty."
          }
        },
        {
          "name": "Get Company System Ledger",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/ledger/company/system",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "ledger", "company", "system"]
            },
            "description": "Fetch the company's system ledger — the GL accounts that hold escrow reserves, fee income, and tax liabilities."
          }
        },
        {
          "name": "List All Company Ledgers",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/ledger?page=1&limit=50",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "ledger"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "50" }
              ]
            },
            "description": "List all ledgers registered under the company — one per user plus the system ledger."
          }
        }
      ]
    },
    {
      "name": "Treasury",
      "description": "Initiate payouts from the company's system accounts to external bank accounts or mobile wallets, and query reserve balances.",
      "item": [
        {
          "name": "Initiate Payout",
          "request": {
            "method": "POST",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "x-idempotency-key", "value": "ide_replace_with_stable_uuid" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/treasury/payouts",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "treasury", "payouts"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"userId\": \"{{userId}}\",\n  \"amount\": 15000,\n  \"currency\": \"USD\",\n  \"destination\": {\n    \"type\": \"MOBILE_MONEY\",\n    \"provider\": \"ECOCASH\",\n    \"accountNumber\": \"+263771234567\"\n  },\n  \"description\": \"Seller payout for ORDER-001\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Move funds from a user's ledger account to an external destination (mobile money or bank account). Amount in cents. Destination types: MOBILE_MONEY, BANK_ACCOUNT."
          }
        },
        {
          "name": "Get Payout by ID",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/treasury/payouts/:payoutId",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "treasury", "payouts", ":payoutId"],
              "variable": [
                {
                  "key": "payoutId",
                  "value": "pay_01HXYZ...",
                  "description": "Payout ID from the initiate response."
                }
              ]
            },
            "description": "Check the current status and processing details of a payout. Statuses: PENDING, PROCESSING, COMPLETED, FAILED."
          }
        },
        {
          "name": "List Payouts",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/treasury/payouts?page=1&limit=20",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "treasury", "payouts"],
              "query": [
                { "key": "page", "value": "1" },
                { "key": "limit", "value": "20" },
                { "key": "status", "value": "COMPLETED", "disabled": true },
                { "key": "userId", "value": "", "disabled": true }
              ]
            },
            "description": "Return all payouts for the company, paginated. Filter by status or userId."
          }
        },
        {
          "name": "Get Reserve Balances",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/treasury/reserves",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "treasury", "reserves"]
            },
            "description": "Return the total escrow reserves held in USD and ZiG. Useful for reconciliation and reporting."
          }
        }
      ]
    },
    {
      "name": "Companies",
      "description": "Register companies, generate API keys, manage administrator accounts, and update company settings. The register endpoint is public — no API key needed.",
      "item": [
        {
          "name": "Register Company (public)",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies"]
            },
            "body": {
              "mode": "formdata",
              "formdata": [
                { "key": "name", "value": "Acme Marketplace", "type": "text" },
                { "key": "slug", "value": "acme", "type": "text" },
                { "key": "adminEmail", "value": "admin@acme.co.zw", "type": "text" },
                { "key": "adminFirstName", "value": "Jackson", "type": "text" },
                { "key": "adminLastName", "value": "Doe", "type": "text" },
                { "key": "adminPassword", "value": "SuperSecret123!", "type": "text" },
                { "key": "isMerchant", "value": "false", "type": "text" },
                { "key": "document", "value": "", "type": "file", "disabled": true, "description": "Optional: company registration certificate (PDF/JPG)" }
              ]
            },
            "description": "Public endpoint — no API key needed. Creates a company and its first administrator account. Sets up the system ledger with all GL accounts. Use isMerchant=false for marketplaces where buyers and sellers are different people."
          }
        },
        {
          "name": "Get Company",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies/{{companyId}}",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies", "{{companyId}}"]
            },
            "description": "Fetch the full company record including business model, status, and configuration."
          }
        },
        {
          "name": "Create API Key",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Authorization", "value": "Bearer {{accessToken}}" },
              { "key": "x-company-id", "value": "{{companyId}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies/api-keys",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies", "api-keys"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"name\": \"Production Server Key\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Generate a new API key for the company. Requires a Bearer token (from /v1/auth/login), not an existing API key. The key value is returned only once — store it immediately."
          }
        },
        {
          "name": "List API Keys",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies/api-keys",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies", "api-keys"]
            },
            "description": "List all API keys for the company. The raw key values are never returned — only name, creation date, and last-used date."
          }
        },
        {
          "name": "Revoke API Key",
          "request": {
            "method": "DELETE",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies/api-keys/:keyId",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies", "api-keys", ":keyId"],
              "variable": [
                {
                  "key": "keyId",
                  "value": "key_01HXYZ...",
                  "description": "The key record ID (not the key value itself)."
                }
              ]
            },
            "description": "Permanently revoke an API key. Any in-flight requests using this key will immediately start returning 401. Cannot be undone."
          }
        },
        {
          "name": "List Administrators",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-api-key", "value": "{{apiKey}}" },
              { "key": "x-company-id", "value": "{{companyId}}" }
            ],
            "url": {
              "raw": "{{baseUrl}}/v1/core/companies/administrators",
              "host": ["{{baseUrl}}"],
              "path": ["v1", "core", "companies", "administrators"]
            },
            "description": "Return all administrator accounts for the company."
          }
        }
      ]
    }
  ]
}