Fat Zebra Integration Guide
PayPal's partnership with Fat Zebra enables merchants to leverage their existing Braintree integration to process transactions through PayPal Orchestration Platform.
This guide helps developers at merchant sites complete the integration in their environment. The following tables describe the supported transaction types, payment instruments, and features for the Fat Zebra integration.
Features
The following topics describe the capabilities that this Fat Zebra integration supports.
Core transaction lifecycle
The following table lists the supported core transaction lifecycle operations.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration
| Capability | SDK | GraphQL | Support | Notes |
|---|---|---|---|---|
| Charge (single step) | ✅ | ✅ | ✅ | Perform authorization and capture in the same call. |
| Standalone authorization | ✅ | ✅ | ✅ | Authorization must be captured within the processor-defined window (5 days) before it expires. |
| Capture (full) | ✅ | ✅ | ✅ | Capture a previously authorized transaction. |
| Partial capture | ✅ | ✅ | ✅ | The capture amount can differ from the authorized amount. |
| Capture greater than authorized amount | ✅ | ✅ | ❌ | |
| Installment transactions (merchant-initiated transaction) | ✅ | ✅ | ❌ | |
| Adjust Authorization API | ✅ | ✅ | ❌ | This integration does not support incremental authorization, partial reversal during capture, or settlement. |
Voids and refunds
The following table lists the supported void and refund operations.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by configuration
| Capability | Support | Notes |
|---|---|---|
| Full void (auth reversal) | ✅ | Voids cancel an authorized transaction prior to settlement. |
| Partial void | ❌ | Use full void, and re-authorize the transaction at the correct amount. |
| Void on settled transaction | ❌ | Use refund instead. |
| Full refund | ✅ | Refunds cannot exceed the settled transaction amount. |
| Partial refund | ✅ | Refunds cannot exceed the settled amount. |
| Multiple refunds | ✅ | |
| Blind credits | ❌ | A refund must reference the original transaction. |
Payment instruments and methods
The following table lists payment instruments and methods that this integration supports.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration
| Instrument or method | Support | Notes |
|---|---|---|
| Credit cards | ✅ | Australia: Mastercard, Visa, American Express, Discover, Diners New Zealand: Mastercard, Visa, American Express, Discover, Diners |
| Debit cards | ✅ | Australia: Mastercard, Visa New Zealand: Mastercard, Visa |
| Prepaid cards | ✅ | Supported where Fat Zebra supports prepaid cards |
| PLCCs | ❌ | |
| Gift cards | ❌ | |
| Apple Pay | ✅ | Supported in Australia and New Zealand. Not supported for card verification. |
| Google Pay | ✅ | Supported in Australia and New Zealand. Not supported for card verification. |
| Android Pay or Samsung Pay | ❌ | |
| Venmo (PayPal) | ❌ | |
| Least Cost Routing (Electronic Funds Transfer at Point of Sale / EFTPOS) | ✅ | Supported in Australia. To enable this on an account, contact Fat Zebra. |
Data, descriptors, and fraud signals
The following table describes support for data fields, descriptors, and fraud signals in this integration.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration
| Capability | Support | Notes |
|---|---|---|
| Card Verification Value (CVV) response handling | ✅ | CVV match codes (M, N, U, I, S, A, B) are mapped. For more information, see CVV handling. |
| Dynamic descriptors | ✅ | Fat Zebra enforces a 35-character limit. Values that exceed this limit might be truncated or rejected. |
| Network tokens | ✅ | Supported in Australia and New Zealand. For more information, see Network token support. |
| Level 2 / Level 3 / Lodging data | ❌ | |
| 3D Secure (3DS) | ✅ | Supported, but not required. Braintree passes 3DS data (CAVV, dsTransactionId, ECI/SLI, version, XID) to Fat Zebra. |
Verifications
The following table describes the support for card verification methods with this integration.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by merchant configuration
| Capability | Support | Notes |
|---|---|---|
| $0 verification | ✅ | Fat Zebra adds a small amount and performs an authorization and a void to return a verification response if needed. |
| Non-zero dollar verification | ❌ | The amount that is sent in the verification call is ignored. |
| Wallet verification | ❌ | Apple Pay and Google Pay verifications are not supported. |
Before you begin
Confirm that you have the following accounts before you begin the integration:
- To process card transactions through Fat Zebra, you need currency-specific Braintree merchant accounts for your integration. Your Braintree account manager (AM) or technical account manager (TAM) can assist you in setting these up.
- A Fat Zebra account. Fat Zebra uses basic authentication (username and password). You will receive API credentials from Fat Zebra for the sandbox and production environments. For more information, see the Fat Zebra API documentation.
After completing setup, proceed to Transactions to create your first transaction.
Transactions
The following requirements apply to all Fat Zebra transactions:
- Cardholder name: All Fat Zebra transactions require
cardholderName. Payment method tokenization must include it. - CVV requirements: For recurring transactions or when using vaulted cards, the CVV might not be present. Fat Zebra accepts these transactions with the
card_on_fileflag set totrue, but this could affect approval rates. - Apple Pay and Google Pay: If you use Apple Pay or Google Pay, ensure that you enable wallet payment processing in your Fat Zebra merchant account.
- Webhooks: Webhooks are supported through Braintree for this integration, but they require specific configuration. To configure your account for webhooks, contact your AM or TAM.
- EFTPOS: To enable EFTPOS, contact Fat Zebra. Braintree supports EFTPOS only on charge (single step) transactions.
Use the Braintree platform for all transaction operations. Performing operations directly with Fat Zebra could cause discrepancies and synchronization errors to occur.
For general information about Braintree transactions, see:
Transaction creation
Creating a Fat Zebra transaction requires specific fields and field mappings. The following sections list the required fields and the fields that Braintree passes to Fat Zebra.
Required fields for Fat Zebra transactions
Creating a Fat Zebra transaction requires the following fields.
| Field | Location | How to provide | Notes |
|---|---|---|---|
amount | Transaction | In transaction | Transaction amount, converted to cents |
creditCard.number | Payment method | During tokenization | Card number. Test cards are remapped in the sandbox. |
creditCard.expirationMonth | Payment method | During tokenization | Format: MM |
creditCard.expirationYear | Payment method | During tokenization | Format: YYYYNote: Braintree combines creditCard.expirationMonth and creditCard.expirationYear and sends them to Fat Zebra as MM/YYYY. |
creditCard.cardholderName | Payment method | During tokenization | Required. Name as it appears on the card. |
Fields that Braintree passes to Fat Zebra
The following table maps Braintree fields to their corresponding Fat Zebra fields for authorize and charge operations.
| Braintree field | Fat Zebra field | Required | Notes |
|---|---|---|---|
creditCard.number | card_number | ✅ | Test cards are remapped in the sandbox environment. |
creditCard.cardholderName | card_holder | ✅ | Must be included during tokenization. |
creditCard.expirationMonth + expirationYear | card_expiry | ✅ | Format: MM/YYYY |
creditCard.cvv | cvv | Omitted for recurring or merchant-initiated transactions For more information, see CVV handling | |
amount | amount | ✅ | Converted to cents (×100 for 2-decimal currencies) |
currencyIsoCode | currency | ✅ | Three-letter ISO currency code, uppercase |
billing.postalCode | billing_address.postcode | ||
billing.streetAddress | billing_address.address | ||
customer.email | billing_address.email | ||
riskData.customerIp | customer_ip | The connector supplies a default value if one is not included. | |
descriptor.name | extra.descriptor.raw | Max 35 characters | |
threeDSecureData.cavv | extra.cavv | 3DS CAVV value | |
threeDSecureData.dsTransactionId | extra.directory_server_txn_id | 3DS Directory Server Transaction ID | |
threeDSecureData.eciFlag | extra.sli | 3DS Security Level Indicator | |
threeDSecureData.version | extra.threeds_version | For example, 2.0.0 | |
threeDSecureData.xId | extra.xid | 3DS XID value | |
vaultedCredentialType | extra.ecm | eCommerce indicator: 31 (customer-initiated transaction / CIT) or 32 (MIT) | |
networkTransactionIdentifier | extra.authorization_tracking_id | Included for merchant-initiated transactions |
Customer creation
A Fat Zebra integration does not require customer creation. If you choose to create a customer, you can do it using either the Braintree SDKs or GraphQL API. Customer email, when available, is passed to Fat Zebra. For more information, see the customer creation guide (SDK) or the customer creation guide (GraphQL).
Vaulted payment methods
Vaulting a tokenized payment method creates a reusable token that can be authorized or charged multiple times. You can vault a payment method in 2 ways:
- Direct vaulting of an already-tokenized payment method.
- During the authorization process using the SDK or GraphQL API.
Transaction object support
The following topics describe support for transaction operations and CVV handling with this integration.
Supported transaction operations
The following table lists the transaction request fields that this integration supports.
Legend: ✅ Supported | ❌ Not supported | ⚠️ Conditional or varies by country, merchant configuration, or processor |
| Transaction operation | Supported |
|---|---|
| Sale | ✅ |
| Find | ✅ |
| Void | ✅ |
| Refund | ✅ |
| Submit for settlement | ✅ |
| Clone | ✅ |
| Search | ✅ |
| Adjust Authorization | ❌ |
| Hold in Escrow | ❌ |
| Release from Escrow | ❌ |
| Submit for Partial Settlement | ❌ |
| Cancel Release | ❌ |
CVV handling
For merchant-initiated transactions, such recurring transactions, or when using vaulted cards, Braintree does not send the CVV to Fat Zebra. Instead, the card_on_file and omit_expiry flags are set to true, and the authorization_tracking_id from the original transaction is included if provided by Fat Zebra.
Transaction status
The following table maps Fat Zebra response statuses to Braintree transaction statuses. For general information about Braintree result objects, see Result Objects.
| Operation | Fat Zebra response | Braintree transaction status | Additional information |
|---|---|---|---|
| Authorize | Approved (codes: 00, 08, 10, 11, 16) | AUTHORIZED | Transaction is authorized and must be captured before expiry. Authorization expires after 5 calendar days. |
| Authorize | Declined (any non-approved code) | PROCESSOR_DECLINED | Hard decline from acquirer |
| Authorize | API error | FAILED | You can configure a retry option on Braintree for this or implement your own retry logic. |
| Charge | Approved | SETTLED | Authorization and immediate capture |
| Charge | Declined | PROCESSOR_DECLINED | Hard decline from acquirer |
| Charge | API error | FAILED | Rare case. Braintree will reconcile this transaction. For more information, see FAILED status during charge. |
| Capture | Approved | SETTLED | |
| Capture | Declined | SETTLEMENT_DECLINED | This can occur if the authorization has expired or there is an amount mismatch. |
| Capture | API error | SETTLING | Rare event. Braintree will reconcile the transaction. Do not ship goods or provide service until the status transitions to SETTLED. For more information, see SETTLING status with HTTP errors. |
| Refund | Approved | SETTLED | |
| Refund | Declined | SETTLEMENT_DECLINED | |
| Refund | API error | SETTLING | Rare event. Braintree will reconcile the transaction. For more information, see SETTLING status with HTTP errors. |
| Void | Voided (success or already voided) | VOIDED | Idempotent. Returns VOIDED even if Fat Zebra has already cancelled the transaction. |
| VerifyCard | Approved | VERIFIED | |
| VerifyCard | Declined | PROCESSOR_DECLINED | |
| VerifyCard | API error | FAILED |
SETTLING status with HTTP errors
The following situations might occur with SETTLING status.
In the rare event that Fat Zebra returns HTTP 4xx or 5xx errors during capture or refund operations, the transaction might remain in SETTLING status while Braintree reconciles the outcome. This can happen due to network or server overload or Fat Zebra API unavailability.
When Braintree queries Fat Zebra for transaction status for capture, refund, and charge, the possible outcomes are:
- If Fat Zebra approves, the status changes to
SETTLED. - If Fat Zebra declines, the status changes to
SETTLEMENT_DECLINED.
FAILED status during charge
This is another rare event that could occur. If Braintree receives no inline response from Fat Zebra due to network errors or timeouts, the transaction status is set to FAILED. Braintree will reconcile this transaction. If the transaction is identified as successful during reconciliation, the status is updated from FAILED to SETTLED and a refund is automatically initiated. The refund follows its own transaction lifecycle (SETTLED, SETTLEMENT_DECLINED, SETTLING, or FAILED). The original transaction remains SETTLED.
Retries
Follow these guidelines when you handle retries for Fat Zebra transactions:
- Do not build a duplicate capture or refund retry loop when you see
success: truebut the status isSETTLING. - 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 or Search) using your internal transaction reference (
transactionId) before attempting a second create. - Retry on
FAILEDtransactions can be configured at the merchant account level. Reach out to your TAM for configuration.
Network tokens
Fat Zebra supports network tokens. The integration includes two provisioning options:
- Braintree-managed network tokens: Braintree provisions and manages network tokens on your behalf.
- Bring Your Own Network Token: Use network tokens you've provisioned through another provider.
To enable Braintree-managed network tokens for your account, contact your AM or Integration Engineer. See the Getting Started with Network Tokens guide for more information.
Response codes
Braintree can only display a limited number of response codes since transaction results are controlled by Fat Zebra. When Fat Zebra decline codes cannot be mapped to equivalent Braintree decline codes, Braintree returns code 2000 with message Do Not Honor.
To query for the Fat Zebra response message, use:
- SDK:
additional_processor_response - GraphQL:
PaymentStatusEvent.processorResponse.additionalInformation
Processor response pass-through and debugging
Because approval and decline outcomes are controlled by Fat Zebra, Braintree may surface a limited set of standardized result codes. Where to find processor response details:
- SDK:
additional_processor_response - GraphQL:
TransactionSettlementProcessorResponseandTransactionAuthorizationProcessorResponse
CVV response code mapping
The following table maps Fat Zebra CVV match codes to their Braintree equivalents.
| Fat Zebra CVV match | Braintree CVV response code | Meaning |
|---|---|---|
| M | M | Match |
| N | N | No match |
| U | U | Not checked / unavailable |
| I | I | Invalid |
| S | S | Issuer does not support CVV |
| A | A | Not applicable |
| B | B | Not provided |
Failure response code mapping
Fat Zebra uses 2-digit numeric response codes:
- Approved codes (transaction succeeds):
00,08,10,11,16 - Retryable system error codes:
09,99
| Braintree error code | Braintree error message | Fat Zebra response code | Fat Zebra message |
|---|---|---|---|
2000 | Do Not Honor | 01 | Refer to card issuer |
2000 | Do Not Honor | 02 | Refer to card issuer |
2000 | Do Not Honor | 05 | Refer to card issuer |
2000 | Do Not Honor | 17 | Declined |
2000 | Do Not Honor | 18 | Declined |
2000 | Do Not Honor | 20 | Declined |
2000 | Do Not Honor | 21 | Declined |
2000 | Do Not Honor | 22 | Declined |
2000 | Do Not Honor | 24 | Declined |
2000 | Do Not Honor | 25 | Declined |
2000 | Do Not Honor | 26 | Declined |
2000 | Do Not Honor | 27 | Declined |
2000 | Do Not Honor | 28 | Declined |
2000 | Do Not Honor | 29 | Declined |
2000 | Do Not Honor | 32 | Declined |
2000 | Do Not Honor | 45 | Declined |
2000 | Do Not Honor | 46 | Declined |
2000 | Do Not Honor | 47 | Declined |
2000 | Do Not Honor | 48 | Declined |
2000 | Do Not Honor | 49 | Declined |
2000 | Do Not Honor | 50 | Declined |
2000 | Do Not Honor | 52 | Declined |
2000 | Do Not Honor | 53 | Declined |
2000 | Do Not Honor | 57 | Declined |
2000 | Do Not Honor | 58 | Declined |
2000 | Do Not Honor | 60 | Declined |
2000 | Do Not Honor | 63 | Declined |
2000 | Do Not Honor | 64 | Declined |
2000 | Do Not Honor | 66 | Declined |
2000 | Do Not Honor | 67 | Declined |
2000 | Do Not Honor | 68 | Declined |
2000 | Do Not Honor | 69 | Declined |
2000 | Do Not Honor | 70 | Declined |
2000 | Do Not Honor | 71 | Declined |
2000 | Do Not Honor | 72 | Declined |
2000 | Do Not Honor | 73 | Declined |
2000 | Do Not Honor | 74 | Declined |
2000 | Do Not Honor | 76 | Declined |
2000 | Do Not Honor | 77 | Declined |
2000 | Do Not Honor | 78 | Declined |
2000 | Do Not Honor | 79 | Declined |
2000 | Do Not Honor | 80 | Declined |
2000 | Do Not Honor | 81 | Declined |
2000 | Do Not Honor | 83 | Declined |
2000 | Do Not Honor | 84 | Declined |
2000 | Do Not Honor | 85 | Declined |
2000 | Do Not Honor | 86 | Declined |
2000 | Do Not Honor | 87 | Declined |
2000 | Do Not Honor | 88 | Declined |
2000 | Do Not Honor | 89 | Declined |
2000 | Do Not Honor | 90 | Declined - please retry |
2000 | Do Not Honor | 95 | Declined |
2001 | Insufficient Funds | 51 | Insufficient funds |
2002 | Limit Exceeded | 61 | Declined |
2002 | Limit Exceeded | 65 | Declined |
2004 | Expired Card | 33 | Expired card |
2004 | Expired Card | 54 | Expired card |
2005 | Invalid Credit Card Number | 14 | Invalid card number |
2007 | No Account | 39 | Declined |
2007 | No Account | 56 | Declined |
2009 | No Such Issuer | 15 | No issuer |
2009 | No Such Issuer | 31 | Bank not supported |
2010 | Card Issuer Declined CVV | 82 | Declined |
2012 | Processor Declined - Possible Lost Card | 04 | Refer to card issuer |
2014 | Processor Declined - Fraud Suspected | 34 | Declined |
2014 | Processor Declined - Fraud Suspected | 59 | Declined |
2016 | Duplicate Transaction | 94 | Declined |
2019 | Invalid Transaction | 12 | Invalid transaction |
2019 | Invalid Transaction | 30 | Declined |
2019 | Invalid Transaction | 40 | Declined |
2020 | Violation | 93 | Declined |
2025 | Set Up Error - Merchant | 03 | No merchant |
2026 | Invalid Merchant ID | 06 | Merchant/acquirer error |
2027 | Set Up Error – Amount | 19 | Declined |
2047 | Call Issuer. Pick Up Card | 07 | Refer to card issuer |
2047 | Call Issuer. Pick Up Card | 35 | Declined |
2047 | Call Issuer. Pick Up Card | 37 | Declined |
2048 | Invalid Amount | 13 | Invalid amount |
2048 | Invalid Amount | 23 | Declined |
2050 | Invalid Credit Plan | 42 | Declined |
2050 | Invalid Credit Plan | 44 | Declined |
2053 | Card reported as lost or stolen | 41 | Declined |
2053 | Card reported as lost or stolen | 43 | Declined |
2057 | Issuer or Cardholder has put a restriction on the card | 36 | Declined |
2057 | Issuer or Cardholder has put a restriction on the card | 62 | Declined |
2102 | Incorrect PIN | 55 | Declined |
2103 | PIN try exceeded | 38 | Declined |
2103 | PIN try exceeded | 75 | Declined |
3000 | Processor Network Unavailable – Try Again | 09 | Acquirer busy |
3000 | Processor Network Unavailable – Try Again | 91 | Declined |
3000 | Processor Network Unavailable – Try Again | 92 | Declined |
3000 | Processor Network Unavailable – Try Again | 96 | Declined |
3000 | Processor Network Unavailable – Try Again | 99 | System error - contact gateway if error persists |
Test cards
Braintree provides a set of test card numbers for sandbox testing. With the Fat Zebra integration, some Braintree test card numbers are automatically mapped to Fat Zebra test card numbers.
Because credit cards are mapped in sandbox to facilitate end-to-end testing, there may be discrepancies in reporting in sandbox.
Credit cards: Success
The following test cards return a successful response in the sandbox environment.
| Card brand | Braintree test number | Fat Zebra test number | Automatically mapped? |
|---|---|---|---|
| Mastercard | 2223000048400011 | 5123456789012346 | ✅ |
| Mastercard | 5555555555554444 | 5555555555554444 | Pass-through |
| Visa | 4005519200000004 | 4005550000000001 | ✅ |
| Visa | 4111111111111111 | 4111111111111111 | Pass-through |
Credit cards: Failure
To trigger a specific error response code in the sandbox environment, use any success test card and append the desired error code to the amount as the last 2 digits in the decimal.
For example:
- To trigger error code
15(No Issuer), use amount100.15. - To trigger insufficient funds (
51), use amount100.51.
For a full list of Fat Zebra failure response codes, see Failure response code mapping.
Apple Pay test cryptograms
In sandbox, Braintree masks Apple Pay cryptograms. The connector automatically maps the standard Braintree sandbox Apple Pay cryptogram to a Fat Zebra-compatible test value.
Related content
The following resources provide additional information about Fat Zebra and Braintree transactions.