Payments
Card Preauthorization
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:
- Initialize Preauthorization — places a hold on the specified amount. The customer completes checkout but is not charged.
- 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
| Parameter | Required | Description |
|---|---|---|
email | Yes | Customer's email address |
amount | Yes | Amount in cents (smallest denomination). Minimum 100 cents. |
currency | Yes | Must be ZAR |
reference | No | Your unique transaction reference. Alphanumeric, -, ., = only. Auto-generated if omitted. |
expire_after_days | No | Days until expire_action is executed. Minimum 1, maximum 7. Defaults to 5. |
expire_action | No | Action on expiry: capture or release. Defaults to release. |
callback_url | No | Override the callback URL from your dashboard for this transaction. |
metadata | No | JSON 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.