Sign in

Payments

Card Preauthorization

View as Markdown

In a nutshell

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.

Info

Card Preauthorization is only available to registered businesses in South Africa that have completed the go-live process.

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.

Copy linkHow 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.

Info

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

Copy linkFirst-time customers

Copy linkStep 1: Initialize the preauthorization

curl https://api.paystack.co/preauthorization/initialize \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "amount": 10000,
    "currency": "ZAR"
  }' \
  -X POST
ParameterRequiredDescription
emailYesCustomer's email address
amountYesAmount in cents (smallest denomination). Minimum 100 cents.
currencyYesMust be ZAR
referenceNoYour unique transaction reference. Alphanumeric, -, ., = only. Auto-generated if omitted.
expire_after_daysNoDays until expire_action is executed. Minimum 1, maximum 7. Defaults to 5.
expire_actionNoAction on expiry: capture or release. Defaults to release.
callback_urlNoOverride the callback URL from your dashboard for this transaction.
metadataNoJSON object of custom data. See Metadata.

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).

Copy linkStep 2: Listen for the reserve confirmation

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

{
  "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.

Copy linkCapture the preauthorization

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

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.

{
  "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"
  }
}
{
  "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"
  }
}

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.

Copy linkRelease a preauthorization

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

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 [email protected] if this happens.

{
  "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"
  }
}
{
  "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"
  }
}

Copy linkReturning 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.

curl https://api.paystack.co/preauthorization/reserve \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization_code": "AUTH_vbvd4qti3m",
    "email": "[email protected]",
    "amount": 10000,
    "currency": "ZAR"
  }' \
  -X POST

Warning

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

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

Was this page helpful?