Payment failures and recovering balances

Here's what to do when payments fail and a subscription has an outstanding balance.

Payment failures

You can set a payment failure threshold for a plan.

• If the failed payment count exceeds the failure threshold, the subscription is suspended.
• If a payment fails, PayPal retries the payment every five days. PayPal retries the payment up to twice per billing cycle.
• If the second retry fails, PayPal counts this as a payment failure. The failed payment amount is added to the outstanding balance for the next billing cycle.

When you create your plan, you can 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 streaming service costs $10 per month
• The payment failure threshold is set to 2
• A subscriber pays on January 1. The subscriber is billed on the first of every month at 10:00 AM GMT.

In this example, PayPal can't pull funds from the subscriber on February 1. Paypal retries on February 5 and February 10. No funds are pulled. PayPal counts this as a payment failure. The outstanding amount against the subscription is $10.

$10 is added to the next billing cycle, so the subscriber is charged $20 on March 1. PayPal can't pull funds and reaches the payment failure threshold. The subscription is suspended.

Suppose the subscriber now cancels the subscription with a $20 outstanding balance. PayPal stops retrying attempts for failed payments. You can settle offline or capture the payment.

Recover outstanding balances

If the subscription has an outstanding balance, you can capture the balance. 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 $20.00. You could capture part of the balance now, $10.00, and the remaining $10.00 later.

curl -v -X POST https://api-m.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture  /
-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": "20.00",
     "currency_code": "USD"
   }
 }'