Payment Providers in Odoo 19:
Stripe, PayPal & Custom Gateway Integration

Every Abandoned Cart Is a Payment Friction Problem

According to Baymard Institute, 22% of online shoppers abandon their cart because the checkout process is too complicated. Another 9% leave because there aren't enough payment methods. That means nearly one-third of your potential revenue evaporates at the moment the customer is ready to pay.

Odoo 19 ships with built-in support for Stripe, PayPal, Authorize.net, Adyen, Mollie, Razorpay, and several regional providers. But installing the module is the easy part. The hard part is configuring tokenization so returning customers pay in one click, handling webhooks so payment confirmations don't silently fail, supporting multi-currency checkout without rounding errors, and processing refunds that actually reconcile in your accounting.

This guide covers the complete payment provider setup for Odoo 19 -- from Stripe and PayPal configuration through tokenization, webhook handling, multi-currency payments, refunds, and building a custom gateway integration from scratch.

Configuring Stripe in Odoo 19: API Keys, Payment Intents, and Checkout Flow

Stripe is the most popular payment provider for Odoo e-commerce. Odoo 19 uses the Payment Intents API (not the legacy Charges API), which supports SCA (Strong Customer Authentication) required by PSD2 in Europe.

Step 1: Install the Stripe Module

Navigate to Apps, search for "Stripe", and install payment_stripe. This also installs the base payment module if not already present.

Step 2: Create a Stripe Account and Retrieve API Keys

From your Stripe Dashboard, navigate to Developers → API Keys. You need two keys:

Step 3: Configure the Provider in Odoo

# Payment Provider Configuration for Stripe
# ─────────────────────────────────────────
# Provider:          Stripe
# State:             Test Mode  (switch to "Enabled" for production)
# Company:           Your Company

# Credentials Tab:
# ─────────────────
# Secret Key:        sk_test_4eC39HqLyjWDarjtT1zdp7dc
# Publishable Key:   pk_test_TYooMQauvdEDq54NiTphI7jx
# Webhook Secret:    whsec_...  (generated in Step 4)

# Configuration Tab:
# ──────────────────
# Payment Journal:   Bank (or a dedicated "Online Payments" journal)
# Allow Tokenization: Yes  (save cards for returning customers)
# Capture Manually:   No   (auto-capture on confirmation)
# Payment Icons:      Visa, Mastercard, Amex  (shown at checkout)

Step 4: Set Up the Stripe Webhook Endpoint

This is the step most implementations skip -- and the one that causes the most production issues. Without webhooks, Odoo relies solely on the redirect callback after checkout. If the customer closes the browser before the redirect, the payment succeeds on Stripe but Odoo never knows about it.

# Endpoint URL:  https://your-odoo-domain.com/payment/stripe/webhook
# Events: checkout.session.completed, payment_intent.succeeded,
#          payment_intent.payment_failed, payment_intent.canceled,
#          charge.refunded, charge.refund.updated
# Copy the Signing Secret (whsec_...) into Odoo provider config.

Setting Up PayPal in Odoo 19: REST API, Smart Buttons, and IPN

Odoo 19 uses the PayPal REST API v2 (Orders API), replacing the legacy NVP/SOAP integration from older Odoo versions. This means you need a PayPal Business account with REST API credentials, not the old "Classic API" username/password/signature.

Step 1: Create REST API Credentials

Go to developer.paypal.com → Apps & Credentials. Create a new app (or use the default sandbox app for testing). Copy the Client ID and Secret.

Step 2: Configure PayPal in Odoo

# Payment Provider Configuration for PayPal
# ───────────────────────────────────────────
# Provider:          PayPal
# State:             Test Mode

# Credentials Tab:
# ─────────────────
# Email Address:     your-business@company.com  (PayPal Business account)
# Client ID:         AaBbCcDd...  (from REST API app)
# Client Secret:     EeFfGgHh...  (from REST API app)

# Configuration Tab:
# ──────────────────
# Payment Journal:   Bank
# Allow Tokenization: No  (PayPal tokenization requires vault approval)
# Fees:
#   Extra Fees:      Domestically: 0%, Internationally: 0%
#   (Or pass provider fees to customer -- check local regulations)

Step 3: Enable IPN (Instant Payment Notification)

PayPal's IPN serves as a fallback for edge cases (network timeouts, browser closures). Set the Notification URL to https://your-odoo-domain.com/payment/paypal/ipn under Account Settings → Notifications → IPN. Odoo verifies each IPN message by sending it back to PayPal for validation, preventing spoofed notifications.

Multi-Currency Payments in Odoo 19: Exchange Rates, Rounding, and Settlement

When a customer pays in EUR but your company books in USD, three exchange rates are in play: Odoo's rate (from the ECB feed or manual entry), the payment provider's rate (Stripe/PayPal conversion), and the bank's settlement rate. Mismatches between these rates create journal entry imbalances that block period closing.

Configuration: Let the Provider Handle Conversion

Recommended approach: Charge in the customer's currency. Stripe/PayPal charges in EUR, settles to your USD account at their exchange rate. Odoo records the invoice and payment in EUR (matched exactly), the bank statement shows the converted USD amount, and the exchange difference is auto-posted to the gain/loss account. Verify supported currencies with provider._get_supported_currencies().

Not recommended: Converting before charging (Odoo converts EUR to USD using its rate, then charges USD). The customer sees a different amount than the product price, creating confusion and potential chargebacks.

Building a Custom Payment Gateway Integration for Odoo 19

When your payment provider isn't supported out of the box (regional banks, crypto gateways, BNPL services), you need a custom integration. Odoo 19 provides a clean extension pattern: inherit payment.provider and payment.transaction, override the key methods, and register your provider code.

Module Structure and Provider Model

# Module structure:
# payment_custom_gateway/
#   __manifest__.py
#   models/payment_provider.py, payment_transaction.py
#   controllers/main.py
#   views/payment_provider_views.xml
#   data/payment_provider_data.xml

from odoo import fields, models

class PaymentProvider(models.Model):
    _inherit = 'payment.provider'

    code = fields.Selection(
        selection_add=[('custom_gw', "Custom Gateway")],
        ondelete={'custom_gw': 'set default'},
    )
    custom_gw_api_key = fields.Char(
        string="API Key",
        required_if_provider='custom_gw',
        groups='base.group_system',
    )
    custom_gw_merchant_id = fields.Char(
        string="Merchant ID",
        required_if_provider='custom_gw',
    )
    custom_gw_webhook_secret = fields.Char(
        string="Webhook Secret",
        groups='base.group_system',
    )

    def _get_supported_currencies(self):
        supported = super()._get_supported_currencies()
        if self.code != 'custom_gw':
            return supported
        return supported.filtered(
            lambda c: c.name in ('USD', 'EUR', 'GBP', 'CAD')
        )

The Transaction Model

import requests
from odoo import models, _
from odoo.exceptions import ValidationError
from odoo.addons.payment import utils as payment_utils

CUSTOM_GW_API_URL = 'https://api.customgateway.com/v1'

class PaymentTransaction(models.Model):
    _inherit = 'payment.transaction'

    def _get_specific_rendering_values(self, processing_values):
        res = super()._get_specific_rendering_values(processing_values)
        if self.provider_code != 'custom_gw':
            return res
        amount = payment_utils.to_minor_currency_units(
            self.amount, self.currency_id
        )
        provider = self.provider_id
        response = requests.post(
            f'{CUSTOM_GW_API_URL}/sessions',
            json={
                'merchant_id': provider.custom_gw_merchant_id,
                'amount': amount,
                'currency': self.currency_id.name,
                'reference': self.reference,
                'return_url': self._get_return_url(),
                'webhook_url': self._get_webhook_url(),
            },
            headers={
                'Authorization': f'Bearer {{provider.custom_gw_api_key}}',
            },
            timeout=30,
        )
        response.raise_for_status()
        session = response.json()
        return {**res, 'checkout_url': session['checkout_url']}

    def _get_tx_from_notification_data(self, provider_code, data):
        if provider_code != 'custom_gw':
            return super()._get_tx_from_notification_data(
                provider_code, data
            )
        tx = self.search([
            ('reference', '=', data.get('reference')),
            ('provider_code', '=', 'custom_gw'),
        ])
        if not tx:
            raise ValidationError(
                _("No transaction for ref: %s", data.get('reference'))
            )
        return tx

    def _process_notification_data(self, data):
        super()._process_notification_data(data)
        if self.provider_code != 'custom_gw':
            return
        self.provider_reference = data.get('gateway_transaction_id')
        status = data.get('status')
        if status == 'completed':
            self._set_done()
        elif status == 'pending':
            self._set_pending()
        elif status in ('failed', 'declined'):
            self._set_error(_(
                "Payment failed: %s", data.get('error_message', '')
            ))
        elif status == 'canceled':
            self._set_canceled()

The Webhook Controller

import hmac, hashlib, json
from odoo import http
from odoo.http import request
from werkzeug.exceptions import Forbidden

class CustomGatewayController(http.Controller):

    @http.route('/payment/custom_gw/webhook', type='json',
                auth='public', csrf=False)
    def webhook(self):
        data = request.get_json_data()
        sig = request.httprequest.headers.get('X-Signature')
        provider = request.env['payment.provider'].sudo().search(
            [('code', '=', 'custom_gw')], limit=1
        )
        expected = hmac.new(
            provider.custom_gw_webhook_secret.encode(),
            json.dumps(data, sort_keys=True).encode(),
            hashlib.sha256,
        ).hexdigest()
        if not hmac.compare_digest(sig or '', expected):
            raise Forbidden()
        request.env['payment.transaction'].sudo()\
            ._handle_notification_data('custom_gw', data)
        return {'status': 'ok'}

Processing Refunds in Odoo 19: Full, Partial, and Automated Reconciliation

Odoo 19 supports full and partial refunds directly from the payment transaction or credit note. The refund is sent to the payment provider via API, and when the provider confirms (via webhook), Odoo creates a reversed journal entry that reconciles with the original payment.

Triggering a Refund from Code

# Full refund
transaction = self.env['payment.transaction'].browse(tx_id)
transaction._send_refund_request()

# Partial refund (refund 25.00 of a 100.00 payment)
transaction._send_refund_request(amount_to_refund=25.00)

# Behind the scenes: Odoo calls the provider refund API,
# the webhook fires (charge.refunded), Odoo creates a new
# payment.transaction with operation='refund', posts a reversed
# journal entry, and links it via source_transaction_id.

5 Payment Integration Gotchas That Cost Real Money

Optimization Metadata