--- updatedAt: 2026-04-22T09:39:55.000Z agentTools: projectIndex: https://docs.finmid.com/llms.txt --- # Get Capital Max State This endpoint returns the Capital Max state for a Business. Capital Max allows a business to request additional capital beyond their standard funding. The response includes Capital Max configuration and a list of past and current applications ordered by `appliedAt DESC` The optional `application_status` query parameter allows filtering applications by their current status. The lifecycle of a Capital Max Application is as follows: - `IN_REVIEW`: the initial state of the resource. The associated offer group is deactivated to block the business from accepting previously generated offers. At any given time, there can be only one Funding Application in the `IN_REVIEW` state. - `APPROVED`: a new offer group has been generated with higher funding limits, becoming the active offer group. - `REJECTED`: the application was rejected and the offer group might or might not have been re-activated. > Hint: query the Active Offer Group to find out if it has been re-activated or not. # OpenAPI definition ````json { "openapi": "3.0.3", "info": { "title": "CAPITAL API", "version": "v1.0" }, "servers": [ { "url": "https://sandbox.finmid.com", "description": "Sandbox" }, { "url": "https://api.finmid.com", "description": "Live" } ], "tags": [ { "name": "Capital Max", "description": "Endpoints for managing Capital Max applications." } ], "security": [ { "apiKeyScheme": [] } ], "paths": { "/api/v1/capital/businesses": { "post": { "tags": [ "Business" ], "operationId": "create-business", "summary": "Create Business", "description": "In order to access pre-approved Offers for Businesses, Platforms must first share non-PI data. This data is used to generate Offers, confirm receiving bank accounts with Businesses, and support the 2FA process used to accept Offers.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "currency", "legal_address" ], "properties": { "id": { "$ref": "#/paths/~1api~1v1~1capital~1payment-batches~1{batch_id}/get/parameters/0/schema" }, "currency": { "description": "Three-letter currency code (ISO 4217). Supported currencies `EUR`, `DKK`, `SEK` and `POL`. Must match the Business's registered currency.", "type": "string", "example": "EUR" }, "bank_account": { "type": "object", "description": "Entity for sharing business bank account details.", "properties": { "account_number_ending": { "description": "Last N digits of the Business’s bank account number (typically the last four).", "type": "string", "example": "9675" } } }, "legal_representative": { "type": "object", "properties": { "phone_ending": { "description": "Last N digits of the business’s contact phone (usually last four).", "type": "string", "example": "1234" } } }, "legal_address": { "type": "object", "description": "Entity for business address details.", "required": [ "country" ], "properties": { "country": { "description": "Country where the Business operates.", "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}~1credits/get/responses/200/content/application~1json/schema/properties/data/items/properties/country/allOf/0" } } }, "partnership_started_date": { "description": "Date when the Business started its partnership with the Platform.", "type": "string", "format": "date", "example": "2020-01-01" }, "founding_date": { "description": "Date when the Business was established.", "type": "string", "format": "date", "example": "2020-01-01" }, "metadata": { "type": "object", "description": "Contains a set of flexible, custom key-value pairs. Used for sharing extra data.\n\nNotable key: `mcc` — the Business's Merchant Category Code(s) (ISO 18245, 4 digits each).\nAccepted formats: a comma-separated string (`\"5411,5812\"`) or an array of strings\n(`[\"5411\", \"5812\"]`). Always send codes as strings to preserve leading zeros (e.g. `\"0742\"`).\nIf at least one provided code is not eligible for financing, the request is rejected with\n`mcc_not_eligible`. The value is stored and returned as a comma-separated string.\n", "additionalProperties": true, "example": { "mcc": "5411,5812", "key": "value" } } } }, "examples": { "create_business": { "value": { "id": "business-id", "currency": "EUR", "bank_account": { "account_number_ending": "1234" }, "legal_representative": { "phone_ending": "4321" }, "legal_address": { "country": "DEU" }, "partnership_started_date": "2023-01-01", "founding_date": "2023-01-01", "metadata": { "mcc": "5411,5812", "mcc_translation": "Grocery stores", "employee_of_the_month": "John Doe" } } } } } }, "required": true }, "responses": { "201": { "description": "Business created.", "content": { "application/json": { "schema": { "description": "Business response object", "type": "object", "required": [ "id", "currency", "bank_account", "legal_address" ], "properties": { "id": { "description": "Identifier of the business.", "type": "string", "example": "business-id" }, "legal_name": { "description": "Legal name of the business.", "type": "string", "example": "Business GmbH" }, "business_registration_number": { "description": "Business registration number.", "type": "string", "example": "DE123456789" }, "tax_number": { "description": "Tax number.", "type": "string", "example": "DE987654321" }, "bank_account": { "description": "Entity for sharing business bank account details.", "type": "object", "properties": { "account_number": { "description": "Full IBAN or local BBAN of the Business’s bank account.", "type": "string", "example": "DE53500105174515729675" }, "bic": { "description": "BIC (Bank Identifier Code) of the Business’s bank account.", "type": "string", "example": "INGDDEFFXXX" }, "account_holder_name": { "description": "Name of the bank account holder. The Business’s legal name will be used for payout if this value is missing.", "type": "string", "example": "John Doe" }, "account_number_ending": { "description": "Last N digits of the Business’s bank account number (typically the last four).", "type": "string", "example": "9675" } } }, "currency": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/requestBody/content/application~1json/schema/properties/currency" }, "legal_representative": { "type": "object", "properties": { "first_name": { "description": "First name of the business’s legal representative.", "type": "string", "example": "John" }, "last_name": { "description": "Last name of the business’s legal representative.", "type": "string", "example": "Doe" }, "phone": { "description": "Phone number of the business’s legal representative.", "type": "string", "example": "+4917612345678" }, "email": { "description": "Email address of the business’s legal representative.", "type": "string", "example": "john@doe.mail" }, "phone_ending": { "description": "Last N digits of the business’s contact phone (usually last four).", "type": "string", "example": "1234" } } }, "legal_address": { "type": "object", "description": "Entity for business address details.", "required": [ "country" ], "properties": { "address_line_1": { "description": "First line of the Business address.", "type": "string", "example": "Musterstraße 12" }, "address_line_2": { "description": "Second line of the Business address for any required additions to the first line.", "type": "string", "example": "c/o Business GmbH" }, "postal_code": { "description": "Postal code of the Business address.", "type": "string", "example": "12345" }, "city": { "description": "City where the Business is located.", "type": "string", "example": "Musterstadt" }, "state": { "description": "State where the Business is located.", "type": "string", "example": "Musterstadt" }, "country": { "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}~1credits/get/responses/200/content/application~1json/schema/properties/data/items/properties/country/allOf/0" } } }, "partnership_started_date": { "description": "Date when the partnership started (ISO 8601 date).", "type": "string", "format": "date", "example": "2020-01-01" }, "founding_date": { "description": "Date when the business was founded (ISO 8601 date).", "type": "string", "format": "date", "example": "2020-01-01" }, "metadata": { "type": "object", "description": "Contains a set of flexible custom key-value pairs. Used for sharing extra data.", "additionalProperties": true, "example": { "key": "value" } } } }, "examples": { "business_created": { "value": { "id": "business-id", "legal_name": null, "business_registration_number": null, "tax_number": null, "bank_account": { "account_number": null, "bic": null, "account_holder_name": null, "account_number_ending": "1234" }, "currency": "EUR", "legal_representative": { "first_name": null, "last_name": null, "phone": null, "email": null, "phone_ending": "4321" }, "legal_address": { "address_line1": null, "address_line2": null, "postal_code": null, "city": null, "state": null, "country": "DEU" }, "partnership_started_date": "2023-01-01", "founding_date": "2023-01-01", "metadata": { "mcc": "5411,5812", "mcc_translation": "Grocery stores", "employee_of_the_month": "John Doe" } } } } } } }, "400": { "description": "Can't process request due to validation reasons, or at least one of the Business's merchant category codes (MCC) is not eligible for financing.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1transaction/post/responses/400/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error", "mcc_not_eligible" ] }, "description": { "example": "Some fields of the request don't match requirements." } } } ] }, "examples": { "validation_error": { "value": { "code": "validation_error", "description": "Some fields of the request don't match requirements." } }, "mcc_not_eligible": { "value": { "code": "mcc_not_eligible", "description": "Financing is not available for businesses in these merchant categories (MCC '9999,8888')." } } } } } }, "401": { "description": "Missing or invalid API key. Could not authenticate API request." }, "409": { "description": "Business exists already.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1transaction/post/responses/400/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "business_conflict" ] }, "description": { "example": "Business with id 'business-id' already exists" } } } ] }, "examples": { "business_conflict": { "value": { "code": "business_conflict", "description": "Business with id 'business-id' already exists" } } } } } }, "500": { "description": "An unexpected server error occurred. You should try again later or contact finmid support.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1transaction/post/responses/400/content/application~1json/schema/allOf/0" }, { "properties": { "code": { "type": "string", "enum": [ "server_error" ] }, "description": { "example": "Our server was hit by a meteorite 💥." } } } ] }, "examples": { "server_error": { "value": { "code": "server_error", "description": "Internal processing error" } } } } } } } } }, "/api/v1/capital/businesses/{business_id}": { "get": { "tags": [ "Business" ], "operationId": "get-business", "summary": "Get Business", "description": "This endpoint allows Platforms to detect what data has been shared up to the current time for any specific Business.", "parameters": [ { "name": "business_id", "in": "path", "required": true, "description": "Identifier of the Business.", "schema": { "$ref": "#/paths/~1api~1v1~1capital~1payment-batches~1{batch_id}/get/parameters/0/schema" }, "example": "business-id" } ], "responses": { "200": { "description": "Business.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/201/content/application~1json/schema" }, "examples": { "business": { "value": { "id": "business-id", "legal_name": "Business GmbH", "business_registration_number": "DE123456789", "tax_number": "DE987654321", "bank_account": { "account_number": "DE53500105174515729675", "bic": "INGDDEFFXXX", "account_holder_name": "John Doe", "account_number_ending": "9675" }, "currency": "EUR", "legal_representative": { "first_name": "John", "last_name": "Doe", "phone": "+4917612345678", "email": "john@doe.mail", "phone_ending": "5678" }, "legal_address": { "address_line1": "Musterstraße 12", "address_line2": "c/o Business GmbH", "postal_code": "12345", "city": "Musterstadt", "state": null, "country": "DEU" }, "partnership_started_date": "2023-01-01", "founding_date": "2023-01-01", "metadata": { "employee_of_the_month": "John Doe" } } } } } } }, "401": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/401" }, "404": { "description": "Business not found.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1transaction/post/responses/400/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "business_not_found" ] }, "description": { "example": "Business with id 'business-id' not found" } } } ] }, "examples": { "business_not_found": { "value": { "code": "business_not_found", "description": "Business with id 'business-id' not found" } } } } } }, "500": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/500" } } } }, "/api/v1/capital/businesses/{business_id}/capital-max": { "get": { "tags": [ "Capital Max" ], "operationId": "get-capital-max", "summary": "Get Capital Max State", "description": "This endpoint returns the Capital Max state for a Business.\n\nCapital Max allows a business to request additional capital beyond their standard funding.\n\nThe response includes Capital Max configuration and a list of past and current applications ordered by `appliedAt DESC`\n\nThe optional `application_status` query parameter allows filtering applications by their current status.\n\nThe lifecycle of a Capital Max Application is as follows:\n- `IN_REVIEW`: the initial state of the resource. The associated offer group is deactivated to block the business from accepting previously generated offers. At any given time, there can be only one Funding Application in the `IN_REVIEW` state. \n- `APPROVED`: a new offer group has been generated with higher funding limits, becoming the active offer group.\n- `REJECTED`: the application was rejected and the offer group might or might not have been re-activated.\n> Hint: query the Active Offer Group to find out if it has been re-activated or not.\n", "parameters": [ { "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}/get/parameters/0" }, { "name": "application_status", "in": "query", "description": "Filter applications by status.", "required": false, "schema": { "description": "Status of the Capital Max Application.\n\n- `IN_REVIEW`: the application is currently under review.\n- `APPROVED`: the application has been approved.\n- `REJECTED`: the application has been rejected.\n", "type": "string", "enum": [ "IN_REVIEW", "APPROVED", "REJECTED" ], "example": "IN_REVIEW" } } ], "responses": { "200": { "description": "Capital Max state for this Business.", "content": { "application/json": { "schema": { "type": "object", "required": [ "can_apply", "available_submission_types", "applications" ], "properties": { "can_apply": { "description": "Whether the business can currently submit a new Capital Max application.", "type": "boolean", "example": true }, "available_submission_types": { "description": "The types of submissions currently available for the business.", "type": "array", "items": { "description": "Type of submission available for a Capital Max application.\n\n- `DOCUMENTS`: the business can submit documents.\n- `AISP_CONNECTION`: the business can connect via AISP (Account Information Service Provider).\n", "type": "string", "enum": [ "DOCUMENTS", "AISP_CONNECTION" ], "example": "DOCUMENTS" } }, "applications": { "description": "List of Capital Max applications for this business.", "type": "array", "items": { "type": "object", "required": [ "applied_at", "requested_amount", "submission_types", "status" ], "properties": { "applied_at": { "description": "Timestamp in UTC when the application was submitted (ISO 8601 datetime).", "type": "string", "format": "date-time", "example": "2025-06-10T14:30:00.000Z" }, "requested_amount": { "description": "The amount requested in the application", "type": "integer", "example": 50000 }, "submission_types": { "description": "The types of submissions included in this application.", "type": "array", "items": { "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}~1capital-max/get/responses/200/content/application~1json/schema/properties/available_submission_types/items" } }, "status": { "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}~1capital-max/get/parameters/1/schema" }, "resolved_at": { "description": "Timestamp in UTC when the application was resolved (ISO 8601 datetime). `null` if the application has not been resolved yet.", "type": "string", "format": "date-time", "nullable": true, "example": "2025-06-12T09:00:00.000Z" } } } } } }, "examples": { "enabled_with_applications": { "summary": "Capital Max enabled with applications", "value": { "can_apply": true, "available_submission_types": [ "DOCUMENTS", "AISP_CONNECTION" ], "applications": [ { "applied_at": "2025-06-10T14:30:00.000Z", "requested_amount": 50000, "submission_types": [ "DOCUMENTS" ], "status": "APPROVED", "resolved_at": "2025-06-12T09:00:00.000Z" }, { "applied_at": "2025-07-01T10:00:00.000Z", "requested_amount": 75000, "submission_types": [ "DOCUMENTS", "AISP_CONNECTION" ], "status": "IN_REVIEW", "resolved_at": null } ] } }, "enabled_no_applications": { "summary": "Capital Max enabled, no applications yet", "value": { "can_apply": true, "available_submission_types": [ "DOCUMENTS" ], "applications": [] } }, "not_enabled": { "summary": "Capital Max not enabled", "value": { "can_apply": false, "available_submission_types": [], "applications": [] } }, "filtered_by_status": { "summary": "Filtered by IN_REVIEW status", "value": { "can_apply": false, "available_submission_types": [ "DOCUMENTS" ], "applications": [ { "applied_at": "2025-07-01T10:00:00.000Z", "requested_amount": 75000, "submission_types": [ "DOCUMENTS" ], "status": "IN_REVIEW", "resolved_at": null } ] } } } } } }, "401": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/401" }, "404": { "$ref": "#/paths/~1api~1v1~1capital~1businesses~1{business_id}/get/responses/404" }, "500": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/500" } } } }, "/api/v1/capital/payment-batches/{batch_id}": { "get": { "tags": [ "Payment" ], "operationId": "get-payment-batch", "summary": "Get Payment batch", "description": "Retrieve aggregated payment information for a specific payment batch.\n\nFor every batch, it is possible to request information about the total batch payment amount and platform commission amount, as well as the payment details for each Funding.\n\nThe information is aggregated by `funding_id`, meaning if multiple payments were reported for the same Funding (via [Report Payment](./report-payment) API), they will be summed together in a single entry.\n\nThis endpoint provides visibility into payments that were reported using [Report Payment](./report-payment) API. Use this data to determine the total amount to collect from your businesses before completing the batch via [Report Funds Collection](./report-funds-collection) API (platform-funded) or bank transfer (finmid-funded).\n", "parameters": [ { "name": "batch_id", "in": "path", "description": "Unique identifier for the specific payment period.", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_\\.\\-]{1,100}$", "maxLength": 100 }, "example": "W4-2020-01" } ], "responses": { "200": { "description": "Aggregated batch payment data.", "content": { "application/json": { "schema": { "type": "object", "required": [ "batch_id", "payment_amount", "currency", "platform_commission_amount", "data" ], "properties": { "batch_id": { "description": "Unique identifier for the specific payment period.", "type": "string" }, "payment_amount": { "description": "Total payment amount reported for all Fundings in this batch. Sum of all `payment_amount` in the `data` array.", "type": "number" }, "currency": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1capital~1payment-batches~1{batch_id}~1incoming-funds/post/requestBody/content/application~1json/schema/properties/currency/allOf/0" }, { "description": "ISO 4217 currency code." } ] }, "platform_commission_amount": { "description": "Total platform commission amount for all Fundings in this batch. Sum of all `platform_commission_amount` in the `data` array.", "type": "number" }, "data": { "type": "array", "description": "Aggregated payment data for each `funding_id` in this batch. If multiple payments were reported for the same Funding, they are summed together.", "items": { "type": "object", "required": [ "business_id", "funding_id", "payment_amount", "platform_commission_amount", "currency" ], "properties": { "business_id": { "description": "Unique identifier of the Business that owns the Funding.", "type": "string" }, "funding_id": { "description": "Unique identifier of the Funding for which payments were reported.", "type": "string", "format": "uuid" }, "payment_amount": { "description": "Total payment amount reported for this Funding in this batch, excluding the `platform_commission_amount`. This is the amount that we expect to receive in transaction to us, with `batch_id` as a payment reference.", "type": "number" }, "platform_commission_amount": { "description": "Total platform commission amount for this Funding in this batch. This is the amount that will be kept by you as a commission.", "type": "number" }, "currency": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1capital~1payment-batches~1{batch_id}~1incoming-funds/post/requestBody/content/application~1json/schema/properties/currency/allOf/0" }, { "description": "ISO 4217 currency code in which Business operates." } ] } } } } } }, "examples": { "single_funding_payment": { "value": { "batch_id": "W4-2020-01", "payment_amount": 1000, "platform_commission_amount": 50, "data": [ { "business_id": "business-123", "funding_id": "00000000-0000-0000-0000-000000000001", "payment_amount": 1000, "platform_commission_amount": 50 } ] } }, "multiple_fundings_payment": { "value": { "batch_id": "W4-2020-01", "payment_amount": 2500, "platform_commission_amount": 125, "data": [ { "business_id": "business-123", "funding_id": "00000000-0000-0000-0000-000000000001", "payment_amount": 1500, "platform_commission_amount": 75 }, { "business_id": "business-456", "funding_id": "00000000-0000-0000-0000-000000000002", "payment_amount": 1000, "platform_commission_amount": 50 } ] } } } } } }, "401": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/401" }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1transaction/post/responses/400/content/application~1json/schema/allOf/0" }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "batch_not_found" ] }, "description": { "example": "Batch with ID 'W4-2020-01' not found" } } } ] }, "examples": { "batch_not_found": { "value": { "code": "batch_not_found", "description": "Batch with ID 'W4-2020-01' not found" } } } } } }, "500": { "$ref": "#/paths/~1api~1v1~1capital~1businesses/post/responses/500" } } } }, "/api/v1/transaction": { "post": { "tags": [ "Payment" ], "operationId": "execute-payment-transaction", "summary": "Execute Payment Transaction", "description": "This API must be implemented by platforms that provide their own capital to businesses.\n\n> ⚠️ Note that this endpoint is **not hosted by finmid**.\n\nIt is called by finmid to instruct the platform to execute a bank transfer to the specified beneficiary to payout a funding.\n\nThe platform must process the payment and return a successful HTTP response to acknowledge receipt of the request.\n\nOnce the payment request has been processed, the platform must notify finmid of its success or failure via the [Receive Payout Confirmation](#tag/Incoming-Webhook/operation/receive-payout-confirmation) webhook.\n\n## Idempotency\n\nThe `idempotency_key` uniquely identifies each transaction request. If finmid sends a request with an `idempotency_key` that was already successfully processed, the platform should return a 409 - CONFLICT response without executing the payment again.\n\n## Beneficiary verification\n\nWe recommend that the platform verifies the beneficiary before executing the payment. Specifically, the platform should look up the business in its own system using the provided `iban` and confirm that the beneficiary is a known customer. If the IBAN does not match any registered business, the platform should reject the request with a 400 - validation error.\n\n## Authentication & message integrity\n\nEvery request from finmid is signed using **HTTP Message Signatures** ([RFC 9421](https://www.rfc-editor.org/rfc/rfc9421)), combined with **IP whitelisting**.\n\n### What is signed\n\nfinmid signs the following components of each request:\n\n| Component | Description |\n|---|---|\n| `@method` | HTTP method (POST) |\n| `@path` | Request path |\n| `content-type` | Media type of the body |\n| `content-digest` | SHA-256 hash of the request body (see below) |\n\n### Request headers\n\nEach signed request includes the following additional HTTP headers:\n\n| Header | Description |\n|---|---|\n| `Content-Digest` | SHA-256 hash of the request body, formatted as `sha-256=::` |\n| `Signature-Input` | Describes which components are signed and includes signature metadata |\n| `Signature` | The cryptographic signature (base64-encoded) |\n\n### Signature metadata\n\nThe `Signature-Input` header contains the following metadata parameters:\n\n| Parameter | Description |\n|---|---|\n| `keyid` | Identifier of the public key to use for verification. finmid will provide the public key during integration setup. |\n| `alg` | Signing algorithm. finmid uses `ed25519`. |\n| `created` | Unix timestamp (seconds) when the signature was created. |\n| `expires` | Unix timestamp (seconds) after which the signature is no longer valid (`created` + 60 seconds) |\n| `nonce` | Random unique value (UUID) generated per request attempt, including retries. Used exclusively for replay attack prevention — independent from the `idempotency_key` in the request body, which serves business-level idempotency. The nonce store can use a short TTL aligned with the signature validity window (`expires - created`). |\n\n### Example signed request\n\n```http\nPOST /api/v1/transaction HTTP/1.1\nHost: platform.example.com\nContent-Type: application/json\nContent-Digest: sha-256=:q83vRzQK3YpS6cJ8iX9u6pHc9T6YxQZ3S8KcYpVvC8E=:\nSignature-Input: sig1=(\"@method\" \"@path\" \"content-type\" \"content-digest\");created=1773135059;expires=1773135119;keyid=\"finmid-prod-key-1\";alg=\"ed25519\";nonce=\"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\nSignature: sig1=:dGhpcyBpcyBhbiBleGFtcGxlIHNpZ25hdHVyZQ==:\n\n{\"idempotency_key\":\"op-fund-2026.crd-001.biz-123\",\"business_id\":\"biz-123\",\"beneficiary\":{\"iban\":\"DE89370400440532013000\",\"bic\":\"COBADEFFXXX\",\"name\":\"John Doe\"}, ...}\n```\n\n### Verification steps (server-side)\n\nThe platform must verify each incoming request:\n\n1. **Parse** `Signature-Input` to extract signed components and metadata.\n2. **Reconstruct** the signature base — the canonical string built from the signed components in the exact order specified by `Signature-Input`.\n3. **Retrieve** the public key using `keyid`. finmid will provide the public key during integration setup.\n4. **Verify** the `Signature` against the reconstructed signature base using the public key and the `ed25519` algorithm.\n5. **Validate** the `Content-Digest` header by computing SHA-256 of the received body and comparing.\n6. **Enforce** temporal and replay policies:\n - Reject if `created` is in the future (allow ~30 seconds clock skew).\n - Reject if current time is after `expires`.\n - Reject if the `nonce` has already been seen within the validity window.\n\nIf any step fails, return `401 Unauthorized`.\n\n### Key exchange\n\nDuring integration setup, finmid will provide:\n- The **Ed25519 public key** for signature verification.\n- The **`keyid`** value that will appear in `Signature-Input`.\n- The list of **IP addresses** to whitelist for additional security.\n\nKey rotation will be coordinated between finmid and the platform, with advance notice.\n\n## Base URL\n\nThe base URL for this endpoint is the platform's own server URL, configured during the integration setup with finmid.
\nThe following is a suggestion, the platform can customise it to their needs:\n\n```\nPOST /api/v1/transaction\n```\n", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotency_key", "business_id", "beneficiary", "amount", "payment_reference" ], "properties": { "idempotency_key": { "type": "string", "description": "Unique idempotency key for this transaction request. Composed of the operation key, source ID, and destination ID, separated by dots.\n\nFormat: `..`\n", "example": "op-abc123.src-001.dst-002" }, "business_id": { "type": "string", "description": "The platform's identifier for the business receiving the payout. Provided by finmid so the platform can verify the beneficiary against its own records.\n", "example": "biz-123" }, "beneficiary": { "allOf": [ { "type": "object", "required": [ "iban", "name" ], "properties": { "iban": { "type": "string", "description": "IBAN of the beneficiary.", "example": "DE89370400440532013000" }, "bic": { "type": "string", "description": "BIC of the beneficiary.", "nullable": true, "example": "COBADEFFXXX" }, "name": { "type": "string", "description": "Full name of the beneficiary.", "example": "John Doe" } } }, { "description": "Bank account details of the payment beneficiary." } ] }, "amount": { "type": "object", "required": [ "value", "currency" ], "description": "The payment amount.", "properties": { "value": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1capital~1simulation~1credits/post/responses/200/content/application~1json/schema/allOf/0/properties/fee/allOf/1" }, { "description": "Amount to be transferred.", "minimum": 0.01 } ] }, "currency": { "allOf": [ { "$ref": "#/paths/~1api~1v1~1capital~1payment-batches~1{batch_id}~1incoming-funds/post/requestBody/content/application~1json/schema/properties/currency/allOf/0" }, { "description": "ISO 4217 currency code of the payment." } ] } } }, "payment_reference": { "type": "string", "description": "Reference text for the bank transfer. Identifies the purpose of the payment.", "example": "Payment funding #CRD-2026-001" } } }, "examples": { "funding_payout": { "summary": "Funding payout to business", "value": { "idempotency_key": "op-fund-2026.crd-001.biz-123", "business_id": "biz-123", "beneficiary": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "name": "John Doe" }, "amount": { "value": 1500.75, "currency": "EUR" }, "payment_reference": "Payment funding #CRD-2026-001" } } } } }, "required": true }, "responses": { "200": { "description": "Transaction request acknowledged. The platform will process the payment." }, "400": { "description": "The request is invalid or failed validation.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "code", "description" ], "properties": { "code": { "allOf": [ { "type": "string", "enum": [ "validation_error", "server_error", "buyer_invalid", "seller_invalid", "platform_invalid", "payment_request_invalid", "line_item_invalid", "buyer_conflict", "seller_conflict", "payment_request_conflict", "business_conflict", "business_not_found", "document_already_exists", "incoming_webhook_conflict", "mcc_not_eligible", "offer_group_not_active", "offer_group_not_found", "platform_check_already_consumed", "platform_check_not_required", "platform_check_unavailable", "platform_checks_not_enabled" ] }, { "description": "Code that represents the kind of error." } ] }, "description": { "allOf": [ { "type": "string" }, { "description": "A more detailed description of the error." } ] } } }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_error" ] }, "description": { "example": "Invalid beneficiary IBAN" } } } ] }, "examples": { "validation_error": { "value": { "code": "validation_error", "description": "Invalid beneficiary IBAN" } } } } } }, "401": { "description": "Signature verification failed. Possible reasons:\n- Invalid or missing `Signature` or `Signature-Input` headers.\n- `Content-Digest` does not match the request body.\n- Signature has expired (`created`/`expires` validation failed).\n- `nonce` has already been used (replay attack detected).\n- Unknown `keyid` or request from a non-whitelisted IP.\n" }, "409": { "description": "Transaction with the same idempotency key already processed." } } } } }, "components": { "securitySchemes": { "apiKeyScheme": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } } } ````