Braintree data mapping

  • Verified
    • 8 min

    Table of contents

    Data sources

    Once you set up your Braintree integration, Leapfin uses a combination of Braintree SDK and GraphQL API to fetch information related to transactions, fees, discounts, plans, and customers from Braintree.

    Braintree transaction object

    The transaction object from Braintree is a record that includes all details of a transaction, including current status as well as status history. For more details, see Braintree Transaction.

    Each transaction object is imported as a braintree-transaction record on the Leapfin Platform.

    { "id": "fqnycvx", "type": "sale", "addOns": [ ], "amount": "57.60", "planId": null, "status": "settled", "billing": { "id": null, "region": null, "company": null, "lastName": null, "locality": null, "firstName": null, "postalCode": null, "countryName": null, "streetAddress": null, "extendedAddress": null, "countryCodeAlpha2": null, "countryCodeAlpha3": null, "countryCodeNumeric": null }, "channel": "Spreedly_BT", "orderId": "156837e8-ab08-11e9-944f-0242dd998877", "applePay": { "bin": "465876", "debit": "No", "last4": "1037", "token": null, "payroll": "No", "prepaid": "No", "cardType": "Apple Pay - Visa", "globalId": null, "imageUrl": "https://assets.braintreegateway.com/payment_method_logo/apple_pay.png?environment=production", "productId": "A", "commercial": "No", "healthcare": "No", "issuingBank": "U.S. Bank National Association-Credit", "cardholderName": null, "expirationYear": "2022", "durbinRegulated": "No", "expirationMonth": "04", "countryOfIssuance": "USA", "sourceDescription": "Visa 1037", "paymentInstrumentName": "Visa 1037" }, "customer": { "id": null, "fax": null, "email": null, "phone": null, "company": null, "website": null, "lastName": null, "firstName": null }, "disputes": [ ], "globalId": "dHJhbnNhY3Rpb25fZnFueTJ8888", "refundId": null, "retryIds": [ ], "shipping": { "id": null, "region": null, "company": null, "lastName": null, "locality": null, "firstName": null, "postalCode": null, "countryName": null, "streetAddress": null, "extendedAddress": null, "countryCodeAlpha2": null, "countryCodeAlpha3": null, "countryCodeNumeric": null }, "createdAt": "2019-07-20T16:04:42Z", "discounts": [ ], "recurring": false, "refundIds": [ ], "taxAmount": null, "taxExempt": false, "updatedAt": "2019-07-20T17:53:18Z", "creditCard": { "bin": null, "debit": "Unknown", "last4": null, "token": null, "payroll": "Unknown", "prepaid": "Unknown", "cardType": null, "globalId": null, "imageUrl": "https://assets.braintreegateway.com/payment_method_logo/unknown.png?environment=production", "venmoSdk": false, "productId": "Unknown", "commercial": "Unknown", "healthcare": "Unknown", "accountType": null, "issuingBank": "Unknown", "accountBalance": null, "cardholderName": null, "expirationYear": "", "durbinRegulated": "Unknown", "expirationMonth": "", "customerLocation": null, "countryOfIssuance": "Unknown", "uniqueNumberIdentifier": null }, "descriptor": { "url": null, "name": null, "phone": null }, "pinVerified": false, "customFields": "", "debitNetwork": null, "escrowStatus": "released", "installments": [ ], "merchantName": "Company X", "subscription": { "billingPeriodEndDate": null, "billingPeriodStartDate": null }, "statusHistory": [ { "statusEvent": { "user": "usexxx", "amount": "57.60", "status": "authorized", "timestamp": "2019-07-20T16:04:43Z", "transactionSource": "api" } }, { "statusEvent": { "user": "usexxx", "amount": "57.60", "status": "submitted_for_settlement", "timestamp": "2019-07-20T16:05:25Z", "transactionSource": "api" } }, { "statusEvent": { "amount": "57.60", "status": "settled", "timestamp": "2019-07-20T17:53:18Z", "transactionSource": "" } } ], "discountAmount": null, "paymentReceipt": { "id": "fqny2vtx", "type": "sale", "amount": "57.60", "globalId": "dHJhbnNhY3Rpb25fZnFueTJ8888", "pinVerified": false, "merchantName": "Company X", "processingMode": null, "currencyIsoCode": "USD", "merchantAddress": { "phone": "888-888-8888", "region": "NY", "locality": "New York", "postalCode": "10003", "streetAddress": null }, "processorResponseCode": "1000", "processorResponseText": "Approved", "processorAuthorizationCode": "110999", "merchantIdentificationNumber": "445373412134", "terminalIdentificationNumber": "00000001" }, "processingMode": null, "retryGlobalIds": [ ], "shippingAmount": null, "subscriptionId": null, "amountRequested": null, "currencyIsoCode": "USD", "cvvResponseCode": "I", "merchantAddress": { "phone": "888-888-8888", "region": "NY", "locality": "New York", "postalCode": "10003", "streetAddress": null }, "refundGlobalIds": [ ], "responseEmvData": null, "installmentCount": null, "serviceFeeAmount": "14.40", "threeDSecureInfo": null, "merchantAccountId": "xya_instant_ccdegeh", "settlementBatchId": "2019-07-20_xya_instant_ccdegeh", "disbursementDetails": { "success": true, "fundsHeld": false, "disbursementDate": "2019-07-22", "settlementAmount": "57.60", "settlementCurrencyIsoCode": "USD", "settlementCurrencyExchangeRate": "1", "settlementBaseCurrencyExchangeRate": null }, "networkResponseCode": "00", "networkResponseText": "Successful approval/completion or V.I.P. PIN verification is successful", "purchaseOrderNumber": null, "shipsFromPostalCode": null, "voiceReferralNumber": null, "avsErrorResponseCode": null, "networkTransactionId": "309201578899999", "refundedInstallments": [ ], "retriedTransactionId": null, "subMerchantAccountId": "xya_instant_ccdegeh", "paymentInstrumentType": "apple_pay_card", "processorResponseCode": "1000", "processorResponseText": "Approved", "processorResponseType": "approved", "refundedTransactionId": null, "scaExemptionRequested": null, "authorizationExpiresAt": "2019-07-27T16:04:43Z", "gatewayRejectionReason": null, "acquirerReferenceNumber": "24492159201713957109880", "authorizedTransactionId": null, "masterMerchantAccountId": "complay_x_plat", "authorizationAdjustments": [ ], "retrievalReferenceNumber": null, "accountFundingTransaction": false, "avsPostalCodeResponseCode": "I", "processedWithNetworkToken": false, "processorAuthorizationCode": "110240", "retriedTransactionGlobalId": null, "additionalProcessorResponse": null, "refundedTransactionGlobalId": null, "avsStreetAddressResponseCode": "I", "merchantIdentificationNumber": "445373412134", "terminalIdentificationNumber": "00000001", "authorizedTransactionGlobalId": null, "partialSettlementTransactionIds": [ ], "processorSettlementResponseCode": "4000", "processorSettlementResponseText": "Confirmed", "partialSettlementTransactionGlobalIds": [ ] }
    { "id": "fqnycvx", "type": "sale", "addOns": [ ], "amount": "57.60", .... "disputes": [ { "dispute":{ "id":"5c8hmhdb43y4n7xx", "kind":"chargeback", "amount":"5.00", "reason":"product_unsatisfactory", "status":"won", "dateWon":"2018-12-14", "evidence":[ { "evidence":{ "id":"6mr6ytwtmv37rc7h", "url":"https://bt-production-arbiter-evidence-files.s3.amazonaws.com/foo", "comment":null, "category":"PROOF_OF_POSSESSION_OR_USAGE", "createdAt":"2018-12-05T18:02:56Z", "sequenceNumber":null, "sentToProcessorAt":null } }, { "evidence":{ "id":"py433w6bdgqzk752", "url":"https://bt-production-arbiter-evidence-files.s3.amazonaws.com/bar", "comment":null, "category":null, "createdAt":"2018-12-05T18:03:04Z", "sequenceNumber":null, "sentToProcessorAt":null } }, { "evidence":{ "id":"59fydnpyxpqtx5k9", "url":null, "comment":"OTHER", "category":"EVIDENCE_TYPE", "createdAt":"2018-12-05T18:02:54Z", "sequenceNumber":null, "sentToProcessorAt":null } } ], "globalId":"ZGlzcHV0ZV81YzhobWhkYjQzeTRuN3h4", "amountWon":"5.00", "createdAt":"2018-12-05T15:52:59Z", "updatedAt":"2018-12-14T00:18:48Z", "caseNumber":"PP-007-615-241-883", "dateOpened":"2018-12-05", "reasonCode":null, "replyByDate":"2018-12-28", "transaction":{ "id":"825g0cpf", "amount":"5.00", "orderId":"charge104388776", "globalId":"dHJhbnNhY3Rpb25fODI1ZzBjcGY", "createdAt":"2018-12-04T13:09:23Z", "purchaseOrderNumber":null, "paymentInstrumentSubtype":"paypal_account" }, "receivedDate":"2018-12-05", "statusHistory":[ { "statusHistory":{ "status":"won", "timestamp":"2018-12-14T00:18:48Z", "effectiveDate":"2018-12-14", "disbursementDate":null } }, { "statusHistory":{ "status":"disputed", "timestamp":"2018-12-05T18:02:57Z", "effectiveDate":"2018-12-05", "disbursementDate":null } }, { "statusHistory":{ "status":"open", "timestamp":"2018-12-05T15:53:00Z", "effectiveDate":"2018-12-05", "disbursementDate":null } } ], "amountDisputed":"5.00", "currencyIsoCode":"USD", "referenceNumber":null, "responseDeadline":"2018-12-27T05:59:59Z", "merchantAccountId":"Patreon_instant", "originalDisputeId":null, "processorComments":"Buyer (2018-12-05T15:41:56.000Z): 商品存在严重漏洞，导致封停账号，要求退钱！\n\nBuyer (2018-12-05T15:47:08.000Z): 商品存在严重漏洞，导致封停账号，要求退钱！", "reasonDescription":null, "processorReplyByDate":"2018-12-29" } } ], ... }

    Payment-Level Fee Report

    The payment-level fee report, formerly known as the transaction-level fee report, provides a breakdown of fees per individual payment, encompassing transactions and refunds. For more details, refer to the Braintree document here.

    Each row of the report is imported as a braintree-fee record on the Leapfin Platform. Unfortunately, Braintree provides documentation about the data schema of the payment-level fee report. So far, Leapfin has seen two variations: one with interchange fees and one without.

    Interchange Fee Estimates:

    The interchange fees on Braintree's payment-level fee report are estimated values. They may be adjusted through a reclassification process. The actual interchange fees are only available in aggregated sum at the end of the month. For more details, refer to the Braintree document here.

    Though such estimated interchange fees are available on the Leapfin Platform, accurate reconciliation is not achievable.

    Braintree Fees:

    The fee information is spread across both the Braintree transaction object and the Payment-level fee report. For payment instrument type "paypal_account", the fee information is contained in the Braintree transaction object. All other types are included in the fee report.

    { "OrderID": "9qeJGA3Rry4pYWQSG5rPGjPPIs6", "CardType": "Credit", "Discount": "0.08", "CardBrand": "American Express", "First6OfCC": "379777", "IssuingBank": "", "ExchangeRate": "1.00", "TransactionID": "jbq2abct", "DiscountCredit": "0", "RefundedAmount": "0.00", "SettlementDate": "2018-03-24", "TransactionType": "sale", "DisbursementDate": "2018-03-26", "SettlementAmount": "1.00", "MerchantAccountID": "company_x", "PaymentInstrument": "credit_card", "PerTransactionFee": "0.05", "CardIssuingCountry": "USA", "Est.TotalFeeAmount": "0.07", "SettlementCurrency": "USD", "Est.InterchangeRate": "", "InterchangeCurrency": "", "PresentmentCurrency": "USD", "BraintreeTotalAmount": "0.07", "Est.InterchangeFixed": "", "OriginalTransactionID": "", "InterchangeDescription": "", "AcquirerReferenceNumber": "", "PerTransactionFeeCredit": "0.00", "Est.InterchangeRateCredit": "", "Est.InterchangeFixedCredit": "", "Est.InterchangeTotalAmount": "" }
    { "OrderID": "", "CardType": "Credit", "Discount": "0.0290", "CardBrand": "Visa", "First6OfCC": "426999", "RefundType": "", "IssuingBank": "JPMorgan Chase Bank N.A.", "ExchangeRate": "1.000000000", "TransactionID": "1aqs8752", "DiscountCredit": "0.0000", "RefundedAmount": "0.00", "SettlementDate": "2022-01-30", "TotalFeeAmount": "0.44", "TransactionType": "sale", "DisbursementDate": "2022-02-01", "SettlementAmount": "5.00", "MerchantAccountID": "company_x_y", "PaymentInstrument": "credit_card", "PerTransactionFee": "0.30", "CardIssuingCountry": "USA", "OriginalSaleAmount": "", "SettlementCurrency": "USD", "PresentmentCurrency": "USD", "BraintreeTotalAmount": "0.44", "OriginalTransactionID": "", "MulticurrencyFeeAmount": "0.00", "MulticurrencyFeeCredit": "0.00", "AcquirerReferenceNumber": "24493332030715701799999", "PerTransactionFeeCredit": "0.00" }

    Braintree discount object

    A discount object from Braintree contains details of discounts applied on a transaction. For more details, refer to Braintree Discount.

    Each discount object is imported as a braintree-discount record on the Leapfin Platform.

    Note: Discount information is already included as part of braintree-transaction record. Leapfin imports it as a separate record for quick reference since braintree-transaction contains lots of information.

    { "id": "discount-build-from-scratch", "kind": "discount", "name": "discount-build-from-scratch", "amount": "49.97", "createdAt": "2017-10-11T17:54:36Z", "updatedAt": "2017-10-11T17:54:36Z", "merchantId": "vg80yw7vz9sxxxxc", "description": "", "neverExpires": false, "numberOfBillingCycles": 1 }

    Braintree plan object

    The plan object from Braintree contains details of the plan associated with a transaction. For more details, refer to the Braintree Plan. Each plan object is imported as a braintree-plan record on the Leapfin Platform.

    { "id": "proYear", "name": "Company X Pro", "price": "199.99", "addOns": [ ], "createdAt": "2016-02-01T21:49:10Z", "discounts": [ ], "updatedAt": "2016-02-01T21:49:10Z", "merchantId": "vgc6yw7vz9s1234c", "description": "", "trialPeriod": false, "trialDuration": null, "currencyIsoCode": "USD", "billingFrequency": 12, "billingDayOfMonth": null, "trialDurationUnit": null, "numberOfBillingCycles": null }

    Braintree customer object

    The customer object from Braintree contains details of the customer. For more details, refer to Braintree Customer. Each customer object is imported as a braintree-customer record on the Leapfin Platform.

    Note: PII information, such as address, email, name, and phone is removed by default during the import process.

    { "id": "101059999", "company": "company x y", "website": null, "globalId": "Y3VzdG9tZXJfMTAxMDUkd8Ne", "createdAt": "2016-08-06T19:52:31Z", "updatedAt": "2016-08-06T19:52:31Z", "merchantId": "6zjs2n92yxcpo0w8", "customFields": "" }

    Data mapping logics

    braintree-transaction

    Leapfin imports each Braintree transaction object as a braintree-transaction record, which contains payment, refund, dispute, payout, and fee information. When mapping data, Leapfin creates multiple accounting records from each braintree-transaction record, as detailed below:

    Payment record creation

    A Payment record is created for each braintree-transaction record with type = "sale".

    Target: LeapfinPayment (schema)

    Source: braintree-transaction (schema)

    Target: LeapfinPayment (schema)

    Source: braintree-transaction (schema)

    objectType

    "payment"

    id

    braintree-transaction.id

    amount

    braintree-transaction.amount

    currencyCode

    braintree-transaction.currencyIsoCode

    date

    braintree-transaction.createdAt

    status

    fetch the latest statusEvent from braintree-transaction.statusHistory[]. If statusEvent.status = "settled", then set status as "succeeded". Else if statusEvent.status is ”AuthorizationExpired”, “Failed”, “GatewayRejected”, “ProcessorDeclined”, “SettlementDeclined” or “Voided”, then set status as "failed". Otherwise, set status as "pending".

    succeededDate

    fetch the latest statusEvent from braintree-transaction.statusHistory[]. If statusEvent.status = "settled", then set succeededDate as statusEvent.timestamp.

    description

    braintree-transaction.orderId

    exchangeRates

    if braintree-transaction.disbursementDetails.settlementCurrencyIsoCode exists and differs from braintree-transaction.currencyIsoCode, then add following exchange rate:

    • rate = braintree-transaction.disbursementDetails.settlementCurrencyExchangeRate

    • currencyCode = braintree-transaction.disbursementDetails.settlementCurrencyIsoCode

    customFields

    The following fields from the source record are added:

    • paymentInstrumentType = braintree-transaction.paymentInstrumentType

    • serviceFeeAmount = braintree-transaction.serviceFeeAmount

    • settlementAmount = braintree-transaction.disbursementDetails.settlementAmount

    • settlementCurrencyCode = braintree-transaction.disbursementDetails.settlementCurrencyIsoCode

    links

    Leapfin creates a link to the Payout object.

    Refund record creation

    A Refund record is created for each braintree-transaction record with type = "credit".

    Target: LeapfinRefund (schema)

    Source: braintree-transaction (schema)

    Target: LeapfinRefund (schema)

    Source: braintree-transaction (schema)

    objectType

    "refund"

    id

    braintree-transaction.id

    amount

    braintree-transaction.amount

    currencyCode

    braintree-transaction.currencyIsoCode

    date

    braintree-transaction.createdAt

    status

    fetch the latest statusEvent from braintree-transaction.statusHistory[]. If statusEvent.status = "settled", then set status as "succeeded". Else if statusEvent.status is ”AuthorizationExpired”, “Failed”, “GatewayRejected”, “ProcessorDeclined”, “SettlementDeclined” or “Voided”, then set status as "failed". Otherwise, set status as "pending".

    exchangeRates

    if braintree-transaction.disbursementDetails.settlementCurrencyIsoCode exists and differs from braintree-transaction.currencyIsoCode, then add following exchange rate:

    • rate = braintree-transaction.disbursementDetails.settlementCurrencyExchangeRate

    • currencyCode = braintree-transaction.disbursementDetails.settlementCurrencyIsoCode

    customFields

    The following fields from the source record are added:

    • paymentInstrumentType = braintree-transaction.paymentInstrumentType

    • settlementAmount = negative braintree-transaction.disbursementDetails.settlementAmount

    • settlementCurrencyCode = braintree-transaction.disbursementDetails.settlementCurrencyIsoCode

    links

    Add a link to the associated Payment record with:

    • objectType = "payment"

    • id = braintree-transaction.refundedTransactionId

    Dispute record creation

    A Dispute record is created for each item in braintree-transaction.disputes[].

    Target: LeapfinDispute (schema)

    Source: braintree-transaction (schema)

    Target: LeapfinDispute (schema)

    Source: braintree-transaction (schema)

    objectType

    "dispute"

    id

    braintree-transaction.disputes\[].id

    amount

    braintree-transaction.disputes\[].amountDisputed

    currencyCode

    braintree-transaction.disputes\[].currencyIsoCode

    date

    braintree-transaction.disputes\[].createdAt

    status

    if braintree-transaction.disputes\[].status is "lost", "accepted" or "expired" set status as "lost".
    else if braintree-transaction.disputes\[].status is "won", set status as "won".
    otherwise, set status as "pending".

    description

    braintree-transaction.disputes\[].reason

    initiatedDate

    if there is an item in braintree-transaction.disputes[].statusHistory[] with statusHistory.status = "open", then set initiatedDate as statusHistory.stimestamp.
    otherwise, set initiatedDate as braintree-transaction.disputes[].dateOpened.

    resolvedDate

    fetch is the latest statusHistory from braintree-transaction.disputes[].statusHistory[], if statusHistory.status is "won", "lost", "accepted" or "expired", then set resolvedDate as statusHistory.timestamp.
    if above is not available, set resolvedDate as braintree-transaction.disputes\[].dateWon.

    exchangeRates

    None

    customFields

    None

    links

    Add a link to the associated Payment record with:

    • objectType = "payment"

    • id = braintree-transaction.id

    Fee record creation

    A Fee record is created for each braintree-transaction record with paymentInstrumentType = "paypal_account".

    Target: LeapfinFee (schema)

    Source: braintree-transaction (schema)

    Target: LeapfinFee (schema)

    Source: braintree-transaction (schema)

    objectType

    "fee"

    id

    use braintree-transaction.id as id. Add braintree-transaction.paymentInstrumentType as suffix.

    amount

    braintree-transaction.paypal.transactionFeeAmount

    currencyCode

    braintree-transaction.paypal.transactionFeeCurrencyIsoCode

    date

    if there is an item in braintree-transaction.statusHistory[] with statusEvent.status = "settled", then set date as statusEvent.stimestamp.
    otherwise, set date as braintree-transaction.createdAt.

    description

    braintree-transaction.paypal.description

    exchangeRates

    None

    customFields

    The following fields from the source record are added:

    • paymentInstrumentType = braintree-transaction.paymentInstrumentType

    • refundFromTransactionFeeAmount = braintree-transaction.paypal.refundFromTransactionFeeAmount

    • refundFromTransactionFeeCurrencyCode = braintree-transaction.paypal.refundFromTransactionFeeCurrencyIsoCode

    links

    if braintree-transaction.type = "sales", add a link to the associated Payment record with:

    • objectType = "payment"

    • id = braintree-transaction.id
      if braintree-transaction.type = "credit", add a link to the associated Payment record with:

    • objectType = "refund"

    • id = braintree-transaction.id

    Payout record creation

    A Payout record is created for each braintree-transaction record which has a non-empty value in disbursementDetails.disbursementDate.

    Target: LeapfinSettlement (schema)

    Source: braintree-transaction (schema)

    Target: LeapfinSettlement (schema)

    Source: braintree-transaction (schema)

    objectType

    "payout"

    id

    braintree-transaction.id

    amount

    braintree-transaction.disbursementDetails.settlementAmount

    currencyCode

    braintree-transaction.disbursementDetails.settlementCurrencyIsoCode

    date

    braintree-transaction.disbursementDetails.disbursementDate

    status

    if braintree-transaction.disbursementDetails.success is true, set status as "paid". Otherwise, set status as "failed".

    description

    ""

    exchangeRates

    None

    customFields

    None

    links

    • If braintreeTransaction.type = ‘sale’, Leapfin links to the payment record.

    • Else, if braintreeTransaction.type = ‘credit’, Leapfin links to the refund record.

    braintree-fee

    Leapfin imports each row in the payment-level fee report as a braintree-fee record. There are two possible schemas for the record: one with interchange fees and one without. When mapping data, Leapfin creates a Fee record for each braintree-transaction record, considering both schemas.

    Fee record creation

    A Fee record is created for each braintree-fee record.

    Target: LeapfinFee (schema)

    Source: braintree-fee (schema)

    Target: LeapfinFee (schema)

    Source: braintree-fee (schema)

    objectType

    "fee"

    id

    use braintree-fee.TransactionID as id. Add braintree-fee.PaymentInstrument as suffix.

    amount

    use braintree-fee."Est.TotalFeeAmount" if exists (for records with interchange fee). Otherwise, use braintree-fee.TotalFeeAmount (for record without interchange fee).

    currencyCode

    braintree-fee.PresentmentCurrency

    date

    braintree-fee.SettlementDate

    description

    ""

    exchangeRates

    None

    customFields

    The following fields from the source record are added:

    • paymentInstrumentType = braintree-fee.PaymentInstrument

    • braintreeTotalAmount = braintree-fee.BraintreeTotalAmount

    • interchangeTotalAmount = braintree-fee."Est.InterchangeTotalAmount"

    • multicurrencyFeeAmount = braintree-fee.MulticurrencyFeeAmount

    links

    if braintree-fee.TransactionType = "sales", add a link to the associated Payment record with:

    • objectType = "payment"

    • id = braintree-fee.TransactionID
      if braintree-fee.TransactionType = "credit", add a link to the associated Payment record with:

    • objectType = "refund"

    • id = braintree-fee.TransactionID

    Related content