Stripe Integration Guide

PayPal's partnership with Stripe enables merchants to leverage their existing Braintree integration to process transactions through the PayPal Orchestration platform.

Note This integration is currently limited to the United States only.

Use this guide if you are a US-based merchant who wants to route card transactions through Stripe using your existing Braintree integration. This guide covers setup, transaction operations, status mapping, response codes, and testing. For SDK and GraphQL code examples, see the relavant links in Related content.

Important Use the Braintree platform for all transaction operations. Performing operations directly with Stripe could cause discrepancies and synchronization errors.

Features

The following topics summarize the capabilities that this integration supports.

Core transaction lifecycle

The following table describes support for the core transaction lifecycle operations with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Core transaction lifecycle
Charge (single step)	✅	Authorize and capture in the same call through the the Braintree SDK or GraphQL.
Charge (dual step)	✅	Authorize and then capture in separate steps through the Braintree SDK (authorize, capture) or GraphQL (authorize, capture).
Standalone authorization	✅	Capture authorization within 7 days (before it expires). This is available through the Braintree SDK or GraphQL.
Capture (full)	✅	Captures a previously authorized transaction. This is available through the Braintree SDK or GraphQL.
Partial capture	❌
Capture greater than authorized amount	❌
Adjust Authorization API (incremental auth / partial reversal)	❌

Voids and refunds

The following table describes support for voids and refusals with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Full void (auth reversal)	✅	Voids cancel an authorized transaction prior to settlement.
Partial void	❌
Void on settled transaction	❌	Use refund instead.
Full refund	✅	Merchants must have sufficient funds in their Stripe account.
Partial refund	✅	Refunds cannot exceed the settled amount.
Multiple refunds	✅
Blind credits (refunds for transactions processed elsewhere)	❌	Refunds must reference the original transaction.

Payment instruments and methods

The following table describes support for payment instruments and methods with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Credit cards	✅	USA: Mastercard, Visa, Diners, American Express, JCB, UnionPay
Debit cards	✅	USA: Mastercard, Visa, American Express, JCB, Diners
Prepaid cards	⚠️	Supported where Stripe supports prepaid.
PLCCs	❌
Gift cards	❌
Apple Pay	❌
Google Pay	❌
Venmo (PayPal)	❌

Data, descriptors, and fraud signals

The following table describes support for data, descriptors, and fraud signals with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
Card Verification Value (CVV) response handling	✅	CVV results are returned in response fields for authorization.
Dynamic descriptors	✅	1–22 character limit
Network tokens	✅	Braintree-managed and Bring Your Own Token are both available. For more information, see Network tokens.
Level 2/3 and lodging data	❌

Verifications

The following table describes support for verifications with this integration.

Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration

Capability	Support	Notes
3D Secure (3DS)	✅	Supported for US transactions
$0 verification	❌	Stripe requires a minimum charge of $0.50 for card validation.
Non-zero verification	✅	Minimum charge of $0.50 required for card validation.
Wallet verification	❌	This integration does not support Apple Pay and Google Pay verifications.

Before you begin

To complete this integration, you must set up Braintree and Stripe:

To set up currency-specific Braintree merchant accounts for use in your integration, contact your Braintree account manager (AM) or technical account manager (TAM).
When you have your Stripe account, work with your AM or TAM to configure the Stripe connection within the Braintree control panel. Stripe provides distinct API keys for sandbox and production environments. You must create the connection using the correct key for each environment.
Set up your environments to process the transactions using the information in Transactions.
Confirm your setup by processing a test transaction using the sandbox test cards that are listed in this guide.

Note If you do not have a dedicated Braintree AM or TAM, contact [email protected] for support.

Also review the following Stripe-specific requirements to ensure that you are in compliance before processing transactions through Stripe:

Cardholder name: All Stripe transactions require the cardholderName. You must must include it during payment method tokenization.
Refunds: Merchants must have sufficient funds in their Stripe account to cover any refund amounts. If adequate funds are unavailable when a refund is initiated, Stripe will place the refund in PENDING status. If Stripe returns a PENDING refund, Braintree will receive the final status update through a webhook when the refund succeeds or fails. No intermediate updates are sent while the refund remains in the PENDING state.
Webhooks: Braintree registers webhook endpoints for refund.updated and refund.created Stripe events to receive final settlement status for pending refunds. Merchants are not required to implement their own webhooks.

Transactions

The following topics describe the requirements for this integration.

Important Use the Braintree platform for all transaction operations. Performing operations directly with Stripe could cause discrepancies and synchronization errors.

For general information about Braintree transactions, see:

Transaction creation

Stripe transactions require the following Braintree fields.

Field	Location	How to provide	Notes
`creditCard.number`	Payment Method	Include during tokenization	Card number
`creditCard.expirationMonth`	Payment Method	Include during tokenization	Format: MM
`creditCard.expirationYear`	Payment Method	Include during tokenization	Format: YYYY
`amount`	Transaction	Include in transaction	Transaction amount. Decimals are supported.
`billing.countryCode`	Payment Method	Include during tokenization	Two-letter ISO country code. Must be `US`.
`card.cardholderName` (SDK) / `creditCard.cardholderName` (GraphQL)	Payment Method	Include during tokenization	Name as it appears on the card

Fields that Braintree passes to Stripe

The following table maps Braintree fields to the corresponding Stripe fields for authorization and charge operations.

Braintree field	Stripe field	Required	Notes
`amount`	`amount`	✅	Converted to cents (×100)
`currencyIsoCode`	`currency`	✅	Three-letter ISO currency code, lowercase
`billing.countryCodeAlpha2`	`billing_details.address.country`	✅	Two-letter ISO country code. Must be `US`.
`billing.postalCode`	`billing_details.address.postal_code`
`billing.streetAddress`	`billing_details.address.line1`
`billing.locality`	`billing_details.address.city`
`billing.region`	`billing_details.address.state`
`customer.email`	`billing_details.email`
`customer.phone`	`billing_details.phone`
`descriptor.name`	`statement_descriptor`		22-character limit
`threeDSecureData.cavv`	`payment_method_options.card.three_d_secure.cavv`		3DS CAVV value
`threeDSecureData.dsTransactionId`	`payment_method_options.card.three_d_secure.ds_transaction_id`		3DS Directory Server Transaction ID
`threeDSecureData.eciFlag`	`payment_method_options.card.three_d_secure.eci`		3DS Electronic Commerce Indicator
`threeDSecureData.version`	`payment_method_options.card.three_d_secure.version`		For example, "2.1.0"
`threeDSecureData.xId`	`payment_method_options.card.three_d_secure.xid`		3DS XID value
`networkTransactionIdentifier`	`payment_method_options.card.mit_exemption.network_transaction_id`		Included for Merchant Initiated Transactions (MIT)

Customer creation

Customer creation is optional but recommended for the Stripe integration. For more information, see the SDK or GraphQL documentation.

Vaulted payment methods

Vaulting a tokenized payment method creates an entity that can be authorized or charged multiple times. For more information, see the SDK or GraphQL documentation.

You also can vault a tokenized payment method during authorization. For more information, see the SDK or GraphQL documentation.

Transaction object support

The following topics describe support for transaction operations and CVV handling with this integration.

Supported transaction operations

The following table documents which transaction operations this integration supports.

Legend: ✅ Supported | ❌ Not supported |

Operation	Supported
Transaction: Sale	✅
Transaction: Find	✅
Transaction: Void	✅
Transaction: Refund	✅
Transaction: Submit for Settlement	✅
Transaction: Clone	✅
Transaction: Search	✅
Transaction: Adjust Authorization	❌
Transaction: Hold in Escrow	❌
Transaction: Release from Escrow	❌
Transaction: Submit for Partial Settlement	❌
Transaction: Cancel Release	❌

CVV handling

For recurring transactions or when using vaulted cards, the CVV might not be present.

NoteUsing ReverseTransactionmutation in GraphQL voids a transaction that is not in the SETTLED state or refunds a transaction that is in the SETTLED state.

Transaction status mapping

For general information about Braintree result objects, see Result Objects.

The following table maps Stripe responses to Braintree transaction statuses.

Operation	Stripe response	Braintree transaction status	Additional information
Authorize	Success	`AUTHORIZED`	Authorization must be captured within 7 days.
Authorize	Declined	`PROCESSOR_DECLINED`	Hard decline from issuer or Stripe
Authorize	API Error	`FAILED`	Network or server error when communicating with Stripe
Charge (single step)	Success	`SETTLED`	Authorization and capture are completed in one step.
Charge (single step)	Declined	`PROCESSOR_DECLINED`	Hard decline from issuer or Stripe
Charge (single step)	API Error	`FAILED`	Network or server error when communicating with Stripe
Capture	Success	`SETTLED`
Capture	Declined	`SETTLEMENT_DECLINED`	This can occur when authorization has expired.
Capture	Already captured (idempotent)	`SETTLED`	Payment intent was already in the succeeded state.
Capture	Authorization already voided	`VOIDED`	Payment intent was previously canceled.
Capture	Connector error (HTTP 500)	`SETTLING`	Rare event. Braintree reconciles this transaction. Do not ship goods until status is `SETTLED`. For more information, see SETTLING status with HTTP errors.
Refund	Success	`SETTLED`	—
Refund	Pending (insufficient funds)	`SETTLING`	Stripe will process when funds become available. Braintree will receive the final status update through a webhook when the refund settles.
Refund	Declined	`SETTLEMENT_DECLINED`	Rare event that can occur during disputes or chargebacks
Refund	Connector error (HTTP 500)	`SETTLING`	Rare event. Braintree will reconcile this transaction. For more information, see SETTLING status with HTTP errors.
Void	Success or already canceled	`VOIDED`	Idempotent: returns `VOIDED` even if already voided on Stripe's side.
VerifyCard	Success	`VERIFIED`
VerifyCard	Declined	`PROCESSOR_DECLINED`
VerifyCard	API Error	`FAILED`
VoidCardVerification	Success or already canceled	`VOIDED`	Braintree calls Stripe to cancel the verification payment intent. Idempotent if already canceled.

SETTLING status with HTTP errors

In rare cases when Stripe returns HTTP 4xx/5xx errors during capture or refund, the transaction may remain in SETTLING status while Braintree reconciles the outcome. This can happen due to:

Network or server overload
Stripe API unavailability

Reconciliation logic: Braintree queries Stripe for transaction status for capture, refund, and charge. If Stripe confirms the operation succeeded, the transaction moves to SETTLED. If Stripe declines, the transaction moves to SETTLEMENT_DECLINED.

Possible outcomes:

If Stripe approves, the status changes to SETTLED.
If Stripe declines, the status changes to SETTLEMENT_DECLINED.

NoteDo not ship goods or provide services until the transaction status is SETTLED.

FAILED status during charge

If Braintree doesn't receive an inline response from Stripe due to network errors or timeouts, the charge transaction status is set to FAILED. Unlike capture and refund, Braintree does not automatically reconcile charge errors. If you are unsure whether a charge was created, query the transaction (Find/Search) using your internal transaction reference before attempting a second create.

Retries

Follow these guidelines when implementing retry logic for Stripe transactions.

Do not build a "duplicate capture/refund retry loop" when you see success: true but status is SETTLING.
Always rely on transaction status before shipping goods or confirming the final outcome.
If your request times out or you are unsure whether a transaction was created, query the transaction (Find/Search) using your internal transaction reference (transactionId) before attempting a second create.
Retry logic on FAILED transactions can be configured at the merchant account level. For help with this configuration, contact your Braintree AM or TAM.

Network tokens

Stripe supports network tokens. The integration includes:

Braintree-managed network tokens: Braintree provisions and manages network tokens on your behalf.
Bring Your Own Network Token: Use network tokens you have provisioned through another provider.

To enable Braintree-managed network tokens for your account, contact your AM or Integration Engineer. For more information, see the Getting Started with Network Tokens guide.

Response codes

Braintree can only display a limited number of response codes, because Stripe controls transaction results. When Stripe decline codes cannot be mapped to like-for-like Braintree decline codes, Braintree returns code 2000 with this message: Do Not Honor.

To query for the Stripe response message, use:

SDK:additional_processor_response
GraphQL:TransactionSettlementProcessorResponse and TransactionAuthorizationProcessorResponse.

Processor response pass-through and debugging

Because approval and decline outcomes are ultimately controlled by Stripe, Braintree surfaces a standardized set of result codes. For detailed processor response information, see the appropriate documentation:

SDK:additional_processor_response
GraphQL:TransactionSettlementProcessorResponse and TransactionAuthorizationProcessorResponse. For more information, see the GraphQL documentation and GraphQL API reference.

CVV response code mapping

The following table maps Stripe CVV check results to Braintree CVV response codes.

Stripe CVV check	Braintree CVV response code	Meaning
`pass`	`M`	Match
`fail`	`N`	No Match
`unavailable`	`S`	Issuer does not support CVV
`unchecked`	`U`	Not Processed
(absent)	`I`	Not Provided

Failure response code mapping

The following table maps Braintree error codes to Stripe error codes and decline codes.

Braintree error code	Braintree error message	Stripe error code	Stripe decline code
`2000`	Do Not Honor	`card_declined`	`do_not_honor`
`2000`	Do Not Honor	`card_declined`	`approve_with_id`
`2000`	Do Not Honor	`card_declined`	`call_issuer`
`2001`	Insufficient Funds	`balance_insufficient`	N/A
`2001`	Insufficient Funds	`insufficient_funds`	N/A
`2001`	Insufficient Funds	`balance_insufficient`	`insufficient_funds`
`2002`	Limit Exceeded	`card_declined`	`card_velocity_exceeded`
`2004`	Expired Card	`card_declined`	`expired_card`
`2004`	Expired Card	`expired_card`	N/A
`2004`	Expired Card	`expired_or_canceled_card`	N/A
`2005`	Invalid Credit Card Number	`card_declined`	`incorrect_number`
`2005`	Invalid Credit Card Number	`card_declined`	`invalid_number`
`2005`	Invalid Credit Card Number	`card_declined`	`invalid_account`
`2005`	Invalid Credit Card Number	`incorrect_number`	N/A
`2006`	Invalid Expiration Date	`card_declined`	`invalid_expiry_month`
`2006`	Invalid Expiration Date	`card_declined`	`invalid_expiry_year`
`2006`	Invalid Expiration Date	`invalid_expiry_month`	N/A
`2006`	Invalid Expiration Date	`invalid_expiry_year`	N/A
`2010`	Card Issuer Declined CVV	`card_declined`	`incorrect_cvc`
`2010`	Card Issuer Declined CVV	`card_declined`	`invalid_cvc`
`2010`	Card Issuer Declined CVV	`incorrect_cvc`	N/A
`2010`	Card Issuer Declined CVV	`invalid_cvc`	N/A
`2012`	Possible lost or stolen card	`lost_or_stolen_card`	N/A
`2014`	Processor Declined – Fraud Suspected	`card_declined`	`fraudulent`
`2014`	Processor Declined – Fraud Suspected	`card_declined`	`not_permitted`
`2014`	Processor Declined – Fraud Suspected	`payment_method_customer_decline`	N/A
`2016`	Duplicate Transaction	`card_declined`	`duplicate_transaction`
`2017`	Cardholder Stopped Billing	`card_declined`	`stop_payment_order`
`2019`	Invalid Transaction	`card_declined`	`card_not_supported`
`2024`	Card Type Not Enabled	`invalid_card_type`	N/A
`2029`	Setup Error - Card	`payment_method_not_available`	N/A
`2033`	Inconsistent Data	`card_declined`	`incorrect_zip`
`2033`	Inconsistent Data	`cardholder_phone_number_required`	N/A
`2033`	Inconsistent Data	`email_invalid`	N/A
`2033`	Inconsistent Data	`incorrect_address`	N/A
`2033`	Inconsistent Data	`incorrect_zip`	N/A
`2033`	Inconsistent Data	`postal_code_invalid`	N/A
`2047`	Call Issuer. Pick Up Card	`card_declined`	`pickup_card`
`2048`	Invalid Amount	`amount_too_small`	N/A
`2048`	Invalid Amount	`amount_too_small`	`invalid_amount`
`2048`	Invalid Amount	`invalid_charge_amount`	N/A
`2053`	Card reported as lost or stolen	`card_declined`	`lost_card`
`2053`	Card reported as lost or stolen	`card_declined`	`stolen_card`
`2057`	Issuer or Cardholder restriction	`card_declined`	`restricted_card`
`2059`	Address Verification Failed	`payment_method_billing_details_address_missing`	N/A
`2060`	Address Verification and CVV Failed	`account_country_invalid_address`	N/A
`2061`	Invalid Transaction Data	`invalid_characters`	N/A
`2064`	Invalid Currency Code	`card_declined`	`currency_not_supported`
`2067`	Authorization Expired	`capture_charge_authorization_expired`	N/A
`2067`	Authorization Expired	`card_declined`	N/A
`2067`	Authorization Expired	`charge_expired_for_capture`	N/A
`2075`	Payer Account Locked/Closed	`account_closed`	N/A
`2099`	Cardholder Authentication Required	`card_declined`	`authentication_required`
`2102`	Incorrect PIN	`card_declined`	`incorrect_pin`
`2102`	Incorrect PIN	`card_declined`	`invalid_pin`
`2102`	Incorrect PIN	`card_declined`	`offline_pin_required`
`2102`	Incorrect PIN	`card_declined`	`online_or_offline_pin_required`
`2102`	Incorrect PIN	`card_declined`	`processing_error`
`2103`	PIN try exceeded	`card_declined`	`pin_try_exceeded`
`2107`	Card Not Activated	`card_declined`	`new_account_information_available`
`4001`	Settlement Declined	`card_declined`	(multiple decline codes)
`4001`	Settlement Declined	`declined`	N/A
`4001`	Settlement Declined	`unknown`	N/A
`4004`	Already Refunded	`charge_already_refunded`	N/A
`4004`	Already Refunded	`return_intent_already_processed`	N/A
`4006`	Capture Amount Exceeded	`amount_too_large`	N/A
`4019`	Refund with Open Case Not Allowed	`refund_disputed_payment`	N/A
`4024`	Refund Time Limit Exceeded	`charge_not_refundable`	N/A

Test cards

Braintree provides a set of test card numbers for sandbox testing. With the Stripe integration, some Braintree test card numbers are automatically mapped to Stripe test card numbers.

NoteBecause we map credit cards in sandbox to facilitate end-to-end testing, there may be discrepancies in reporting. In production, card numbers are sent to Stripe directly without modification.

Credit cards: Success

The following test card numbers produce successful transaction results in the sandbox.

Card brand	Braintree test number	Stripe test number	Automatically mapped
American Express	`378282246310005`	`378282246310005`	✅
Diners Club	`36259600000004`	`3056930009020004`	✅
Discover	`6011000991300009`	`6011111111111117`	✅
Mastercard	`5555555555554444`	`5555555555554444`	Pass-through
Visa	`4111111111111111`	`4242424242424242`	✅
JCB	`3530111333300000`	`3566002020360505`	✅
UnionPay	`6243030000000001`	`6200000000000005`	✅

Credit cards: Failure

The following test card numbers produce declined or error results in the sandbox.

Scenario	Braintree test number	Stripe test number	Automatically mapped?	Braintree result
Processing Error Decline	`4000111111111115`	`4000000000000119`	✅	Processor Declined
Insufficient Funds	`5105105105105100`	`4000000000009995`	✅	Processor Declined
Lost Card	`378734493671000`	`4000000000009987`	✅	Processor Declined
Stolen Card	`6011000990139424`	`4000000000009979`	✅	Processor Declined
Expired Card	`3852000000009814`	`4000000000000069`	✅	Processor Declined
Expired Card (Visa)	`4012888888881881`	`4000000000000069`	✅	Processor Declined
Card Velocity Exceeded	`3566002020360505`	`4000000000006975`	✅	Processor Declined

The following resources provide additional information for working with Stripe and Braintree.