Payment failures and recovering balances

DocsCurrentLast updated: October 6th 2021, @ 7:10:14 pm

In a subscription business model, a subscriber is charged an amount at regular intervals according to the subscription plan definition. Learn what to do when payments fail and outstanding balances exist for a subscription.

Payment failures

You can set a failure threshold for a plan, and if the subscription failed payment count exceeds the failure threshold you set, the subscription is suspended.

If a subscription payment fails at the start of the billing cycle, PayPal retries the payment every five days for a maximum of two retries until the next billing cycle is reached. If the second retry attempt fails, PayPal increments the failed payment count by one, places the failed payment amount in the outstanding balance, and adds it to the next billing cycle.

When you create your plan, set the value for the payment_failure_threshold in the payment_preferences object:

    "payment_preferences": {
        "auto_bill_outstanding": true,
        "payment_failure_threshold": 2

Example of payment failure and threshold

  • A music streaming service has two plans:
    • Basic plan - For a single device, costs $4.99 per month.
    • Premium plan - For up to 3 devices, costs $9.99 per month.
  • The payment failure threshold is set to 2.
  • A user subscribes to the basic plan on 1 January and is debited automatically on the first of every month at 10:00 am GMT regardless of country.

In this example, if PayPal was not able to pull funds from the user for the billing cycle starting 1 February, payment is retried on 5 February and 10 February. If the second retry fails, PayPal increments the subscription failed payment count by one and sets the outstanding amount against the subscription to $9.99.

This outstanding amount is added to the next billing cycle and, in this example, the subscriber is charged $19.98 on 1 March. If the payment fails for the next billing cycle as well, causing the payment failure threshold to be reached, the previous outstanding amount is added to the current cycle for a total outstanding balance of $29.97, and the subscription is suspended. You can settle offline or capture the outstanding balance.

Buyer cancels subscription with balance

If the buyer cancels a subscription, PayPal stops retrying attempts for failed payments. The amount you're trying to recover goes into an outstanding balance which you settle offline or capture at any time.

Recover outstanding balances

If the subscription has an outstanding balance, you can capture that balance at any time. You might want to do this if the failure threshold is met and the subscription is suspended.

Sample request

In this example, the outstanding balance being captured is $25.00. You could capture part of the balance now, $15.00, and the remaining $10.00 later.

curl -v -X POST  /
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-H "PayPal-Request-Id: CAPTURE-160919-A0051" \
-d '{
   "note": "Charging because the balance reached the limit",
   "capture_type": "OUTSTANDING_BALANCE",
   "amount": {
     "value": "25.00",
     "currency_code": "USD"