Payments
How to use partial debits
In a nutshell
Recover part of a recurring payment when the full amount cannot be charged from a saved authorization.
Copy linkConfirm eligibility
Partial debit is available only on request. Access is granted after review by Paystackβs team. The feature currently supports Mastercard and Verve authorizations.
Copy linkStart from a saved authorization
Partial debits work only on existing authorizations. Use the same email attached to the authorization and the authorization code from a previous successful payment.
Copy linkCall the partial debit endpoint
Send the authorization, currency, amount, and email to https://api.paystack.co/transaction/partial_debit.
curl https://api.paystack.co/transaction/partial_debit \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"authorization_code": "AUTH_72btv547",
"currency": "NGN",
"amount": "20000",
"email": "[email protected]"
}' \
-X POST
You can also include:
referencefor tracking and idempotencyat_leastto set the minimum amount Paystack should try to recover
at_least must not be greater than amount.
Copy linkUse bulk charge when processing many partial retries
If you are charging many customers at once, pass attempt_partial_debit: true in each bulk charge object. Combine it with at_least when you want to define a lower acceptable recovery amount.
Copy linkVerify the result
When partial debit is involved, Paystack returns two important amount fields during verification and webhook processing:
| Field | Meaning |
|---|---|
amount | The amount actually charged |
requested_amount | The amount you originally tried to charge |
Use amount to determine what was recovered, and requested_amount to compare the original bill against the settled amount.
Copy linkReconcile before fulfilment
Only mark the payment flow complete after you verify the transaction or receive the final webhook event. If your fulfilment depends on collecting the full amount, compare amount and requested_amount before granting access or shipping goods.