# Card Preauthorization

> Place a hold on a customer's card before charging the final amount — for ride-hailing, delivery, and pay-after-service businesses in South Africa.

<callout type="info">

Card Preauthorization is only available to registered businesses in South Africa that have completed the [go-live process](https://support.paystack.com/hc/en-us/articles/360009881220-How-do-I-activate-my-Paystack-Registered-Business-).

</callout>

Preauthorization lets you place a hold on a customer's card before charging the final amount. The money stays in the customer's account during the hold period — they cannot access it, but they are not charged yet. You charge the final amount after service delivery.

This is used by ride-hailing services, e-commerce businesses with delivery payment, and hotel booking platforms to guarantee funds are available before service is rendered.

## How preauthorization works

The flow has two steps:

1. **Initialize Preauthorization** — places a hold on the specified amount. The customer completes checkout but is not charged.
2. **Capture Preauthorization** — charges the final amount. If the final amount is less than the hold, the balance is automatically released.

The default hold period is **5 days**. You can extend it up to **7 days** using `expire_after_days`. Use `expire_action` to specify what happens when the hold expires: either `capture` (charge the amount) or `release` (release the funds to the customer). The default is `release`.

<callout type="info">

Preauthorization is an asynchronous flow. Webhooks are required. Set up a webhook endpoint before going live with this feature.

</callout>

## First-time customers

### Step 1: Initialize the preauthorization

```bash
curl https://api.paystack.co/preauthorization/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "amount": 10000,
    "currency": "ZAR"
  }' \
  -X POST
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        email
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Customer's email address
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Amount in cents (smallest denomination). Minimum 100 cents.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Must be <code>
        ZAR
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reference
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Your unique transaction reference. Alphanumeric, <code>
        -
      </code>
      
      , <code>
        .
      </code>
      
      , <code>
        =
      </code>
      
       only. Auto-generated if omitted.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expire_after_days
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Days until <code>
        expire_action
      </code>
      
       is executed. Minimum 1, maximum 7. Defaults to 5.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expire_action
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Action on expiry: <code>
        capture
      </code>
      
       or <code>
        release
      </code>
      
      . Defaults to <code>
        release
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        callback_url
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Override the callback URL from your dashboard for this transaction.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      JSON object of custom data. See <a href="/payments/online/metadata">
        Metadata
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

Redirect the customer to the `authorization_url` returned in the response. The customer enters their card details on the Paystack Checkout page (similar to Redirect integration).

### Step 2: Listen for the reserve confirmation

After the customer completes checkout, Paystack sends a `preauthorization.reserve.success` event to your webhook URL.

```json
{
  "event": "preauthorization.reserve.success",
  "data": {
    "id": 543,
    "status": "authorized",
    "reference": "pre_9gjnu6dc",
    "amount": 10000,
    "currency": "ZAR",
    "authorization": {
      "authorization_code": "AUTH_vbvd4qti3m",
      "channel": "card",
      "reusable": true
    },
    "expiry_date": "2024-06-05T23:28:52.000Z",
    "expire_action": "release"
  }
}
```

Store the `authorization_code` and `reference` — you will need them to capture or release.

## Capture the preauthorization

After service delivery, charge the final amount before the hold period expires.

```bash
curl https://api.paystack.co/preauthorization/capture \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "pre_9gjnu6dc",
    "amount": 8500,
    "currency": "ZAR"
  }' \
  -X POST
```

The `amount` must be less than or equal to the original hold amount. If it is lower, the difference is released back to the customer automatically.

A successful capture sends the `preauthorization.capture.success` event. If the capture fails (e.g., processor timeout), Paystack sends `preauthorization.capture.failed`.

<code-tabs :labels="{"success":"Success","failed":"Failed"}">
<template v-slot:success="">

```json
{
  "event": "preauthorization.capture.success",
  "data": {
    "id": 3099,
    "status": "captured",
    "reference": "pre_9gjnu6dc",
    "amount": 8500,
    "currency": "ZAR",
    "authorization": {
      "authorization_code": "AUTH_vbvd4qti3m",
      "channel": "card",
      "reusable": true
    },
    "captured_amount": 8500,
    "captured_at": "2024-06-05T11:58:44.000Z",
    "transaction_id": "1504264401",
    "expiry_date": null,
    "expire_action": "capture"
  }
}
```

</template>

<template v-slot:failed="">

```json
{
  "event": "preauthorization.capture.failed",
  "data": {
    "id": 3099,
    "status": "capture_failed",
    "reference": "pre_9gjnu6dc",
    "amount": 8500,
    "currency": "ZAR",
    "authorization": {
      "authorization_code": "AUTH_vbvd4qti3m",
      "channel": "card",
      "reusable": true
    },
    "captured_amount": null,
    "captured_at": null,
    "transaction_id": "1504264401",
    "expiry_date": "2024-06-05T23:28:52.000Z",
    "expire_action": "release"
  }
}
```

</template>
</code-tabs>

<callout type="info">

If Paystack does not get a definitive response during capture, the preauthorization enters an `ongoing` state and the processor is polled for a final response. If no response arrives, it moves to `capture_failed`.

</callout>

## Release a preauthorization

If the customer cancels or you decide not to charge, release the hold to make the funds available again.

```bash
curl https://api.paystack.co/preauthorization/release \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "pre_9gjnu6dc"}' \
  -X POST
```

The funds become available to the customer within a few minutes. A `preauthorization.release.success` event is sent on success.

In the rare case that release fails, Paystack sends `preauthorization.release.failed`. Contact [techsupport@paystack.com](mailto:techsupport@paystack.com) if this happens.

<code-tabs :labels="{"success":"Success","failed":"Failed"}">
<template v-slot:success="">

```json
{
  "event": "preauthorization.release.success",
  "data": {
    "id": 3101,
    "status": "released",
    "reference": "pre_9gjnu6dc",
    "amount": 10000,
    "currency": "ZAR",
    "authorization": {
      "authorization_code": "AUTH_vbvd4qti3m",
      "channel": "card",
      "reusable": true
    },
    "expiry_date": "2024-06-05T23:28:52.000Z",
    "expire_action": "release"
  }
}
```

</template>

<template v-slot:failed="">

```json
{
  "event": "preauthorization.release.failed",
  "data": {
    "id": 3118,
    "status": "release_failed",
    "reference": "pre_9gjnu6dc",
    "amount": 10000,
    "currency": "ZAR",
    "authorization": {
      "authorization_code": "AUTH_vbvd4qti3m",
      "channel": "card",
      "reusable": true
    },
    "expiry_date": "2024-06-05T23:28:52.000Z",
    "expire_action": "release"
  }
}
```

</template>
</code-tabs>

## Returning customers

If the customer has already paid your business via card, Paystack has an existing card authorization on file. You can skip the Initialize step and use the Reserve Preauthorization endpoint directly — the customer does not need to re-enter card details.

```bash
curl https://api.paystack.co/preauthorization/reserve \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_code": "AUTH_vbvd4qti3m",
    "email": "customer@example.com",
    "amount": 10000,
    "currency": "ZAR"
  }' \
  -X POST
```

<callout type="warning">

The `authorization_code` and `email` must match what was used in the original transaction. A mismatch causes the preauthorization to fail.

</callout>

Only card authorizations where `reusable: true` can be used for preauthorization. This is the same authorization model used for recurring charges.
