# Partial capture

Authorise the full amount, then capture only part of it after fulfilment. Void the remaining authorised funds to release them back to the customer.

## Use cases

- Partial shipments
- Tips or fees adjusted down
- Damaged/returned items before capture
- Hotel no-shows with reduced charge
- Metered usage less than estimated hold

## Steps

### 1. Create payment intent — `POST /payments`

Create a payment intent with capture_method set to 'manual'. This authorises the full amount without capturing funds.

Request body:

```json
{
  "amount": 6500,
  "currency": "ZAR",
  "confirm": false,
  "description": "Test payment from Interactive Docs",
  "return_url": "https://example.com/flows/simple-purchase?status=complete",
  "is_iframe_redirection_enabled": true,
  "billing": {
    "address": {
      "line1": "123 Main Street",
      "line2": "Apartment 4B",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "shipping": {
    "address": {
      "line1": "456 Delivery Road",
      "line2": "Unit 7",
      "city": "Cape Town",
      "state": "Western Cape",
      "zip": "8001",
      "country": "ZA",
      "first_name": "John",
      "last_name": "Doe"
    },
    "phone": {
      "number": "821234567",
      "country_code": "+27"
    },
    "email": "john.doe@example.com"
  },
  "capture_method": "manual",
  "authentication_type": "three_ds"
}
```

### 2. Mount SDK

Initialise the SDK and mount the checkout component for customer authorisation.

### 3. Customer authorises

Customer enters payment details and authorises the payment. Funds are held but not transferred.

### 4. Partial capture

In **requires_capture**, complete the flow in one of two ways:

• **Partial capture** — POST /payments/{id}/capture with an `amount_to_capture` less than the authorised amount. Status becomes `partially_captured` and the remainder needs to be voided in order to be released back to the customer.

• **Void** — POST /payments/{id}/cancel to release the remaining funds

Request body (Capture):

```json
{
  "amount_to_capture": 3000
}
```

Request body (Void authorisation):

```json
{
  "cancellation_reason": "abandoned"
}
```

### 5. Void remaining funds — `POST /payments/{id}/cancel`

After a partial capture, void the remaining authorised amount via POST /payments/{id}/cancel to release it back to the customer. Skip if you already voided the full authorisation.

Request body:

```json
{
  "cancellation_reason": "abandoned"
}
```

## Response

Payment endpoints return the payment object. Key fields to read:

- `payment_id` — the payment identifier.
- `status` — current payment status (see the state transitions below).
- `client_secret` — pass to the SDK to complete the payment client-side.
- `next_action` — present when a redirect or 3-D Secure challenge is required.

## Key parameters

- capture_method: 'manual'
- amount_to_capture < authorised amount
- Status becomes partially_captured
- Remaining funds must be voided to release the hold

## Flow diagram

```mermaid
flowchart LR
    A[Create Payment] --> B[Mount SDK]
    B --> C[Customer Authorises]
    C --> D{Authorised?}
    D -->|Yes| E[Full Amount Held]
    E --> V{Capture or Void?}
    V -->|Partial Capture| G[Capture Less Than Auth]
    G --> H[partially_captured]
    H --> F[Void Remaining]
    F --> I[Hold Released]
    V -->|Void| X[Full Hold Released]
    D -->|No| K[Show Error]
```

## Payment state transitions

```mermaid
stateDiagram-v2
    [*] --> requires_payment_method: Create Payment
    requires_payment_method --> requires_confirmation: Add Payment Method
    requires_confirmation --> processing: Confirm
    processing --> requires_capture: Authorised
    processing --> failed: Authorisation Failed
    requires_capture --> partially_captured: Partial Capture
    requires_capture --> cancelled: Void Full Auth
    partially_captured --> cancelled: Void Remaining
    cancelled --> [*]
    failed --> [*]
```

---

Interactive version: https://playground.peachpayments.com/flows/partial-capture