{
  "info": {
    "_postman_id": "f1reh0rse-merch4nt-ap1-c0llect10n",
    "name": "Firehorse Merchant API",
    "description": "Merchant API v1. Server-side signed calls. Configure a private apiKey environment variable. Sandbox creates are explicit. Keep idempotencyKey and merchantReference stable for retries; reset both for a new logical operation. API responses and examples do not certify a completed payment.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://firehorsepay.powerwebhub.com/transaction"
    },
    {
      "key": "apiKey",
      "value": "PASTE_YOUR_API_KEY"
    },
    {
      "key": "merchantReference",
      "value": "order-example-001"
    },
    {
      "key": "transactionId",
      "value": "100123"
    },
    {
      "key": "idempotencyKey",
      "value": ""
    }
  ],
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "const apiKey = pm.variables.get('apiKey');",
          "if (!apiKey || apiKey === 'PASTE_YOUR_API_KEY') throw new Error('Set a private merchant apiKey');",
          "const timestamp = Math.floor(Date.now() / 1000).toString();",
          "const nonce = pm.variables.replaceIn('{{$guid}}');",
          "const resolve = value => pm.variables.replaceIn(pm.variables.replaceIn(value));",
          "const pathname = value => value.replace(/^https?:\\/\\/[^/]+/i, '').split(/[?#]/)[0] || '/';",
          "const basePath = pathname(resolve(pm.variables.get('baseUrl'))).replace(/\\/$/, '');",
          "const publicPath = pathname(resolve(pm.request.url.toString()));",
          "const path = (basePath && publicPath.startsWith(basePath + '/') ? publicPath.slice(basePath.length) : publicPath).replace(/^\\/+/, '/');",
          "if (!path.startsWith('/api/v1/')) throw new Error('Unexpected backend signing path');",
          "if (pm.request.method === 'POST' && path === '/api/v1/transactions') {",
          "  let key = pm.variables.get('idempotencyKey');",
          "  if (!key) { key = pm.variables.replaceIn('{{$guid}}'); pm.collectionVariables.set('idempotencyKey', key); }",
          "  pm.request.headers.upsert({ key: 'Idempotency-Key', value: key });",
          "}",
          "const body = pm.request.body && pm.request.body.mode === 'raw' ? resolve(pm.request.body.raw) : '';",
          "if (pm.request.body && pm.request.body.mode === 'raw') pm.request.body.update(body);",
          "const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);",
          "const canonical = [pm.request.method, path, timestamp, nonce, bodyHash].join('\\n');",
          "const signature = CryptoJS.HmacSHA256(canonical, apiKey).toString(CryptoJS.enc.Hex);",
          "pm.request.headers.upsert({ key: 'X-API-KEY', value: apiKey });",
          "pm.request.headers.upsert({ key: 'X-TIMESTAMP', value: timestamp });",
          "pm.request.headers.upsert({ key: 'X-NONCE', value: nonce });",
          "pm.request.headers.upsert({ key: 'X-SIGNATURE', value: signature });",
          "pm.request.headers.upsert({ key: 'Content-Type', value: 'application/json' });"
        ]
      }
    }
  ],
  "item": [
    {
      "name": "Create Hosted Checkout Session (Sandbox)",
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"amount\": \"10.00\",\n  \"currency\": \"EUR\",\n  \"mode\": \"SANDBOX\",\n  \"returnTo\": \"https://merchant.example.com/payment-return\"\n}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/v1/checkout/sessions",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "checkout",
            "sessions"
          ]
        }
      }
    },
    {
      "name": "Create Deposit",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Idempotency-Key",
            "value": "{{idempotencyKey}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"type\": \"DEPOSIT\",\n  \"amount\": 10.00,\n  \"currency\": \"EUR\",\n  \"paymentMethod\": \"CARD\",\n  \"merchantReference\": \"{{merchantReference}}\",\n  \"mode\": \"SANDBOX\",\n  \"successUrl\": \"https://example.com/success\",\n  \"failUrl\": \"https://example.com/fail\"\n}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions"
          ]
        }
      }
    },
    {
      "name": "Create Withdrawal (Payout)",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Idempotency-Key",
            "value": "{{idempotencyKey}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"type\": \"PAYOUT\",\n  \"amount\": 10.00,\n  \"currency\": \"EUR\",\n  \"paymentMethod\": \"BANK_TRANSFER\",\n  \"merchantReference\": \"{{merchantReference}}\",\n  \"mode\": \"SANDBOX\"\n}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions"
          ]
        }
      }
    },
    {
      "name": "Get Transaction Status",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions/{{transactionId}}",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions",
            "{{transactionId}}"
          ]
        }
      }
    },
    {
      "name": "List Transactions",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions?page=0&size=20",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions"
          ],
          "query": [
            {
              "key": "page",
              "value": "0"
            },
            {
              "key": "size",
              "value": "20"
            },
            {
              "key": "status",
              "value": "SUCCESS",
              "disabled": true
            },
            {
              "key": "type",
              "value": "DEPOSIT",
              "disabled": true
            },
            {
              "key": "search",
              "value": "",
              "disabled": true
            }
          ]
        }
      }
    },
    {
      "name": "Refund Transaction",
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"amount\": 10.00,\n  \"reason\": \"Customer requested a full refund\"\n}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions/{{transactionId}}/refund",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions",
            "{{transactionId}}",
            "refund"
          ]
        }
      }
    },
    {
      "name": "Transaction Callbacks",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions/{{transactionId}}/callbacks",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions",
            "{{transactionId}}",
            "callbacks"
          ]
        }
      }
    },
    {
      "name": "Transaction Trace",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/v1/transactions/{{transactionId}}/trace",
          "host": [
            "{{baseUrl}}"
          ],
          "path": [
            "api",
            "v1",
            "transactions",
            "{{transactionId}}",
            "trace"
          ]
        }
      }
    }
  ]
}
