# 0 Amount authorisation

Validate a card without charging it by authorising 0 amount. Perfect for verifying card details, setting up accounts, or checking card validity before a future charge. The card is saved for future use.

## Use cases

- Account signup card verification
- Free trial setup
- Card-on-file validation
- Pre-authorisation before service
- Updating expired cards

## Steps

### 1. Create 0 amount authorisation — `POST /payments`

Create a payment with amount: 0 and capture_method: "manual" to validate the card without charging.

Key parameters:
• amount: 0 - Zero authorisation
• currency: "ZAR" - Required even for 0 amount
• capture_method: "manual" - Prevents auto-capture
• setup_future_usage: "off_session" - Saves card for future charges
• customer.id - Your unique customer identifier

The zero-auth validates:
• Card number is valid
• Card is not expired
• Card passes issuer checks
• AVS/CVV verification (if enabled)

Request body:

```json
{
  "amount": 0,
  "currency": "ZAR",
  "confirm": false,
  "capture_method": "manual",
  "authentication_type": "three_ds",
  "setup_future_usage": "off_session",
  "description": "Card validation - 0 amount authorisation",
  "return_url": "https://example.com/flows/zero-auth?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"
  },
  "customer": {
    "id": "cus_validate_card",
    "email": "customer@example.com",
    "name": "Card Validation User"
  },
  "mandate_data": {
    "customer_acceptance": {
      "acceptance_type": "offline",
      "accepted_at": "1963-05-03T04:07:52.723Z",
      "online": {
        "ip_address": "127.0.0.1",
        "user_agent": "amet irure esse"
      }
    },
    "mandate_type": {
      "multi_use": {
        "amount": 799,
        "currency": "ZAR",
        "start_date": "2023-10-26T10:20:00Z",
        "end_date": "2099-01-01T00:00:00Z",
        "metadata": {
          "frequency": "13"
        }
      }
    }
  }
}
```

### 2. Mount SDK

Initialise the SDK for card entry. Customer enters card details for validation.

### 3. Customer enters card

Customer enters card details. The 0 amount auth validates the card without any charge.

After success:
• Card is validated and saved
• payment_method_id returned for future charges
• No funds are held or charged
• Card ready for future transactions

### 4. Void authorisation — `POST /payments/{id}/cancel`

Void the 0 amount authorisation to release it cleanly. While 0 amount auths typically don't hold funds, voiding ensures proper cleanup.

The card remains saved and can be charged using:
• payment_method_id for one-time charges
• mandate_id if you set up a mandate

Request body:

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

## Additional request payloads

### Capture

```json
{}
```

## 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

- amount: 0 - No charge to customer
- capture_method: 'manual' - Prevents capture
- Validates card without holding funds
- Card saved via setup_future_usage

## Flow diagram

```mermaid
flowchart LR
    A[Create 0 amount Payment] --> B[Mount SDK]
    B --> C[Customer Enters Card]
    C --> D{Card Valid?}
    D -->|Yes| E[Card Saved]
    E --> F[Void Auth]
    F --> G[Ready for Future Charges]
    D -->|No| H[Show Error]
```

## Payment state transitions

```mermaid
stateDiagram-v2
    [*] --> requires_payment_method: Create 0 amount Payment
    requires_payment_method --> processing: Submit Card
    processing --> requires_capture: Card Validated
    processing --> failed: Invalid Card
    requires_capture --> cancelled: Void Auth
    cancelled --> [*]: Card Saved

    note right of requires_capture: No funds held - Card saved for future
```

---

Interactive version: https://playground.peachpayments.com/flows/zero-auth