paypal UNPROCESSABLE_ENTITY on order capture: payment source declined

TL;DR

The order was created fine, but the buyer card or funding source was declined when PayPal tried to capture. This is a buyer-side funding problem. Show the buyer a clear "payment declined" message and let them pick a different funding source, then create a new order. Do not retry the same capture.

UNPROCESSABLE_ENTITY order capture payment source declined

Use this when

• Order capture returns UNPROCESSABLE_ENTITY with a declined payment source.
• The order created successfully but capture fails.
• You need buyer-facing copy for a capture-time decline.

Not for this skill when

• Order creation itself failed. That is an order-setup problem.
• The error is at authorize time, not capture time.

Steps

1. ('Read the capture error detail to confirm the payment source was declined. Verify: the issue is the funding source, not your request.', 'Do not retry the same capture. Verify: no duplicate capture attempts exist.', 'Tell the buyer plainly that their payment method was declined and offer alternatives. Verify: the UI allows choosing a new funding source.', 'Create a new order with the new funding source and capture it. Verify: capture succeeds.', 'If declines are frequent for one buyer, suggest they check with their bank. Verify: you are not blocking a good customer.')

Variant phrasings

paypal order capture unprocessable entity

Short search.

paypal capture failed payment source declined

Symptom search.

UNPROCESSABLE_ENTITY paypal capture

Code search.

Compatibility: PayPal Orders API v2, capture endpoint.

Why it happens

PayPal separates order creation (reserving intent) from capture (moving money). The funding source is only truly tested at capture. A card that looked fine at order time can be declined at capture: limits reached, bank changed its mind, or the authorization window lapsed. UNPROCESSABLE_ENTITY is PayPal saying the request was well-formed but the business operation cannot proceed with this funding source.

Edge cases / pitfalls

• Retrying the same capture burns the buyer patience and changes nothing.
• The old order cannot be recaptured with a new source. Create a new order.
• Log the decline detail code; "declined" has sub-reasons that matter for support.
• Authorize-then-capture flows have expiry windows. Capture promptly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_uSs9eqS33oVRq6y0qtN9kQ