# Payment Integration

Generating invoices is one half of the billing cycle. Collecting payment against them is the other. Without automation, every invoice means chasing a payment manually, reconciling when it lands, and following up when it doesn't - work that scales linearly with customer count and is exactly the wrong kind of work for a growing business to be doing.

Revenium integrates with Stripe for automated card-on-file payments. Once configured, invoices generated by Revenium are charged automatically to the customer's stored payment method, with payment status flowing back into Revenium so the Invoices view always reflects what has actually been paid. There's no reconciliation between two systems because there's only one system.

This page walks through setting up the integration and explains how payment configuration flows through to products and subscriptions.

### <i class="fa-cc-stripe">:cc-stripe:</i> Stripe Is the Supported Provider

Payment Gateways in Revenium support Stripe as the payment provider. If you're already using Stripe for payment collection elsewhere, this integration slots in against the same account - no separate merchant setup, no duplicate card-on-file storage. If you're not using Stripe yet, you'll need to create a Stripe account before configuring the integration; the keys you need come from your Stripe dashboard.

### <i class="fa-credit-card">:credit-card:</i> Setting Up the Payment Gateway

Head to **Configuration > Billing** and open the **Payment Gateways** tab. The list is empty until you add one; click the **+** button to create a new payment gateway configuration.

The Add Payment Gateway form needs:

* **Name** (required) - an internal label for this configuration. Shows up in the Configuration Name column once saved, and in the Payment Options dropdown on products. Something descriptive like "Stripe - Production" or "Stripe - EU Entity" works well, especially if you might end up with multiple Stripe accounts for different business units or regions.
* **Payment Provider** (required) - Stripe is the only option in the dropdown.
* **Tax Behavior** (required) - how tax is handled on invoices charged through this gateway:
  * **None** - no tax is applied. Use this if you're not using Stripe Tax.
  * **Inclusive** - the invoice total already includes tax; tax amount is calculated backwards from the total.
  * **Exclusive** - tax is added on top of the invoice total at charge time.
* **Secret Api Key** (required) - from your Stripe dashboard. This is the sensitive key; Revenium uses it server-side to create charges.
* **Api Publishable Key** (required) - also from the Stripe API keys page. Used for any client-side checkout flows.

Once saved, the gateway appears in the Payment Gateway list with Provider, Configuration Name, and Owner columns. Your own name appears as Owner - useful in teams where multiple people configure payment setups and you need to know who to ask about a particular configuration.

### <i class="fa-tags">:tags:</i> Connecting the Gateway to a Product

Configuring the gateway doesn't by itself activate automated payments - it makes the option available. To actually charge customers automatically, the product they're subscribed to needs to be pointed at it.

On each product that should use automated card payments, set the **Payment Options** field (in the product's invoicing configuration) to **Stripe-Enabled Payments**, and select the gateway you just created. From that point on, invoices generated against subscriptions on this product are charged automatically against the customer's saved card.

This is a per-product choice rather than an account-wide switch. That matters because it means you can have some products on automated Stripe charging, others on invoice-only billing (where Revenium generates the invoice and you collect payment yourself), and others on external payment updates (where your own accounting system tells Revenium when invoices are paid). Different customers on different products can be billed in different ways without separate infrastructure.

### <i class="fa-play">:play:</i> What Happens After Setup

Once Stripe is configured and products are pointed at it, the lifecycle runs itself:

* At the end of each invoicing period, Revenium generates an invoice against the customer's subscription
* The invoice is automatically charged to the customer's saved Stripe payment method
* Stripe attempts the charge, with automatic retries for common failures handled according to your Stripe configuration
* Payment status flows back into Revenium and surfaces in the **Billing > Invoices** view
* On failure, the **Payment Failed** notification template triggers an email to the customer
* On success, the **Successful Payment** template fires if enabled

The **Show Failed Payments Only** toggle on the Invoices tab becomes the most useful view to monitor once this is running - it filters out the noise of successfully paid invoices and shows only the ones that need attention.

### <i class="fa-record-vinyl">:record-vinyl:</i> Recording Payments Collected Outside Revenium

Not every customer is on automated Stripe billing. Enterprise contracts are often paid by wire transfer, bank ACH, or procurement systems outside Stripe's world. For these, the **Invoices with External Payment Updates** payment option on a product tells Revenium to generate the invoice but wait for external confirmation that it's been paid. When the payment lands in your system, you mark it as received in Revenium - either manually through the UI or programmatically via the API (see below).

This mixed-mode approach - automated Stripe for SMB customers, externally-tracked payments for enterprise - is common in practice and is what the three Payment Options on products are designed to support.

### <i class="fa-code">:code:</i> Via API

Stripe gateway configuration is a one-time UI operation and doesn't have a dedicated API - the Stripe credentials are sensitive enough that pushing them through an automated flow isn't the usual pattern. Everything downstream of that setup, however, is available programmatically.

**Attaching a payment gateway to a product.** When you create or update a product via the [Products API](https://revenium.readme.io/reference/get_product), the payload includes a `paymentConfigurationId` field. Set this to the ID of the Payment Gateway you configured in the UI, and any subscription created against that product will automatically bill through the connected Stripe account. This is how teams managing many products programmatically wire them all to the same (or different) payment configurations without repeating UI setup for each one.

**Subscriptions inherit their payment configuration from their product.** The [Subscriptions API](https://revenium.readme.io/reference/get_subscription) doesn't take a payment configuration at subscription-create time because it doesn't need to - the subscription uses whatever configuration is attached to the product it references. When you migrate a customer to a different product with a different payment configuration, payment routing changes automatically as part of that migration.

**Recording externally-collected payments.** For products on the invoice-only or external-payment-update flow, the [Payment Received](https://revenium.readme.io/reference/get_payment_received) endpoints let you record when a payment arrives, link it to a specific invoice, and keep Revenium's record of outstanding balances accurate. This is the right endpoint to call from your accounting or treasury system when a bank transfer clears.

**Setting a default payment method at the tenant level.** The [tenant default payment method](https://revenium.readme.io/reference/setdefaultpaymentmethod) endpoint sets which payment method is used as the fallback when a product or subscription doesn't specify one directly. Useful for setting a house default across multiple products without updating each one individually.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.revenium.io/monetize-your-ai/payment-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.