{
  "openapi": "3.0.3",
  "info": {
    "title": "Firehorse Merchant Integration API",
    "version": "1.0.0",
    "description": "Curated integration subset, reviewed 2026-11-22. Request fields are described per operation; this file is not a complete validation schema. Sign exact bytes and the backend /api/v1 path; public /transaction proxy prefix and query are excluded.",
    "x-documentation-updated": "2026-11-22"
  },
  "servers": [
    {
      "url": "https://firehorsepay.powerwebhub.com/transaction"
    }
  ],
  "externalDocs": {
    "url": "https://docs-firehorsepay.powerwebhub.com/authentication"
  },
  "components": {
    "securitySchemes": {
      "MerchantApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY"
      }
    }
  },
  "paths": {
    "/api/v1/checkout/sessions": {
      "post": {
        "operationId": "checkout_sessions",
        "summary": "Create a hosted checkout session",
        "description": "Create an expiring checkout URL on your server. The customer chooses an eligible payment method in Firehorse checkout.\n\nCreating a session does not create a transaction. A transaction is created when a method is selected.\n\nThis endpoint is not idempotent. Store and reuse the returned URL for the same checkout; do not create another session automatically after a timeout.\n\nmerchantReference is not accepted by this endpoint. Keep the checkout/order association on your server.\n\nTreat checkoutUrl as a short-lived capability. Do not place an API key in a browser URL.",
        "tags": [
          "Checkout"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "checkoutUrl": "https://firehorsepay.powerwebhub.com/transaction/api/v1/checkout/page?checkoutSession=EXAMPLE_CAPABILITY_TOKEN",
                  "expiresAt": "2026-11-22T12:30:00Z"
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "amount — required — Positive decimal amount in major units. Read it from your trusted order data.\ncurrency — required — Three-letter currency code.\nmode — optional — SANDBOX or LIVE. The server default is LIVE; always send SANDBOX when testing.\ncountry — optional — Two-letter payer country when known.\nreturnTo — optional — Absolute HTTP(S) return URL.",
                "additionalProperties": true
              },
              "example": {
                "amount": "10.00",
                "currency": "EUR",
                "mode": "SANDBOX",
                "returnTo": "https://merchant.example.com/payment-return"
              }
            }
          }
        }
      }
    },
    "/api/v1/transactions": {
      "post": {
        "operationId": "create_transaction",
        "summary": "Create a payment or payout",
        "description": "Validate and persist an operation, route it and enqueue provider initiation. A 201 response confirms creation; the provider result may arrive later.\n\nAn initial CREATED response can have no redirectUrl. Poll the owned transaction or handle its webhook until initiation finishes.\n\nIf redirectUrl is present, send the payer to the provider checkout. A browser return is not proof of payment.\n\nA duplicate create returns 409 rather than the original 201 body. Recover the original operation using your persisted transaction ID/reference; do not issue another operation with a new key.\n\nProvider selection is normally handled by routing. Only pin providerCode for a deliberate integration/test scope.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Persist a UUID per logical operation. This header or body idempotencyKey is required.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "id": 100123,
                  "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
                  "type": "DEPOSIT",
                  "status": "CREATED",
                  "amount": 10,
                  "currency": "EUR",
                  "merchantReference": "order-example-001",
                  "redirectUrl": null
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "type — required — DEPOSIT or PAYOUT. Payout requires a supporting provider, capability and recipient fields.\namount — required — Positive decimal major units; prefer decimal strings.\ncurrency — required — Three-letter currency code supported in the selected scope.\npaymentMethod — required — Enabled internal method, for example CARD.\nmerchantReference — required — Unique reference for this logical order or operation.\nIdempotency-Key — required — UUID header, or idempotencyKey in the request body. Persist it before sending.\nmode — optional — SANDBOX or LIVE; omitted mode defaults to LIVE.\nregionId — optional — Your merchant region ID. It is not a global region ID.\ncustomerEmail / customerFields — conditional — Valid payer email and fields required by your capability/provider.\nsuccessUrl / failUrl — optional — Absolute return URLs. Valid merchant defaults may be used.\nflow — optional — REDIRECT by default; H2H requires a suitable integration.",
                "additionalProperties": true
              },
              "example": {
                "type": "DEPOSIT",
                "amount": "10.00",
                "currency": "EUR",
                "paymentMethod": "CARD",
                "merchantReference": "order-example-001",
                "mode": "SANDBOX",
                "customerEmail": "sandbox-payer@example.com"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "list_transactions",
        "summary": "List transactions",
        "description": "List transactions scoped to your authenticated merchant, with supported filters and pagination.\n\nQuery parameters are excluded from the HMAC canonical path.\n\nUse the returned pagination metadata; do not infer that one page is the complete transaction history.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "DEPOSIT, PAYOUT or REFUND.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Canonical transaction status.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page index and page size.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Page index and page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "content": [
                    {
                      "id": 100123,
                      "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
                      "type": "DEPOSIT",
                      "status": "CREATED",
                      "amount": 10,
                      "currency": "EUR",
                      "merchantReference": "order-example-001",
                      "redirectUrl": null
                    }
                  ],
                  "number": 0,
                  "size": 20,
                  "totalElements": 1
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        }
      }
    },
    "/api/v1/transactions/{idOrUuid}": {
      "get": {
        "operationId": "get_transaction",
        "summary": "Retrieve a transaction",
        "description": "Read the current owned transaction by numeric ID or UUID. Use the terminal status and credited amount to update your order.\n\nTransactions owned by another merchant return 404.\n\nCREATED, PROCESSING and MANUAL_REVIEW require further handling. Do not mark them as paid.\n\nUse sensible polling intervals and backoff rather than a tight loop.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "idOrUuid",
            "in": "path",
            "required": true,
            "description": "Numeric transaction ID or UUID returned by the API.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "id": 100123,
                  "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
                  "type": "DEPOSIT",
                  "status": "SUCCESS",
                  "amount": 10,
                  "currency": "EUR",
                  "merchantReference": "order-example-001",
                  "redirectUrl": null,
                  "providerAmount": 10,
                  "providerCurrency": "EUR",
                  "actualAmount": 10,
                  "actualCurrency": "EUR",
                  "creditedAmount": 10,
                  "creditedCurrency": "EUR",
                  "amountUpdateType": "EXACT"
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        }
      }
    },
    "/api/v1/transactions/{id}/refund": {
      "post": {
        "operationId": "refund",
        "summary": "Record a full refund action",
        "description": "Apply the supported full-refund action to an owned SUCCESS transaction. The amount must equal creditedAmount, falling back to the legacy amount.\n\nThis action updates Firehorse transaction state. Do not assume a separate provider refund HTTP call unless the specific provider workflow supports and confirms it.\n\nVerify the amount/currency and authorization before issuing the action. Repeated actions are restricted by transaction state.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric owned transaction ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "id": 100123,
                  "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
                  "type": "DEPOSIT",
                  "status": "REFUNDED",
                  "amount": 10,
                  "currency": "EUR",
                  "merchantReference": "order-example-001",
                  "redirectUrl": null
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "amount — required — Exactly the refundable credited amount. Partial refunds are rejected.\nreason — required — Reason for the action.",
                "additionalProperties": true
              },
              "example": {
                "amount": "10.00",
                "reason": "Customer requested refund"
              }
            }
          }
        }
      }
    },
    "/api/v1/transactions/{id}/void": {
      "post": {
        "operationId": "void",
        "summary": "Cancel a non-terminal transaction",
        "description": "Apply cancellation when the transaction permits the transition. Terminal transactions cannot be voided.\n\nInspect the current state first. An unsupported transition returns a conflict.\n\nA local cancellation is not a blanket guarantee that a provider-side collection or transfer was reversed.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Numeric owned transaction ID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "id": 100123,
                  "uuid": "6f1c0c8e-0d62-4a0f-a913-57c6e45d7c21",
                  "type": "DEPOSIT",
                  "status": "CANCELED",
                  "amount": 10,
                  "currency": "EUR",
                  "merchantReference": "order-example-001",
                  "redirectUrl": null
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "reason — required — Reason for cancellation.",
                "additionalProperties": true
              },
              "example": {
                "reason": "Order cancelled"
              }
            }
          }
        }
      }
    },
    "/api/v1/transactions/{idOrUuid}/callbacks": {
      "get": {
        "operationId": "callbacks",
        "summary": "Read provider callback history",
        "description": "Inspect received provider callbacks linked to an owned transaction. The response contains safe summaries, processing state and duplicate counts.\n\nProvider callbacks are inbound to Firehorse. They are distinct from outbound merchant webhooks.\n\nCallback summary amounts are provider-reported raw values; use the transaction amount breakdown for authoritative credited amounts.\n\nHeaders and signature material are not part of this response. An empty history does not prove that a payment failed.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "idOrUuid",
            "in": "path",
            "required": true,
            "description": "Owned transaction ID or UUID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "example": [
                  {
                    "receivedAt": "2026-11-22T12:00:00Z",
                    "providerCode": "example_sandbox",
                    "status": "DONE",
                    "processedAt": "2026-11-22T12:00:01Z",
                    "payloadSummary": {
                      "status": "success",
                      "amount": "10.00",
                      "currency": "EUR"
                    },
                    "duplicateCount": 0,
                    "lastDuplicateAt": null
                  }
                ]
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        }
      }
    },
    "/api/v1/transactions/{idOrUuid}/trace": {
      "get": {
        "operationId": "trace",
        "summary": "Inspect the transaction trace",
        "description": "Read the owned transaction timeline for routing, initiation, provider interaction and webhook delivery diagnostics.\n\nThe shape of individual events depends on the recorded source. The empty events array here is an illustrative example.\n\nA missing event means no matching evidence was recorded; it does not certify a successful stage.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "idOrUuid",
            "in": "path",
            "required": true,
            "description": "Numeric owned transaction ID or UUID.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                },
                "example": {
                  "transactionId": 100123,
                  "merchantReference": "order-example-001",
                  "providerCode": "example_sandbox",
                  "currentStatus": "CREATED",
                  "traceId": "example-trace",
                  "events": []
                }
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        }
      }
    },
    "/api/v1/providers/payment-options": {
      "get": {
        "operationId": "payment_options",
        "summary": "List payment provider candidates",
        "description": "Read provider catalog candidates for a direct integration scope. This list is not final routing eligibility or a provider readiness result.\n\nAn empty list means no catalog candidates for this scope. A non-empty list does not certify current routing eligibility, external credentials, FX conversion or provider health.\n\nCall from your server with signed headers. Query parameters are excluded from the HMAC path.\n\nHosted checkout handles method eligibility separately and routing selects the provider. Do not use the legacy cashier options endpoint as a signed-header-only merchant API.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "MerchantApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-TIMESTAMP",
            "in": "header",
            "required": true,
            "description": "Unix seconds, within five minutes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-NONCE",
            "in": "header",
            "required": true,
            "description": "Fresh unique nonce per HTTP attempt.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-SIGNATURE",
            "in": "header",
            "required": true,
            "description": "HMAC-SHA256 canonical request; see authentication guide.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "description": "Requested major-unit amount.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "description": "Three-letter currency code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "paymentMethod",
            "in": "query",
            "required": true,
            "description": "Internal payment method, for example CARD.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": true,
            "description": "DEPOSIT or PAYOUT.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Defaults to LIVE. Explicitly send SANDBOX while testing.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "regionId",
            "in": "query",
            "required": false,
            "description": "Merchant region ID for regional filtering.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Illustrative successful response. Additional response fields may be present.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "example": []
              }
            }
          },
          "default": {
            "description": "Error response. Inspect HTTP status and response details; do not blindly retry a create."
          }
        }
      }
    }
  }
}