{
  "info": {
    "_postman_id": "e5f6a7b8-6666-4d10-8e2e-topifydocs001",
    "name": "Topify API — Docs (localhost:3000/docs)",
    "description": "Postman collection generated from the **Topify API documentation** page (`/docs`).\n\n> **Note:** `http://localhost:3000/docs` is the docs **website**. API requests use `{{api_base_url}}` (your Laravel backend), e.g. `https://apipay.topify.ng` or `http://127.0.0.1:8000`.\n\n## Response format\nAll JSON responses: `{ status, message, data, errors }`. Money is in **kobo**.\n\n## Auth\n| Surface | Header |\n|---------|--------|\n| Merchant API v1 (`/api/v1/*`) | `Authorization: Bearer sk_test_…` → `{{merchant_api_key}}` |\n| Dashboard API (`/api/*`) | `Authorization: Bearer …` → `{{user_token}}` from login |\n\n## Bank codes\n- PalmPay `20946` · Monnify `30901` · 9PSB `20897` (disabled)\n\n## Quick start\n1. Import this collection + `TopifyGateway.Docs.postman_environment.json`\n2. Set `api_base_url`\n3. Run **Setup** folder (Login → API credentials → Business status)\n4. Run **Merchant API v1** or **Dashboard API** folders\n\n## Webhooks (outbound)\nTopify POSTs to your URL with `X-Topify-Signature` (HMAC-SHA512). Events: `customer.virtual_account.created`, `charge.success`, `wallet.funded`, etc.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "api_base_url", "value": "https://apipay.topify.ng", "type": "string" },
    { "key": "user_token", "value": "", "type": "string" },
    { "key": "merchant_api_key", "value": "", "type": "string" },
    { "key": "business_id", "value": "", "type": "string" },
    { "key": "customer_code", "value": "CUS-ABC123", "type": "string" },
    { "key": "provider", "value": "palmpay", "type": "string" },
    { "key": "reference", "value": "TXN-ABC123", "type": "string" },
    { "key": "customer_email", "value": "buyer@example.com", "type": "string" },
    { "key": "customer_name", "value": "Ada Okafor", "type": "string" },
    { "key": "customer_phone", "value": "08012345678", "type": "string" },
    { "key": "identity_document_type", "value": "bvn", "type": "string" },
    { "key": "identity_number", "value": "22334455667", "type": "string" }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [{ "key": "token", "value": "{{user_token}}", "type": "string" }]
  },
  "item": [
    {
      "name": "Setup",
      "description": "Authenticate and load variables before calling documented endpoints.",
      "item": [
        {
          "name": "Login (Dashboard — save user_token)",
          "request": {
            "method": "POST",
            "auth": { "type": "noauth" },
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{api_base_url}}/api/auth/login",
              "host": ["{{api_base_url}}"],
              "path": ["api", "auth", "login"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"user@topify.test\",\n  \"password\": \"password\"\n}"
            },
            "description": "Dashboard API auth (Sanctum). Docs → Authentication → Dashboard API."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const j = pm.response.json();",
                  "if (j?.data?.token) {",
                  "  pm.collectionVariables.set('user_token', j.data.token);",
                  "  pm.environment.set('user_token', j.data.token);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "Get API credentials (save merchant_api_key)",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/developer",
              "host": ["{{api_base_url}}"],
              "path": ["api", "developer"]
            },
            "description": "Docs → Developer settings. Saves test secret key for Merchant API v1."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const j = pm.response.json();",
                  "const key = j?.data?.test_secret_key || j?.data?.live_secret_key;",
                  "if (key) {",
                  "  pm.collectionVariables.set('merchant_api_key', key);",
                  "  pm.environment.set('merchant_api_key', key);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "Get business status (save business_id)",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/business/status",
              "host": ["{{api_base_url}}"],
              "path": ["api", "business", "status"]
            },
            "description": "Required for virtual account reserve (`businessId`)."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const j = pm.response.json();",
                  "const id = j?.data?.business?.business_id;",
                  "if (id) {",
                  "  pm.collectionVariables.set('business_id', String(id));",
                  "  pm.environment.set('business_id', String(id));",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "Preview fee — virtual account inbound",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/fees/preview?amount=100000&type=virtual_account",
              "host": ["{{api_base_url}}"],
              "path": ["api", "fees", "preview"],
              "query": [
                { "key": "amount", "value": "100000", "description": "Kobo (₦1,000)" },
                { "key": "type", "value": "virtual_account" }
              ]
            },
            "description": "Docs → Virtual accounts — inbound transfer fee preview."
          }
        }
      ]
    },
    {
      "name": "Merchant API v1 — Customers",
      "description": "Docs → Customers. Auth: `Bearer {{merchant_api_key}}`",
      "auth": {
        "type": "bearer",
        "bearer": [{ "key": "token", "value": "{{merchant_api_key}}", "type": "string" }]
      },
      "item": [
        {
          "name": "Create customer",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{api_base_url}}/api/v1/customers",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "customers"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{customer_email}}\",\n  \"name\": \"{{customer_name}}\",\n  \"phone\": \"{{customer_phone}}\"\n}"
            },
            "description": "POST /api/v1/customers — Idempotent on email."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const j = pm.response.json();",
                  "if (j?.data?.customer_code) {",
                  "  pm.collectionVariables.set('customer_code', j.data.customer_code);",
                  "  pm.environment.set('customer_code', j.data.customer_code);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "List customers",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/v1/customers?per_page=15",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "customers"],
              "query": [{ "key": "per_page", "value": "15" }]
            },
            "description": "GET /api/v1/customers"
          }
        },
        {
          "name": "Get customer",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/v1/customers/{{customer_code}}",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "customers", "{{customer_code}}"]
            },
            "description": "GET /api/v1/customers/{customer_code}"
          }
        }
      ]
    },
    {
      "name": "Merchant API v1 — Virtual accounts",
      "description": "Docs → Virtual accounts → Merchant API (v1). Bank codes: PalmPay 20946, Monnify 30901.",
      "auth": {
        "type": "bearer",
        "bearer": [{ "key": "token", "value": "{{merchant_api_key}}", "type": "string" }]
      },
      "item": [
        {
          "name": "Reserve virtual accounts",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{api_base_url}}/api/v1/virtual-accounts/reserve",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "virtual-accounts", "reserve"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"email\": \"{{customer_email}}\",\n  \"name\": \"{{customer_name}}\",\n  \"phoneNumber\": \"{{customer_phone}}\",\n  \"bankCode\": [\"20946\", \"30901\"],\n  \"businessId\": \"{{business_id}}\",\n  \"identity_document_type\": \"bvn\",\n  \"identity_number\": \"22334455667\",\n  \"useLive\": false\n}"
            },
            "description": "POST /api/v1/virtual-accounts/reserve — Idempotent per provider + email + name + phone. Inbound payments credit wallet net of fee."
          },
          "event": [
            {
              "listen": "test",
              "script": {
                "exec": [
                  "const j = pm.response.json();",
                  "if (j?.data?.customer?.customer_code) {",
                  "  pm.collectionVariables.set('customer_code', j.data.customer.customer_code);",
                  "  pm.environment.set('customer_code', j.data.customer.customer_code);",
                  "}"
                ],
                "type": "text/javascript"
              }
            }
          ]
        },
        {
          "name": "List customer accounts",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/v1/virtual-accounts/customer/{{customer_code}}",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "virtual-accounts", "customer", "{{customer_code}}"]
            },
            "description": "GET /api/v1/virtual-accounts/customer/{customer_code}"
          }
        }
      ]
    },
    {
      "name": "Merchant API v1 — Transactions",
      "description": "Docs → Transactions",
      "auth": {
        "type": "bearer",
        "bearer": [{ "key": "token", "value": "{{merchant_api_key}}", "type": "string" }]
      },
      "item": [
        {
          "name": "Verify transaction",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/v1/transactions/verify/{{reference}}",
              "host": ["{{api_base_url}}"],
              "path": ["api", "v1", "transactions", "verify", "{{reference}}"]
            },
            "description": "GET /api/v1/transactions/verify/{reference} — amount & fee in kobo."
          }
        }
      ]
    },
    {
      "name": "Dashboard API — Virtual accounts (Sanctum)",
      "description": "Docs → Virtual accounts → Dashboard API. Uses {{user_token}} from login.",
      "auth": {
        "type": "bearer",
        "bearer": [{ "key": "token", "value": "{{user_token}}", "type": "string" }]
      },
      "item": [
        {
          "name": "List your reserved accounts",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/virtual-accounts",
              "host": ["{{api_base_url}}"],
              "path": ["api", "virtual-accounts"]
            },
            "description": "GET /api/virtual-accounts"
          }
        },
        {
          "name": "Provider sandbox modes",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/virtual-accounts/provider-modes",
              "host": ["{{api_base_url}}"],
              "path": ["api", "virtual-accounts", "provider-modes"]
            },
            "description": "GET /api/virtual-accounts/provider-modes — Docs → Sandbox & live"
          }
        },
        {
          "name": "Provision reserved account",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "url": {
              "raw": "{{api_base_url}}/api/virtual-accounts/provision",
              "host": ["{{api_base_url}}"],
              "path": ["api", "virtual-accounts", "provision"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"provider\": \"palmpay\",\n  \"customer_name\": \"Jane Doe\",\n  \"email\": \"jane@example.com\",\n  \"phone\": \"08012345678\",\n  \"identity_document_type\": \"bvn\",\n  \"identity_number\": \"22334455667\"\n}"
            },
            "description": "POST /api/virtual-accounts/provision — PalmPay requires BVN/NIN/CAC."
          }
        },
        {
          "name": "Get account by provider",
          "request": {
            "method": "GET",
            "header": [{ "key": "Accept", "value": "application/json" }],
            "url": {
              "raw": "{{api_base_url}}/api/virtual-accounts/{{provider}}",
              "host": ["{{api_base_url}}"],
              "path": ["api", "virtual-accounts", "{{provider}}"]
            },
            "description": "GET /api/virtual-accounts/{provider} — e.g. palmpay, monnify"
          }
        }
      ]
    }
  ]
}