{
  "info": {
    "_postman_id": "kanacash-partner-api-v1",
    "name": "KanaCash Partner API",
    "description": "KanaCash Partner API collection. Flow: 1) Get Token, 2) Quote, 3) Confirm with quoteId. The fee is locked at quote time.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "baseUrl", "value": "https://core.kanacash.com/api/v1", "type": "string", "description": "Production: https://core.kanacash.com/api/v1 | Sandbox: https://sandbox.kanacash.com/api/v1" },
    { "key": "clientId", "value": "", "type": "string", "description": "Your partner Client ID (UUID)" },
    { "key": "clientSecret", "value": "", "type": "string", "description": "Your partner Client Secret" },
    { "key": "accessToken", "value": "", "type": "string", "description": "Auto-filled by Get Access Token" },
    { "key": "collectionQuoteId", "value": "", "type": "string", "description": "Auto-filled by Quote Collection" },
    { "key": "disbursementQuoteId", "value": "", "type": "string", "description": "Auto-filled by Quote Disbursement" },
    { "key": "lastCollectionRef", "value": "", "type": "string" },
    { "key": "lastDisbursementRef", "value": "", "type": "string" }
  ],
  "item": [
    {
      "name": "1. Authentication",
      "item": [
        {
          "name": "Get Access Token",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "var json = pm.response.json();",
                  "if (json.access_token) {",
                  "    pm.collectionVariables.set('accessToken', json.access_token);",
                  "    console.log('Token saved. Expires in: ' + json.expires_in + 's');",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{baseUrl}}/partner/auth/token",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "auth", "token"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"client_id\": \"{{clientId}}\",\n  \"client_secret\": \"{{clientSecret}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "Exchange your client ID and secret for a Bearer token. Valid for 1 hour. Token is saved automatically."
          }
        }
      ]
    },
    {
      "name": "2. Account",
      "item": [
        {
          "name": "Lookup Account by Phone",
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/account/:phone",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "account", ":phone"],
              "variable": [{ "key": "phone", "value": "0881234567" }]
            },
            "description": "Check if a KanaCash user exists before initiating a transaction."
          }
        },
        {
          "name": "Get Partner Balance",
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/balance",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "balance"]
            },
            "description": "Returns your current partner wallet balance in LRD and USD."
          }
        }
      ]
    },
    {
      "name": "3. Collection",
      "item": [
        {
          "name": "Step 1 — Quote Collection",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "var json = pm.response.json();",
                  "if (json.data && json.data.quoteId) {",
                  "    pm.collectionVariables.set('collectionQuoteId', json.data.quoteId);",
                  "    console.log('quoteId saved: ' + json.data.quoteId);",
                  "    console.log('Fee: ' + json.data.fee + ', Total debit: ' + json.data.totalDebit);",
                  "    console.log('Sufficient balance: ' + json.data.sufficientBalance);",
                  "    if (!json.data.sufficientBalance) console.warn('WARNING: User has insufficient balance!');",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/collection/quote",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "collection", "quote"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"0881234567\",\n  \"amount\": 500.00,\n  \"currency\": \"LRD\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "STEP 1: Get a fee quote before collecting. Returns a quoteId valid for 10 minutes. The quoteId is saved automatically. Check sufficientBalance before proceeding to Step 2."
          }
        },
        {
          "name": "Step 2 — Confirm Collection",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "var json = pm.response.json();",
                  "if (json.data && json.data.referenceId) {",
                  "    pm.collectionVariables.set('lastCollectionRef', json.data.referenceId);",
                  "    console.log('Collection request sent. referenceId: ' + json.data.referenceId);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/collection/request",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "collection", "request"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"quoteId\": \"{{collectionQuoteId}}\",\n  \"externalId\": \"ORDER-001\",\n  \"note\": \"Payment for Order #001\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "STEP 2: Confirm the collection using the quoteId from Step 1. The fee is locked at the quote price. The user receives a push notification to approve or decline within 10 minutes."
          }
        },
        {
          "name": "Get Collection Status",
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/collection/:referenceId",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "collection", ":referenceId"],
              "variable": [{ "key": "referenceId", "value": "{{lastCollectionRef}}" }]
            },
            "description": "Poll the status of a collection request. Use webhooks for real-time updates instead."
          }
        }
      ]
    },
    {
      "name": "4. Disbursement",
      "item": [
        {
          "name": "Step 1 — Quote Disbursement",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "var json = pm.response.json();",
                  "if (json.data && json.data.quoteId) {",
                  "    pm.collectionVariables.set('disbursementQuoteId', json.data.quoteId);",
                  "    console.log('quoteId saved: ' + json.data.quoteId);",
                  "    console.log('Fee: ' + json.data.fee + ', Total debit: ' + json.data.totalDebit);",
                  "    console.log('Sufficient balance: ' + json.data.sufficientBalance);",
                  "    if (!json.data.sufficientBalance) console.warn('WARNING: Insufficient partner balance!');",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/disbursement/quote",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "disbursement", "quote"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"phone\": \"0771234567\",\n  \"amount\": 200.00,\n  \"currency\": \"USD\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "STEP 1: Get a fee quote before disbursing. Returns a quoteId valid for 10 minutes. Check sufficientBalance before proceeding to Step 2."
          }
        },
        {
          "name": "Step 2 — Confirm Transfer",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "var json = pm.response.json();",
                  "if (json.data && json.data.referenceId) {",
                  "    pm.collectionVariables.set('lastDisbursementRef', json.data.referenceId);",
                  "    console.log('Transfer completed. TxID: ' + json.data.transactionId);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/disbursement/transfer",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "disbursement", "transfer"]
            },
            "body": {
              "mode": "raw",
              "raw": "{\n  \"quoteId\": \"{{disbursementQuoteId}}\",\n  \"externalId\": \"PAYOUT-001\",\n  \"note\": \"Commission payment\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "description": "STEP 2: Execute the transfer using the quoteId from Step 1. The fee is locked at the quote price. Completes immediately."
          }
        },
        {
          "name": "Get Disbursement Status",
          "request": {
            "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "{{accessToken}}", "type": "string" }] },
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/partner/v1/disbursement/:referenceId",
              "host": ["{{baseUrl}}"],
              "path": ["partner", "v1", "disbursement", ":referenceId"],
              "variable": [{ "key": "referenceId", "value": "{{lastDisbursementRef}}" }]
            },
            "description": "Retrieve details and final status of a disbursement."
          }
        }
      ]
    }
  ]
}