Flutterwave Integration Guide

PayPal's Braintree partnership with Flutterwave enables merchants to use their existing Braintree integration to process card-not-present transactions through the PayPal Orchestration platform. Flutterwave's network focuses on Africa and emerging markets. It provides direct card acquisition in regions where traditional global processors have limited reach.

This guide helps developers at merchant sites complete the integration in their environment.

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

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

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

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

Verifications

The following table describes support for verifications with this integration.

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

Before you begin

Integrating Flutterwave with Braintree requires configuration in both:

• In Braintree: To process card transactions through Flutterwave, you need a Braintree merchant account that you configure for the Flutterwave connector. For help with setting up this account and securely storing your credentials, contact your Braintree account manager (AM) or technical account manager (TAM).
• In Flutterwave: To obtain access to Flutterwave's card-direct API, contact Flutterwave. When your account is provisioned, Flutterwave provides a merchant username and password for the sandbox and production environments. To securely share these credentials with Braintree, work with your Braintree AM or TAM.

Transactions

The following topics describe the requirements for this integration.

For general information about Braintree transactions, see:

• Transactions guide (SDK)
• Transactions guide (GraphQL)
• Transaction response object

Transaction creation

When you create a transaction, include the required fields and any optional fields that are appropriate for your use case.

The following table lists the fields that transactions require.

Fields that Braintree passes to Flutterwave

The following tables list the fields Braintree passes to Flutterwave for each operation.

Authorize, charge, and verify card

The following table lists the fields that Braintree passes to Flutterwave for authorization, charge, and verification purposes.

Capture

The following table lists the fields that Braintree passes to Flutterwave for capturing transactions.

Refund

The following table lists the fields that Braintree passes to Flutterwave for refunds.

Void

The following table lists the fields that Braintree passes to Flutterwave for voided transactions.

Customer creation

Creating a customer is optional for the Flutterwave integration. To create a customer, you can use either the Braintree SDKs or the GraphQL API. For more information, see the customer creation guide (SDK) or the customer creation guide (GraphQL).

Vaulted payment methods

Vaulting a tokenized payment method creates an entity that can be authorized or charged multiple times. A tokenized payment method also can be vaulted during authorization. For more information, see the vault guide (SDK) or the vault guide (GraphQL).

CVV handling

For merchant-initiated transactions, such recurring transactions, or when using vaulted cards, Braintree does not send the CVV to Flutterwave. Instead, Braintree sends an empty string (""). While Flutterwave accepts transactions without CVV, some card issuers might decline these transactions.

Supported transaction operations

The following table lists the transaction operations that the Flutterwave integration supports.

Transaction status mapping

The following table maps Flutterwave results to Braintree transaction statuses. For general information about Braintree result objects, see result objects.

SETTLING status and reconciliation

In rare cases, Flutterwave may return a retryable error (SERVER_BUSY, SERVER_FAILED, or an unrecognized error cause) after an otherwise-valid capture or refund request. When this occurs, the transaction is placed in SETTLING and Braintree automatically polls Flutterwave for the actual outcome.

Reconciliation behavior varies by operation:

• Capture reconciliation: If Flutterwave has not yet processed the capture (transaction still in AUTHORIZATION), returns AUTHORIZED for another reconciliation cycle. If the authorization was voided before capture, returns VOIDED.
• Refund reconciliation: Queries use the compound orderId|transactionId from the refund's origin response.

Possible outcomes after reconciliation:

• Flutterwave confirms success → status changes to SETTLED.
• Flutterwave returns a 4xx error → status changes to SETTLEMENT_DECLINED.
• Flutterwave returns a 5xx error → status remains SETTLING for another reconciliation cycle.

Do not ship goods or provide services until the transaction status has transitioned to SETTLED. Do not build a duplicate capture or refund retry loop when you see SETTLING.

Charge operations

Charge for Flutterwave is dual-step. Braintree first performs an authorization and then immediately captures it. The resulting transaction status follows the same outcomes as Capture. For more information, see Transaction status mapping.

Retries

Do not implement a retry loop when you observe success: true with a status of SETTLING. Braintree handles reconciliation automatically. Always check transaction status before fulfilling an order.

If your request times out or you are unsure whether a transaction was created, query the transaction using Find or Search with your internal transaction reference before attempting a second create.

Retry behavior on FAILED authorization can be configured at the Merchant Account ID (MAID) level. To enable automatic retries, contact your Braintree AM or TAM.

Response codes

Flutterwave uses ISO 8583-style two-digit acquirer codes for declines. Braintree maps these to standardized Braintree response codes. When a Flutterwave acquirer code is not present in the mapping, Braintree surfaces the raw acquirer code and message in the additionalProcessorResponse field.

To query for the Flutterwave raw response message, use:

• SDK:additional_processor_response. For more information, see the core documentation.
• GraphQL:PaymentStatusEvent.processorResponse.additionalInformation. For more information, see the core documentation.

CVV response code mapping

The following table maps Flutterwave CVV codes to their Braintree equivalents.

Failure response code mapping

The following table maps Flutterwave acquirer failure codes to their Braintree equivalents. If a Flutterwave acquirer code is not in this list, Braintree passes through the raw code and message in the additionalProcessorResponse field without a mapped genericResponseCode.

Testing

Braintree provides a set of test card numbers for sandbox testing. With the Flutterwave integration, certain Braintree test card numbers are automatically remapped to Flutterwave test card numbers to support end-to-end sandbox testing. In production, Braintree sends card numbers to Flutterwave directly (without modification).

Test card mappings

Expiration date-controlled outcomes

The expiration date you provide determines the outcome from Flutterwave for mapped test cards. Use the combinations that are in the following tables when you test your integration in the sandbox environment.

Mastercard (5105105105105100 → 5111111111111118)

Visa (4000111111111115 → 4012000033330026)

Known limitations

Review the following known behaviors and limitations before processing transactions through Flutterwave.

• Duplicate transaction reference handling: If Flutterwave returns INVALID_REQUEST with a message about "Merchant Transaction Reference must be set to a unique value," the error is treated as retryable (SETTLING). This can occur during the propagation delay between when a Flutterwave merchant account is provisioned and when it is fully active.
• CVV not sent for recurring or vaulted transactions: When a vaulted card is used for a subsequent transaction (for example, a subscription renewal), the CVV is not available. The connector sends an empty string.
• No 3DS, network token, or AVS support: This integration does not support 3DS data pass-through, network tokens (Braintree-managed or bring-your-own), or AVS response fields. If your use case requires any of these, contact your TAM to discuss alternative integration options.

Supported currencies

The Flutterwave connector supports the following currencies: GBP, CAD, XAF, CLP, COP, EGP, EUR, GHS, GNF, KES, MWK, MAD, NGN, RWF, SLL, STD, ZAR, TZS, UGX, USD, XOF, ZMW.

Related content

The following resources provide additional information about the Flutterwave integration and Braintree platform:

• Flutterwave API documentation (Postman collection)
• Braintree testing guide
• Braintree transaction guide (SDK)
• Braintree transaction guide (GraphQL)
• Braintree GraphQL API reference
• Braintree AVS or CVV response codes