---
title: "Reserve funds for an accepted deal"
method: POST
path: "/deals/{dealId}/transactions"
tags: ["Transactions"]
---

# Reserve funds for an accepted deal

`POST /deals/{dealId}/transactions`

## Request

- Base URL: `https://api.darwin.so/api/v1`
- URL: `https://api.darwin.so/api/v1/deals/{dealId}/transactions`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates an idempotent reservation for the accepted maximum cap. Choose Darwin-managed payment or the application-managed Shared Payment Token preview. Performance settlement releases any unused amount.

## Path parameters

- `dealId` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateTransactionFundingRequest
  - `paymentMode` 'DARWIN_MANAGED' | 'APPLICATION_MANAGED'

## Response `201`

The reservation or exact funding requirement.

- TransactionFundingResult
  - `state` 'ready' | 'requires_funding' | 'payment_authorization_required' | 'recurring_approval_required' | 'recurring_scheduled', required
  - `transaction` Transaction, required
    - `id` string, required
    - `transactionId` string, required
    - `goalId` string, required
    - `taskId` string: Deprecated compatibility alias for goalId.
    - `dealId` string, required
    - `mode` 'BUY' | 'SELL' | 'CHAT', required: The workflow view for shared Darwin work resources.
    - `offerId` string: Deprecated compatibility alias for dealId.
    - `reservedCapMinor` integer, required
    - `amountMinor` integer
    - `subtotalMinor` integer, required
    - `darwinFeeMinor` integer, required
    - `feeBps` integer
    - `feeAttributionReason` string
    - `feePolicyVersion` integer
    - `taxAmountMinor` integer, required
    - `settledAmountMinor` integer, nullable, required
    - `releasedAmountMinor` integer, required
    - `refundedAmountMinor` integer
    - `currency` string, required
    - `status` string, required
    - `settlementMode` 'fixed' | 'performance', required
    - `sellerAcceptanceStatus` string
    - `customerAccountStatus` string
    - `fulfillmentStatus` string
    - `fundedAt` string, date-time, nullable
    - `transferredAt` string, date-time, nullable
    - `refundedAt` string, date-time, nullable
    - `disputedAt` string, date-time, nullable
    - `canceledAt` string, date-time, nullable
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `fundingAmountMinor` integer
  - `fundingRail` string, nullable
  - `clientSecret` string, nullable

## Other responses

- `400`: The request was invalid.
- `401`: The API key or access token is missing, invalid, expired, or revoked.
- `403`: The principal does not have the required scope or resource access.
- `404`: The resource was not found for this principal.

---

[API](https://skmtc.dev/darwin/apis/darwin-api.md) · [All operations](https://skmtc.dev/darwin/apis/darwin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/darwin/apis/darwin-api/revisions/56166fce7bfb?raw)