# Pre-authorisation

Authorise now, capture later. Useful when you need to verify funds before shipping or providing a service.

## Use cases

- Hotel bookings
- Car rentals
- Pre-orders
- Fraud review workflows

## Steps

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

Create a payment intent with capture_method set to 'manual'. Funds are authorised but not captured.

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. Customer authorises the payment.

### 3. Customer authorises

Customer confirms the payment. Funds are held but not transferred yet.

### 4. Capture or void authorisation

Funds are held in **requires_capture**. Choose one outcome—this completes the flow:

• **Capture** — POST /payments/{id}/capture to settle (full or partial amount).

• **Void** — POST /payments/{id}/cancel to release the hold with no charge (for example, order cancelled).

Request body (Capture):

```json
{
  "amount_to_capture": 6500
}
```

Request body (Void authorisation):

```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'
- Two-step process: authorise then capture
- POST /payments/{id}/capture to complete

## Flow diagram

```mermaid
flowchart LR
    A[Create Payment] --> B[Mount SDK]
    B --> C[Customer Authorises]
    C --> D{Authorised?}
    D -->|Yes| E[Funds Held]
    E --> F{Capture or Void?}
    F -->|Capture| G[Order Complete]
    F -->|Void| H[Hold Released]
    D -->|No| I[Show Error]
```

## Payment state transitions

```mermaid
stateDiagram-v2
    [*] --> requires_payment_method: Create Payment
    requires_payment_method --> processing: Customer Submits
    processing --> requires_capture: Authorised
    processing --> failed: Authorisation Failed
    requires_capture --> succeeded: Capture
    requires_capture --> cancelled: Void/Cancel
    succeeded --> [*]
    cancelled --> [*]
```

---

Interactive version: https://playground.peachpayments.com/flows/preauthorization