Sign in

Payments

How to use partial debits

View as Markdown

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:

  • reference for tracking and idempotency
  • at_least to 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:

FieldMeaning
amountThe amount actually charged
requested_amountThe 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.

Was this page helpful?