Payments

Payment Capabilities

Recurso integrates with payment gateways to handle:

Subscription payments
One-time charges
Payment retries (dunning)
Refunds

Supported Gateways

Gateway	Regions	Currencies
Razorpay	India	INR
Stripe	Global	135+ currencies

Payment Flow

Recurso generates the invoice; the customer pays it on Recurso’s hosted checkout page at {your-recurso-origin}/checkout/{invoice_id}. The checkout initiates a gateway order, drives the right client flow (Stripe Payment Element or Razorpay Checkout.js), and settlement is always verified server-side — the checkout confirms the payment with the gateway and binds it to the invoice before anything is marked paid. Gateway webhooks remain the authoritative backstop.

Configuration

Configure gateways in your environment:

.env

# Razorpay (India)
RAZORPAY_KEY_ID=rzp_live_xxx
RAZORPAY_KEY_SECRET=xxx

# Stripe (Global)
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_PUBLISHABLE_KEY=pk_live_xxx   # required for hosted checkout & portal card update
STRIPE_WEBHOOK_SECRET=whsec_xxx

STRIPE_PUBLISHABLE_KEY (and RAZORPAY_KEY_ID for INR) are handed to the buyer’s browser by the hosted checkout. If the browser-side key is missing, checkout initiation fails loudly with a 503 instead of dead-ending the buyer.

See the Payment Gateways guide for detailed setup instructions.

Collect Payment

For Subscriptions

Creating a subscription generates its first invoice. Send the customer to the hosted checkout for that invoice — the gateway is chosen automatically by currency (INR → Razorpay, others → Stripe):

const subscription = await recurso.subscriptions.create({
  customer_id: 'cust_abc123',
  plan_id: 'plan_pro'
});

const [invoice] = await recurso.invoices.list({ subscription_id: subscription.id });

// Redirect the customer to the hosted checkout
window.location.href = `https://billing.yourdomain.com/checkout/${invoice.id}`;

The checkout page handles everything from there: card + local methods via the Stripe Payment Element (with real failure states — a declined payment shows “Payment not completed” with retry, never a false success), or the Razorpay modal for INR (UPI, cards, netbanking).

One-Time Charges

There’s no standalone invoice-create API — one-off charges attach to a subscription and bill on its next invoice, or land immediately via an advance invoice:

# Add a one-off charge (bills on the next recurring invoice)
curl -X POST https://api.recurso.dev/v1/subscriptions/{sub_id}/charges \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Onboarding fee", "amount": 999900, "currency": "INR" }'

# …or bill ahead of schedule right now
curl -X POST https://api.recurso.dev/v1/subscriptions/{sub_id}/advance \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "periods": 1 }'

See Advanced Billing for details.

Create Payment Order

The hosted checkout calls this for you; if you build a custom payment UI, create the gateway order directly. It is a public, rate-limited endpoint (no API key — it powers buyer-facing pages) that takes only the invoice id and picks the gateway by the invoice’s currency:

curl -X POST https://billing.example.com/payments/order \
  -H "Content-Type: application/json" \
  -d '{ "invoice_id": "9b2f6c1e-…" }'

For most integrations use the checkout wrapper instead — POST /checkout/{id}/pay returns everything the browser flow needs (gateway, Stripe client_secret + publishable_key, or razorpay_key_id). Settle only via the verify endpoints (success / razorpay/verify); never mark invoices paid from the client.

Payment Methods

The payment instrument lives at the gateway, attached during checkout (Stripe SetupIntent / Razorpay token or UPI mandate) or through the customer portal. Renewals then charge it automatically. On the Recurso side you can update the card-on-file display metadata shown in the dashboard and dunning emails:

curl -X PUT https://api.recurso.dev/v1/customers/{customer_id}/payment-method \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "card_brand": "visa", "card_last4": "4242",
        "card_exp_month": 12, "card_exp_year": 2028 }'

When a card expires, send the customer a magic link — the portal walks them through a fresh SetupIntent or mandate.

Record Offline Payment

Record payments received outside of Recurso — bank transfers, cash, cheques — optionally against an invoice, with TDS handled first-class:

curl -X POST https://api.recurso.dev/v1/payments/offline \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "…",
    "invoice_id": "…",
    "payment_type": "bank_transfer",
    "amount": 589882,
    "tds_amount": 58988,
    "currency": "INR",
    "reference_number": "NEFT-REF-123456",
    "notes": "NEFT from HDFC account"
  }'

string

required

bank_transfer, cash, or cheque.

integer

required

Cash actually received, in minor units.

integer

Tax deducted at source by the customer (Indian B2B). Posts to the TDS Receivable account — amount + tds_amount settles the invoice.

string

Bank/UTR/cheque reference for reconciliation.

List Offline Payments

Retrieve all offline payments recorded for an invoice or customer:

curl -G https://api.recurso.dev/v1/payments/offline \
  -H "Authorization: Bearer $API_KEY" \
  -d invoice_id=inv_001

from recurso.api.offline_payments import list_offline_payments

result = list_offline_payments.sync(client=client)
# The SDK has no server-side invoice filter — match client-side:
for_invoice = [p for p in result.data if p.invoice_id == invoice_id]

payments, _ := client.OfflinePayments.List(ctx)

// The SDK has no server-side invoice filter — match client-side:
for _, p := range payments {
  if p.InvoiceID != nil && *p.InvoiceID == invoiceID {
    // ...
  }
}

Virtual Accounts for Bank Transfers

For customers who prefer to pay via bank transfer, create a virtual account that auto-reconciles incoming payments:

// POST /v1/virtual-accounts { customer_id, invoice_id, amount }
const res = await fetch(`${BASE_URL}/v1/virtual-accounts`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ customer_id: 'cust_abc123', invoice_id: 'inv_001', amount: 589882 }),
});
const va = (await res.json()).data;
// Share these with the customer — incoming transfers auto-reconcile:
console.log(va.account_number, va.ifsc_code, va.bank_name, va.beneficiary_name);

When the customer transfers to this account, Recurso automatically matches the payment to the correct invoice. See the Virtual Accounts guide for setup.

Retrying Failed Payments

When payments fail, Recurso automatically:

Sends payment failure notification
Schedules retry based on dunning config
Escalates with reminder emails
Suspends subscription after max retries

// Configure dunning schedule
{
  retry_days: [1, 3, 7],     // Retry on day 1, 3, 7
  max_retries: 3,
  suspend_after_days: 14,
  cancel_after_days: 30
}

For intelligent retry timing based on payment success patterns, see the Smart Retry guide. For configuring email sequences during payment recovery, see the Dunning Campaigns guide.

Refunds

Refunds are issued as credit notes of type refund — this calls the real Stripe/Razorpay refund API and posts a Refunds-vs-Cash ledger reversal:

const refund = await recurso.creditNotes.create({
  type: 'refund',            // vs. 'adjustment' (account credit)
  customer_id: 'cust_abc123',
  invoice_id: 'inv_001',
  amount: 250000,            // minor units — partial refund
  currency: 'INR',
  reason: 'Customer requested',
});

The gateway refund settles asynchronously; the credit note tracks its refund_status (pending → processed, or failed / manual_required).

Webhooks

Event	Description
`payment.succeeded`	Payment completed
`payment.failed`	Payment attempt failed
`payment.refunded`	Refund issued
`payment.disputed`	Chargeback/dispute

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Payment Capabilities

Supported Gateways

Payment Flow

Configuration

Collect Payment

For Subscriptions

One-Time Charges

Create Payment Order

Payment Methods

Record Offline Payment

List Offline Payments

Virtual Accounts for Bank Transfers

Retrying Failed Payments

Refunds

Webhooks

Next steps

Dunning & recovery

The Ledger

​Payment Capabilities

​Supported Gateways

​Payment Flow

​Configuration

​Collect Payment

​For Subscriptions

​One-Time Charges

​Create Payment Order

​Payment Methods

​Record Offline Payment

​List Offline Payments

​Virtual Accounts for Bank Transfers

​Retrying Failed Payments

​Refunds

​Webhooks

​Next steps

Dunning & recovery

The Ledger

Payment Capabilities

Supported Gateways

Payment Flow

Configuration

Collect Payment

For Subscriptions

One-Time Charges

Create Payment Order

Payment Methods

Record Offline Payment

List Offline Payments

Virtual Accounts for Bank Transfers

Retrying Failed Payments

Refunds

Webhooks

Next steps