Magento Payment Gateways — PayPal, Stripe, Braintree and Offline Methods

In this tutorial, you'll learn how to configure payment gateways in Magento, including PayPal, Braintree, Stripe, and offline payment methods, along with security considerations and troubleshooting.

What You'll Learn

• Configuring payment methods in the Magento admin panel
• Setting up PayPal Express Checkout with API credentials
• Integrating Braintree for credit cards, Apple Pay, and Google Pay
• Installing and configuring Stripe via third-party extension
• Using offline methods: check/money order, bank transfer, cash on delivery
• Restricting payment methods by customer group and website
• Payment gateway security, PCI DSS compliance, and tokenization
• Troubleshooting payment errors and reading payment logs

Why It Matters

Payment gateways are the most critical integration in any e-commerce store. A misconfigured payment method blocks revenue entirely. Security mistakes can lead to data breaches and PCI non-compliance. Understanding how each gateway works, how to test in sandbox mode, and how to troubleshoot errors is essential knowledge for any Magento developer or store administrator.

Real-World Use

A store expands from the US to Europe. US customers use credit cards via Braintree and PayPal. European customers need Klarna, Sofort, and bank transfers. By configuring multiple payment methods and restricting them by billing country, the store offers region-appropriate payment options without cluttering the checkout for customers who cannot use them.

Learning Path

flowchart LR
  A["Cart & Checkout"] --> B["Payment Gateways
← You are here"]:::current
  B --> C["Shipping"]
  C --> D["Tax Configuration"]
  D --> E["Orders & Invoices"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Payment Methods Configuration

All payment configuration is in Stores > Configuration > Sales > Payment Methods.

The configuration page lists every available payment method. Each method has its own section with enable/disable, API credentials, and behavior settings.

Common settings across methods:

• Enabled — Yes/No
• Title — Display name on checkout
• New Order Status — Status assigned after order placement (e.g., Pending, Processing)
• Payment from Applicable Countries — All Allowed or Specific Countries
• Payment from Specific Countries — Selected countries where the method is available
• Sort Order — Display order in the payment step
• Minimum/Maximum Order Total — Amount range where the method appears

PayPal

Magento has several PayPal integration options:

PayPal Express Checkout: The most common PayPal integration. Customers pay using their PayPal account without leaving the store.

Configuration steps:

1. Go to Stores > Configuration > Sales > Payment Methods > PayPal Express Checkout.
2. Configure API Authentication:
   • API Username (from PayPal business account)
   • API Password
   • API Signature
3. Set Sandbox Mode to Yes for testing.
4. Configure settings:
   • Enable In-Context Checkout (opens PayPal in a modal)
   • Enable PayPal Guest Checkout (lets customers pay with credit card via PayPal without a PayPal account)
   • Payment Action: Authorization (hold) or Sale (capture immediately)

The Express Checkout button appears:

• On the product page (Shortcut)
• In the mini cart
• On the shopping cart page
• In the checkout payment step

PayPal Standard: Redirects customers to PayPal for payment. When they return, Magento finalizes the order. Simpler to configure but less seamless than Express Checkout.

PayPal Payflow Pro: An on-site credit card processing solution. Customers enter card details on the checkout page (hosted by PayPal). This provides PCI compliance without redirecting.

Braintree

Braintree is now the default PayPal-powered payment gateway in Magento. It supports:

• Credit and debit cards (Visa, Mastercard, Amex, Discover)
• PayPal (via Braintree)
• Apple Pay
• Google Pay
• ACH (US bank transfers)
• Venmo
• 3D Secure authentication

Configuration in Stores > Configuration > Sales > Payment Methods > Braintree:

1. Enter the Merchant ID, Public Key, and Private Key from your Braintree account.
2. Configure environment: Sandbox for testing, Production for live.
3. Enable payment options (credit cards, PayPal, Apple Pay, Google Pay).
4. Configure 3D Secure verification:
   • Required Amount: Orders above this threshold require 3D Secure
   • Verify with 3D Secure: Always or on specific conditions

Braintree handles PCI compliance through tokenization. Card details are tokenized by Braintree's JavaScript SDK, and Magento never stores raw card numbers.

Stripe

Stripe is not included in Magento Core. You need a third-party extension from the Magento Marketplace or a custom integration.

Popular Stripe extensions include:

• Stripe Payments (official Stripe partner)
• Magento 2 Stripe by CRUD
• Stripe Integration by Meetanshi

Configuration via extension:

1. Install the extension via Composer.
2. Enter Stripe API keys (Publishable Key and Secret Key) from the Stripe Dashboard.
3. Configure webhook URL in Stripe to receive payment events.
4. Enable payment methods: cards, Apple Pay, Google Pay, Klarna, etc.
5. Set 3D Secure requirement.

Stripe extensions typically support:

• Stored cards (save card for future purchases)
• 3D Secure 2 authentication
• Refunds from the Magento admin
• Subscription billing

Offline Payment Methods

Offline methods do not Process payments in real time. The order is created, and payment is collected separately.

Check/Money Order:

• Customer sends a physical check or money order.
• Configuration: Payable To (name), Send Check To (address).
• Order is created as "Pending" until the check arrives and is manually confirmed.

Bank Transfer:

• Customer transfers funds to your bank account.
• Configuration: Bank account name, account number, routing number, SWIFT/BIC, bank name.
• Instructions appear on the checkout confirmation page and in the order email.

Cash on Delivery:

• Customer pays in cash when the order is delivered.
• Configuration: Additional fee per order, title, instructions.
• Supported regions must be configured.

Purchase Order:

• B2B customers provide a PO number.
• Configuration: Company name field requirement, PO number field.
• Perfect for wholesale and corporate accounts.

Zero Subtotal Checkout:

• Used for free products or subscriptions where no payment is needed.
• Configuration: Title, new order status.
• Available only when the order total is $0.00.

Payment Gateway Configuration Per Website

In multi-store setups, you can configure different payment methods per website.

Go to Stores > Configuration. In the top-left corner, select the website scope. Each website can have its own payment method configuration.

This is useful when:

• Website A (US) offers Braintree and PayPal
• Website B (Germany) offers PayPal, Klarna, and bank transfer
• Website C (Wholesale) offers only Purchase Order and bank transfer

Payment Method Availability Per Customer Group

Restrict payment methods to specific customer groups:

1. Open the payment method configuration.
2. Find "Payment from Applicable Countries" or similar section.
3. Some extensions provide a "Customer Groups" setting.
4. Select specific groups allowed to use the method.

For example, the Purchase Order method should only appear for Wholesale and Corporate customer groups, not for Retail customers.

Payment Gateway Security

PCI DSS compliance is mandatory when accepting credit card payments:

• Tokenization — Use a gateway that tokenizes card data (Braintree, Stripe). Magento never stores the raw card number.
• SSL — The checkout page must use HTTPS with a valid SSL certificate.
• SAQ — Depending on your integration, you may need to complete a Self-Assessment Questionnaire (SAQ).
• 3D Secure — Adds an authentication step that reduces fraud liability.
• CVC verification — Always require the card security code.
• AVS — Address Verification System checks billing address against card issuer.

Never store raw credit card numbers in Magento's database. Always use a payment gateway that handles PCI compliance.

Troubleshooting Payment Issues

When payment fails, check these locations:

Payment logs:

var/log/payment.log
var/log/system.log
var/log/exception.log

Enable debug mode for the payment method to see detailed API communication:

Stores > Configuration > Sales > Payment Methods > [Method] > Debug: Yes

Common payment failures:

• Invalid API credentials — Double-check the API keys, especially after switching from sandbox to production.
• Webhook not configured — For Stripe, missing webhook means orders stay in "Pending" forever.
• Country restriction — The card's issuing country is not in the allowed list.
• AVS mismatch — Billing address does not match what the card issuer has on file.
• Fraud detection — The gateway flagged the Transaction as potentially fraudulent.

Common Mistakes

1. Using sandbox credentials in production. This is the most common mistake. Sandbox credentials work for testing but real charges fail. Always switch to production API keys and disable sandbox mode before going live.

2. Not configuring Webhooks for Stripe. Without webhooks, asynchronous payment events (success, failure, refund) are not communicated to Magento. Orders remain in "Pending" status indefinitely.

3. Enabling too many payment methods. Every extra payment method adds visual clutter and decision fatigue. Offer 2-3 methods that cover 95% of customers. More is not better.

4. Forgetting PCI compliance. Collecting credit card information on your server without proper PCI compliance is illegal and dangerous. Always use a gateway that handles tokenization (Braintree, Stripe, PayPal Payflow Pro).

5. Not testing in sandbox. Configuring a payment method without testing in sandbox mode leads to production failures. Always create test orders with test credit card numbers before going live.

Practice Questions

1. What is the difference between PayPal Express Checkout and PayPal Standard? Answer: PayPal Express Checkout keeps customers on the store site with an in-context modal and supports guest checkout with credit cards. PayPal Standard redirects customers to PayPal's website for payment and returns them to the store afterward. Express Checkout provides a better user experience.

2. How does Braintree handle PCI compliance? Answer: Braintree uses tokenization. The Braintree JavaScript SDK collects card details and exchanges them for a payment method nonce (token). This nonce is sent to Magento, which passes it to Braintree for processing. Magento never stores or transmits raw card numbers, keeping the store out of PCI scope.

3. What are offline payment methods and when should you use them? Answer: Offline methods (Check/Money Order, Bank Transfer, Cash on Delivery, Purchase Order) collect payment outside the real-time payment flow. They should be used for B2B transactions (Purchase Orders), customers without cards (Bank Transfer), or regions where cash is preferred (COD).

4. Challenge: Compare three payment gateway configurations for an international store selling to US, UK, and EU customers. For each region, recommend the optimal payment methods considering local preferences, fees, and regulatory requirements. Include Braintree, PayPal, Stripe, and at least one local payment method per region. Create a configuration table showing the enabled methods per website, customer group restrictions, and minimum/maximum order amounts.

FAQ

Mini Project

Your task: Configure and test a complete payment suite for a multi-region store.

1. Set up a Braintree sandbox account (braintreesandbox.com).
2. Configure Braintree in your Magento store with sandbox credentials.
3. Enable credit cards, PayPal, and Apple Pay.
4. Create a test order with Braintree test card: 4111 1111 1111 1111.
5. Configure Check/Money Order for backup.
6. Enable Bank Transfer with your test bank details.
7. Configure Cash on Delivery with a $5 fee.
8. Restrict Purchase Order to Wholesale customer group only.
9. Create test orders with each payment method.
10. Verify that orders appear correctly in Sales > Orders with the correct payment method and status.
11. Test a refund via Braintree from the Magento admin.

This exercise gives you hands-on experience with every payment method type.

What's Next

Now that you understand payment gateways, learn about shipping configuration:

Continue to Lesson 11: Shipping — Shipping methods, carriers, and zones.

Related lessons:

• Cart and Checkout — How payment interacts with checkout
• Tax Configuration — Tax calculation on shipping
• Orders, Invoices and Shipments — Creating shipments after payment