Platform Reference

Braintree Decline Codes: Complete Reference Guide

Braintree (a PayPal service) uses a processor response code system that includes both standard ISO 8583 codes and Braintree-specific gateway rejection reasons. Understanding both layers is important for effective payment recovery. The processor response code reflects the bank's decision, while gateway rejections are decisions made by Braintree itself (AVS checks, CVV verification, fraud filters). This guide covers both and maps them to optimal recovery strategies.

Affected Percentage

N/A — reference guide for all Braintree declines

Recovery Rate

Varies by code: 10-95% depending on decline type

Recommended Action

Retry with strategy

Key Concepts

Processor response codes (2000-series)

These are the bank's actual response codes. Braintree passes them through with a 2000-series prefix. For example, 2001 maps to "Insufficient Funds" (ISO 8583 code 51).

Gateway rejections

Braintree can reject transactions before they reach the bank based on AVS mismatch, CVV mismatch, fraud filters, or risk threshold settings in your Braintree control panel.

PayPal-specific declines

For PayPal transactions processed through Braintree, additional decline reasons include PayPal buyer/seller restrictions, PayPal risk decisions, and funding source issues.

Braintree fraud tools

Braintree's fraud detection (Basic, Advanced, or Kount integration) can decline transactions based on risk scoring independent of the bank's decision.

Recommended Retry Strategy

Retry recommended

Timing

Varies by code. Processor codes 2001-2015 are generally retryable (soft declines). Codes 2041-2099 are generally not (hard declines). Gateway rejections should be investigated, not retried.

Max Retries

Depends on the specific code. Soft processor declines: 3-4 retries. Hard declines: 0 retries.

Reasoning

Braintree's dual-layer system (processor codes + gateway rejections) requires different handling. Processor soft declines should be retried with timing optimization. Gateway rejections require configuration changes or customer data corrections, not retries.

Best Practices

1
Differentiate between processor response codes and gateway rejections in your error handling — they require completely different recovery approaches.
2
For processor codes, map the 2000-series code back to its ISO 8583 equivalent to apply standard retry/outreach strategies.
3
For gateway rejections (AVS, CVV), improve your checkout flow to collect accurate billing data rather than retrying the same data.
4
Review your Braintree fraud tool settings regularly — overly aggressive fraud rules cause false positive declines that lose revenue.
5
Use Braintree's transaction search API to pull detailed decline analytics and identify which codes contribute most to your failed payment volume.

How Rezoki Handles This Automatically

Rezoki supports Braintree's full decline taxonomy including both processor response codes and gateway rejections. For processor codes, Rezoki maps Braintree's 2000-series codes to the underlying ISO 8583 standard and applies the same intelligent recovery workflows — smart retries for soft declines, card updater + outreach for hard declines. For gateway rejections, Rezoki identifies the specific rejection reason and provides actionable recommendations: adjusting AVS settings, reviewing fraud rules, or fixing data quality issues. Rezoki's dashboard provides a unified view of Braintree declines broken down by type, giving clear visibility into where revenue is being lost.

Start Recovering Revenue

Related Decline Codes

Soft

Stripe Decline Codes: Complete Reference

Varies by code: 10-95% depending on decline type

Code 2 (Stripe) / GenericSoft

Generic Decline

40-60% recoverable

Soft

Soft vs Hard Declines: Complete Guide

Soft: 70-95%. Hard: 30-65%. Ambiguous: 40-60%.

Hard

Fraud-Related Declines

40-60% of false positives recoverable

Frequently Asked Questions

What is the difference between a Braintree processor code and a gateway rejection?+

A processor response code (2000-series) comes from the customer's bank — the transaction was sent to the bank and the bank declined it. A gateway rejection is Braintree's own decision to block the transaction before it reaches the bank, based on AVS/CVV verification, fraud filters, or risk settings. Gateway rejections are controllable through your Braintree configuration.

What does Braintree code 2001 mean?+

Code 2001 is "Insufficient Funds" — equivalent to ISO 8583 code 51. It's a soft decline meaning the customer's account doesn't have enough balance. It's highly recoverable (70-85%) with smart retry timing, ideally around paydays.

How do I handle Braintree gateway AVS rejections?+

AVS (Address Verification System) rejections mean the billing address provided doesn't match what the bank has on file. Don't retry with the same address. Instead, contact the customer to verify their billing address, or adjust your Braintree AVS settings to be less strict if you're seeing high false positive rates.

Does Braintree have a smart retry feature like Stripe?+

Braintree doesn't have a built-in equivalent to Stripe Smart Retries. You need to implement your own retry logic or use a tool like Rezoki that provides AI-powered retry scheduling. Braintree's recurring billing does perform basic retries on a fixed schedule, but it lacks the ML-based timing optimization.

Can I use Rezoki with Braintree?+

Yes. Rezoki integrates with Braintree via webhooks and the Braintree API. It reads processor response codes and gateway rejections from failed transactions and applies the optimal recovery workflow for each decline type. Rezoki provides the smart retry intelligence that Braintree's native billing lacks.