Drupal Commerce with Authorize.Net or Braintree

How Drupal Commerce takes card payments through Authorize.Net or Braintree

A store team that needs card checkout and repeat orders on a self-hosted Drupal site will run that card flow through a contributed Drupal Commerce payment gateway module for the chosen provider. The module sends payment requests to Authorize.Net or Braintree, handles the provider's responses, and records payment and refund records on the order. Which contributed module fits, how the provider captures the card, and whether cards are kept in the gateway vault together decide how much of your environment falls under PCI DSS scope, so those three choices belong in the design review before any code is written.

The module choice comes first. Confirm the exact contributed module for your provider on Drupal.org, and check which Drupal and Drupal Commerce versions it supports today, since this section does not assume a module name or version. Next, confirm with the provider which card capture method its current API requires. A hosted capture page keeps card data off your servers, while a direct API integration usually means your web application handles more card data and sits closer to PCI DSS requirements. Ask the provider to confirm its current API requirements in writing, because they change over time and the module must follow them.

Vault settings are the last decision. Storing cards in the gateway vault and referencing them for repeat orders keeps raw card numbers out of your database, but the stored payment method still needs to be linked to the customer and order correctly, and refunds and failed renewals must be tested against the vault. Plan a test run with the provider's sandbox for each path (first purchase, saved card reuse, refund, declined card) and record which PCI DSS requirements your scope statement covers. Your qualified security assessor or compliance lead should review that scope before launch.

What you need in place before the gateway integration starts

Most delays in a card integration come from prerequisites that were never confirmed, not from the gateway code itself. The items below split into two sides: the Drupal platform the store runs on, and the provider account that issues the credentials and endpoints the module needs.

Drupal core and PHP version

Drupal 11 requires PHP 8.3 or later and Drupal 10 requires PHP 8.1 or later. Drupal 10 reaches end of life on December 9, 2026, so a new commerce build should confirm the core version it targets before choosing a payment module. Check that the Commerce release you plan to use declares support for that core version, and record the PHP version your hosting platform will actually run.

Web server and database stack

Supported Drupal versions run on Apache or Nginx with MariaDB, MySQL, PostgreSQL or SQLite. For a store that stores payment references and order data, confirm the production database engine and its backup approach before the build starts, and keep the same stack in staging so that gateway callbacks are tested against the real configuration.

HTTPS on the storefront

Card forms, return URLs and webhook callbacks all depend on a valid TLS certificate on the storefront and checkout domains. Confirm that the certificate chain, redirects and any reverse proxy or CDN settings preserve the original host and protocol, because a mismatch often breaks off-site payment redirects and hosted fields in ways that only appear after go-live.

Merchant account and sandbox credentials

Ask the provider for a live merchant account and a separate sandbox account with its own API keys or tokens. Keep sandbox and live credentials in different secret stores, and confirm who holds administrative access to the provider dashboard. Authorize.Net and Braintree issue different credential types, so the module you choose determines which values you need.

Webhook endpoint and notifications

Decide which public URL the provider will call for asynchronous events such as settlements, refunds and declines, and confirm that it is reachable from the provider's network without a login. Agree who owns the signing secret or verification key, and test that duplicate or delayed notifications do not create duplicate orders or payments in Drupal Commerce.

Stored payment profile and vault settings

Repeat orders with saved cards require the merchant account to be enabled for stored payment profiles or vault tokens. Ask the provider to confirm this in writing for the live account, since sandbox behavior can differ. Also confirm whether the account accepts tokenized card data from the Drupal site and under what card data handling model, because that answer determines the PCI DSS scope discussed later on this page.

How to configure the gateway in the order that avoids rework

This sequence moves a Drupal Commerce card gateway from a sandbox install to verified test transactions, so each setting is confirmed before live credentials, real cards or customer data are involved.

Confirm the provider and contributed module
Before any install, the team confirms which provider (Authorize.Net or Braintree) and which Drupal Commerce payment module it will use, checking that the module has a stable release compatible with the Drupal core version in use. Your developer checks the module's project page on Drupal.org and records the version in the project plan. Done when the team has a written decision naming the provider, the module and its version, and the sandbox account owner.
Install and enable the payment module
A developer adds the module through Composer in a non-production copy of the site, enables it along with the Drupal Commerce payment dependencies, and clears caches. The change is committed to version control so the same module set reaches every environment. Done when the module appears as enabled on the extend page, the site loads without errors, and the Composer lock file shows the pinned version.
Create the sandbox gateway configuration
An administrator creates a payment gateway entity in Drupal Commerce and selects the sandbox or test mode, using only sandbox API credentials from the provider. Live credentials stay out of this environment entirely and are stored in your secrets mechanism rather than in configuration exported to the repository. Done when the gateway saves with a sandbox mode indicator and a test checkout can reach the provider's sandbox endpoint.
Set capture mode and the vault option
The team chooses between authorize only and authorize and capture, and decides whether card details are stored in the provider's vault for repeat orders. The choice affects when money moves, how fulfillment is triggered and what a later refund looks like, so it is agreed with finance and operations first. Done when the saved configuration matches the written decision and a test order shows the expected transaction state in the payment record.
Configure currency and accepted card types
An administrator confirms the store currency matches the currency the provider account is enabled to settle, then lists only the card brands the merchant account accepts. Mismatches here typically surface as declines at checkout, so the team checks them against the provider's dashboard rather than guessing. Done when a test order in the store currency is accepted and an unsupported card type is rejected with a clear message.
Add the notification endpoint
A developer registers the site's webhook or notification URL in the provider's sandbox dashboard, using a route that is protected by signature verification as the module documents. Events such as settlements or refunds that happen outside checkout then update the order record. Done when a test event sent from the provider reaches the site and appears in the logs as received and verified, and an invalid signature is refused.
Run the test transaction matrix
The QA lead runs a scripted set of sandbox transactions: an approved payment, a declined card, a partial refund and a full void. Each result is compared with the provider dashboard. An approved payment should produce a payment record matching the provider transaction ID, a partial refund should reference the original transaction and leave the balance correct, and a void should cancel an uncaptured authorization without a refund record. If a saved card is used for a repeat order, the stored token should appear on the customer's payment method list while the database holds no raw card number. Done when every case matches the expected record and the results are signed off.

How stored cards in the gateway vault support repeat orders

A gateway vault lets the site keep a reusable reference to a card instead of the card number itself. With Authorize.Net, the stored reference is a customer profile and payment profile held by the gateway. With Braintree, it is a customer record and payment method token in the Braintree vault. In Drupal Commerce, the payment gateway plugin for the chosen provider saves that identifier on the payment method entity linked to the customer's account, so a later order can be charged without the shopper re-entering card details. The card number should never be written to the Drupal database. Your team should confirm with the provider which fields the module stores, where they live in the database, and that no full card data passes through your servers at any step. Consent and display rules belong in the checkout design, not in the gateway settings. Store the card only after the shopper has ticked an explicit save-card option that states what is kept and for what purpose. Show saved cards only to the account that owns them, and show only the brand and last four digits. Decide how the site handles a guest checkout that asks to save a card, and whether that option is offered at all. Deleting a card in the customer account should delete or deactivate the local payment method and call the provider to remove the token. Expired cards need a defined path: the site should flag them, and the shopper should be asked to add a new card rather than having the old token charged. Each stored token must map to one customer account, and each order that uses it should record which payment method and gateway transaction it used. Check these links with test orders before launch, including refunds and voids, because a broken mapping shows up later as a charge against the wrong account. Then confirm two points with the provider in writing: whether the stored token can be charged off session (when the shopper is not present, for example on a reorder placed later), and which authentication rules apply, including when the issuer may require a fresh verification step. Those answers determine whether reorders can complete without the shopper. Recurring billing and subscriptions are a separate sibling topic, so this section covers the card token only.

Which order, customer and payment records map to which provider objects

This table compares Drupal Commerce records on your site with the objects Authorize.Net or Braintree create for the same activity. Read each row as a question: what does the site need to answer locally, and what should stay with the gateway. The main takeaway is that the site should hold references and status, while card data and settlement detail remain at the provider.

Drupal Commerce record	Provider object to expect	What the site stores locally	What stays at the provider only
Order	Transaction or payment reference created per charge attempt	Order ID, totals, state and the reference returned by the gateway	Authorization detail and gateway-side order notes
Order payment	Transaction ID, authorization or capture result	Payment entity, amount, currency, state and remote ID	Full response payload and processor-level decline codes
Payment gateway configuration	Merchant account credentials and API or environment settings	Gateway plugin settings with secrets referenced, not copied in clear text	Merchant account setup, processor agreements and key issuance
Payment method	Vaulted payment method token or profile reference	Token reference, card brand, last four digits and expiry for display	Primary account number and card security data
Customer profile	Customer or vault profile identifier at the gateway	Mapping from the Drupal user or customer profile to the gateway profile ID	Stored card records and the cardholder data inside the vault
User account	No direct provider object; linked through the customer profile reference	Account, roles and the link to the gateway customer reference	Any card or bank data supplied during checkout
Refund	Refund or credit transaction referencing the original charge	Refund payment record, amount and the provider refund reference	Settlement batch detail and chargeback records
Status event	Webhook or notification of settlement, failure or dispute	Last processed event ID and resulting order or payment state	Full event history and dispute workflow
Settlement report	Batch or settlement file for reconciliation	Reconciliation totals and exception notes for finance	Batch-level processing and bank deposit records

How the choice of integration method changes PCI DSS scope

Each decision below determines how much of your Drupal Commerce estate touches cardholder data. Capture method, secret handling, administrator access, logging and patching all feed the same question: which systems store, process or transmit card data. A qualified assessor determines the PCI DSS scope for your environment, so use these cards to prepare the evidence and design choices that assessment will need.

Hosted or redirect capture versus on-site fields

With a hosted page or redirect, the customer enters card details on the gateway's domain, so card numbers do not pass through your Drupal servers. Card fields rendered on your own checkout page send the number through your web tier, which widens the systems in scope. Decide the capture method before the theme is built, because switching later means reworking checkout and retesting the flow. Confirm with the gateway which Commerce payment plugin variant and which integration mode you intend to use.

API keys and webhook secrets

Gateway API credentials and webhook signing secrets should live in a secrets store or environment injection, not in settings files committed to Git or in the Commerce payment gateway form stored in the database. Anyone who can read the database or exported configuration can otherwise reuse those credentials. Ask who can rotate them, how rotation is tested against live webhooks, and whether sandbox and production credentials are separated.

Administrator access to gateway settings

Limit who can change gateway configuration, refund transactions and view transaction reports, and separate those roles from content and site-building permissions. Review Drupal role assignments and the gateway's own user accounts on a schedule, and remove access when staff change roles. Log every change to payment settings so that a reviewer can tie a configuration change to a named person.

Card data in logs, messages and backups

Drupal writes to watchdog and external log sinks, and checkout errors often dump request payloads. Verify that payment exceptions, debug output and failed-order records do not capture card numbers, expiry dates or full gateway responses. Backups of the database and file system carry the same data, so check what the payment tables hold and who can restore them. Test log redaction with a deliberate failed payment before launch.

Patching core, Commerce and payment modules

Track security advisories from the Drupal Security Team for Drupal core, Drupal Commerce and the Authorize.Net or Braintree module, because a vulnerability in any of them can expose the checkout. Security releases follow a set Wednesday window, while bugfix releases come on the first Wednesday of each month. Agree who reviews advisories, who tests the update on staging, and how quickly a security release reaches production.

Authorize.Net or Braintree: how to choose between them for this store

Costs for card processing come from two places: the gateway account and the merchant account or acquiring bank that settles the funds. The gateway fee, the per-transaction charge, monthly account fees, chargeback handling and any minimum commitments are set in your provider agreement, and they change over time. Ask each provider for a written schedule that applies to your expected volume, card mix and countries of sale.

Gateway and processing fees: Confirm the per-transaction and percentage charges, and whether they differ for card-not-present orders, international cards or refunds.
Merchant account requirements: Confirm whether you need your own merchant account, which bank acquires for the provider, and who holds the settlement relationship.
Recurring charges: Ask about monthly platform fees, PCI-related fees, gateway minimums and charges for unused capacity.
Chargebacks and holds: Ask how disputes are reported, what fees apply and whether reserves can be required for new or high-risk merchants.
Term and exit: Check contract length, termination notice and how stored card data would be exported if you switch providers.

Ask for the full fee schedule in writing and have finance review it alongside the Drupal Commerce scope.

Failures that most often stop card payments or repeat orders

This table pairs each failure that typically stops card payments or creates duplicate orders with its likely cause and the configuration or test step that fixes it. Read it as a pre-launch checklist and as a triage guide once the store is live. Most of these problems trace back to environment mismatches, webhook delivery and handling of retried notifications, so verify those first.

Failure	Likely cause	Fix
Live store charges fail or test cards behave oddly	Sandbox API credentials or sandbox endpoints left in production, or live credentials pointed at a test environment	Keep environment and credentials in separate, named settings per store. Run a test order on each environment and confirm the gateway dashboard shows it under the expected mode before launch.
Declined orders in one currency or for one card brand	Currency or card type not enabled on the merchant account, or not added to the payment gateway configuration in Drupal Commerce	Compare the store's accepted currencies and card brands with the merchant account settings. Test each enabled brand with a gateway test card before go-live.
Payment succeeds at the gateway but the order never completes	Webhook or notification URL blocked by a firewall, web application firewall, proxy, or an invalid or expired HTTPS certificate	Confirm the notification endpoint is publicly reachable over HTTPS with a valid certificate chain. Send a test notification from the gateway dashboard and check the Drupal logs and gateway delivery history.
Repeat order for a stored card is declined or requires authentication	Stored token cannot be charged off session because the issuer or customer authentication rules changed, so the transaction needs the customer present	Confirm with the gateway how stored credentials and strong customer authentication are handled for your region and card mix. Design a fallback that emails the customer a payment link for re-authentication.
Duplicate orders or double charges after a gateway retry	Retried notifications processed without checking whether the transaction ID was already recorded against an order	Make notification handling idempotent by storing the gateway transaction ID and ignoring repeats. Replay the same notification twice in staging and confirm one order and one payment record.
Refund fails in the store or at the gateway	Original transaction already settled or voided, so it must be refunded or reversed through a different operation	Map each refund path to the transaction state at the gateway. Test a refund after capture, a void before settlement, and a partial refund in sandbox, and record which operation the store calls in each case.
Card numbers or sensitive data appear in logs, backups or exports	Verbose debug logging of request payloads, or database dumps captured while tokenization was incomplete	Confirm the store only handles gateway tokens and hosted fields. Search logs, database backups and exports for card-like strings during a test, and set retention and redaction rules before go-live.

Questions buyers ask before hiring help with this integration

What drives the cost of a Drupal Commerce Authorize.Net or Braintree integration?

The largest drivers are the number of payment methods, whether cards must be stored in the gateway vault for repeat orders, and how much testing and security review the project needs. Module setup and configuration are usually a single block of work, while provider account setup is often done by the client's finance or operations team with DeployOpen supplying the technical steps. Testing covers sandbox transactions, declines, refunds and failure paths, and a security review looks at how card data moves through the site. Ask for a written quote that lists each of these items separately, showing who performs it and whether it is one-time or recurring.

Can our internal team build this integration without outside help?

A team with Drupal Commerce experience, PHP skills and access to the gateway's sandbox can complete the core integration alone, provided someone owns the payment flow end to end. The harder skills are PCI DSS scoping, webhook and callback handling, reconciliation of gateway records with orders, and writing a test plan that covers failures. If those skills are thin internally, a partner usually covers the design, build and test scripts while your staff review and take over operation. Confirm your internal capacity before choosing either path.

How long does the gateway work take?

Duration depends mainly on how many payment methods are enabled, whether stored cards are in scope, how many order types need payment handling, and how thorough the test scope is. A single gateway with one-time card payments is far simpler than several gateways with vaulted cards for repeat orders and recurring billing. Provider account approval can run on its own schedule and may affect the start date. Ask the provider for its current onboarding timelines, then ask for a schedule in the written quote that shows which steps depend on them.

What do we need to provide before the work starts?

You will need an Authorize.Net or Braintree account with sandbox access, a named business owner who can approve the merchant setup, and a technical contact who can grant access to the Drupal environment. A compliance or security contact should review the PCI scope decisions, and finance should confirm settlement, refund and currency rules. A draft test plan listing the checkout paths, order types, currencies and failure cases helps keep testing focused. Your written scope should name who supplies each of these items and by when.

What needs ongoing attention after the site launches?

Several things recur. Contributed payment modules receive updates that may need testing before deployment, and gateways change their APIs and SDKs over time, which can affect card storage and webhook handling. Drupal core and PHP versions also move on a published schedule, so the payment path must be retested after each major upgrade. Security releases from the Drupal Security Team can require quick patching of the site. Plan a recurring test cycle and a clear owner for gateway notices, and ask whether support or upgrade retainers cover these tasks.

How does the stored card and PCI scope question affect the design?

Using the gateway's hosted fields or vault tokens keeps raw card numbers off your servers, which typically narrows the PCI DSS scope compared with handling card data directly. Storing cards for repeat orders still requires careful token handling, access control for customer records, and logging that never captures card data. Whether your site qualifies for a reduced questionnaire depends on your transaction volume and how the checkout is built, so confirm the assessment type with your acquirer or QSA. DeployOpen prepares the technical evidence, while independent assessors issue any attestation.

How is scope agreed before the work begins?

Most engagements are fixed-scope, so the payment methods, stored-card requirements, test scope, deliverables and timelines are agreed in writing before any build work starts. The written scope should name the gateway, the Drupal and Drupal Commerce versions in use, the checkout and order types covered, and the exclusions. Changes after signature are handled through a written change request that states the effect on cost and timing. Ask for the scope document to list acceptance tests, so both sides know when the integration is complete.

How DeployOpen works on this

DeployOpen plans, implements, customizes, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Drupal Commerce with Authorize.Net or Braintree, we start with a written scope that fixes the gateway, the checkout flows, the vault design and the PCI scope boundary before any build begins.

How we scope

The written scope names the gateway, the account type, the checkout flows and the currencies you accept.
It records which card data touches your Drupal servers and which stays with the gateway's hosted fields or vault.
Stored-card and repeat-order behavior is defined, including which contributed modules and versions will be used.

How we build

We configure the payment gateway plugin in Drupal Commerce and build any custom code needed for your order flows.
Test transactions cover authorization, capture, refund, void, declines and 3-D Secure challenges in the gateway sandbox.
Webhook or notification handling, logging and error paths are built and tested before any live credentials are used.

How we hand over

You receive configuration records, custom code in version control, and the test cases used for each payment path.
Runbooks cover credential rotation, refund procedures, failed-payment handling and how to read gateway reports.
A written record of the PCI scope decisions is handed over so your assessor and security team can review it.

How we support

Ongoing support, module upgrades and continuous testing are available as retainers after handover.
Upgrades to Drupal core, Drupal Commerce and gateway modules are tested in a staging copy before production.
Gateway API changes are reviewed as they are announced, and you confirm the current support terms with the gateway vendor.