Braintree Onboarding

​

Overview

Nevermined supports Braintree as a fiat settlement provider alongside Stripe. Sellers who connect a Braintree merchant account can price their plans in Braintree-supported currencies and receive funds directly into their own Braintree gateway, while Nevermined collects the platform fee on the same card transaction. This page covers the seller-side setup: connecting your Braintree account, configuring per-currency merchant accounts, and what to expect at plan creation and settlement time. If you only need to pay for a Braintree-priced plan as a buyer, see Card Enrollment → Braintree instead.

​

Why Braintree?

Use Braintree when:

• You already operate on Braintree and want funds to land directly in your existing gateway.
• You need merchant-of-record relationships under your own underwriting agreements (per currency).
• You want a uniform transaction.sale settlement on both subscription checkout and per-request x402 charges, without holding a Stripe Connected Account.

Stripe remains the right choice when you want the simplest onboarding (Stripe Connect express) and don’t have a multi-currency requirement that maps cleanly to Braintree’s child merchant account model. The choice is per plan, not per seller — fiatPaymentProvider is set on each plan at creation time, so a single seller can run some plans on Stripe and others on Braintree.

​

Prerequisites

Before connecting Braintree to Nevermined, you need:

​

Connecting Your Braintree Account

Connection happens once per organization, from its Organization page (you must be an Admin of the organization):

​

What gets stored

After connecting, Nevermined holds three pieces of information about your account: Raw card data, customer details, and transaction PII never leave Braintree — Nevermined only stores the routing handles.

​

Disconnecting

Click Disconnect Braintree on the Organization page to end the connection. Nevermined revokes the access token it held and clears all four fields above (access token, refresh token, merchant ID, and the per-currency map). Existing delegations against your account stop being chargeable on the next request. Disconnecting does not remove Nevermined from your Braintree account. Braintree’s API can revoke an access token but not your authorization of the app, so Nevermined stays listed under OAuth → Connected Apps in your Braintree Control Panel. Reconnecting may reuse that authorization, so it may skip the consent screen. To remove Nevermined entirely, click Revoke Access next to it in the Control Panel. If Braintree does not confirm the token revoke, the Organization page warns you, and the API’s DELETE /api/v1/fiat/braintree/disconnect response reports accessTokenRevocation: "failed". Nevermined still discards the connection.

​

Per-Currency Merchant Accounts

Braintree binds each merchant account to a single currency. To price a plan in EUR you need an EUR merchant account on your gateway; pricing the same plan in USD additionally needs a USD merchant account. This is a Braintree-side requirement, not a Nevermined one. Adding a merchant account to your gateway is a self-service action in the Braintree dashboard for sandbox accounts; production accounts may require Braintree to complete underwriting first. After adding a new currency in Braintree:

1. Disconnect Nevermined’s Braintree connection.
2. Reconnect — re-authorization usually completes in two clicks, because Braintree may skip the consent screen for an app you have already authorized.
3. The newly available currency badge appears on the Organization page.

There is no manual “Refresh” button. Currency changes on your side are rare enough that the disconnect+reconnect path is the simplest way to re-trigger discovery.

​

Plan Creation: Currency Guard

When you create a plan with fiatPaymentProvider: 'braintree', Nevermined checks the plan’s currency against the merchant accounts discovered at connection time:

• Currency available → plan creation succeeds. Buyers can purchase the plan and receive credits.
• Currency missing → plan creation is rejected with BCK.BRAINTREE.0008. Add the child merchant account in your Braintree dashboard, then disconnect and reconnect Nevermined before retrying.

The plan-creation form in the Nevermined App enforces this client-side too: when you select Braintree as the provider, the currency dropdown only shows the currencies your gateway supports, with a tooltip pointing you to the Organization page if none are available yet.

​

Settlement Model

Once a plan is live, Nevermined settles each fiat charge with a two-transaction split on the buyer’s vaulted card:

1. Platform fee is charged on Nevermined’s own Braintree gateway, against Nevermined’s per-currency platform merchant account.
2. Merchant share is charged on your OAuth-connected gateway, against your per-currency child merchant account that matches the plan’s currency.

If the merchant leg fails after the platform fee has been collected, Nevermined automatically voids the platform transaction so you never end up paying a fee for a charge the buyer didn’t complete. This split applies to both:

• One-time subscription checkouts through the Nevermined App’s Braintree Drop-in.
• Per-request x402 settlements for credit top-ups when a buyer’s balance is insufficient (see the x402 card-delegation spec for the protocol-level details).

For very small charges where the platform fee would round to zero or negative, Nevermined falls back to a single merchant transaction with no fee collected — preserving correctness over revenue.

​

Limitations

• Currencies: USD and EUR only. Reach out if you need additional currencies; we’ll add them when there’s a clear use case.
• Refresh tokens rotate: long-lived CI tokens against real Braintree accounts are not feasible. Test integrations should mock the gateway or use a developer’s interactive sandbox session.
• Re-discovery requires reconnect: changing your gateway’s set of merchant accounts requires disconnecting and reconnecting Nevermined. Currency changes on the seller side are rare enough that this is acceptable; let us know if it becomes a friction point.

​

Troubleshooting

​

Related Pages