Charge RPC

<!--

title: Charge description: Process a recurring payment using an existing mandate - charge customer's stored payment method for subscription renewal without requiring their presence last_updated: 2026-03-11 generated_from: backend/grpc-api-types/proto/services.proto auto_generated: false reviewed_by: engineering reviewed_at: 2026-03-05

approved: true

-->

Overview

The Charge RPC processes a recurring payment using a previously established mandate. This enables subscription billing and automated payment collection without requiring customer interaction or re-entering payment details.

Business Use Case: When a subscription billing cycle triggers (e.g., monthly SaaS renewal), you need to charge the customer's stored payment method. The Charge RPC uses the mandate reference from the initial SetupRecurring to process the payment without customer presence, following stored credential protocols for secure recurring billing.

Purpose

Why use Charge for recurring payments?

Key outcomes:

• Payment processed using stored mandate (no customer interaction required)
• Compliance with card network stored credential requirements
• New transaction ID for each charge (distinct from original mandate)
• Support for MIT (Merchant Initiated Transaction) protocols

Request Fields

Response Fields

Example

Request (grpcurl)

grpcurl -H "x-connector: stripe" \
  -H "x-connector-auth: {\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}" \
  -d '{
    "merchant_charge_id": "charge_sub_001",
    "mandate_reference_id": {
      "connector_mandate_id": "seti_3Oxxx...",
      "payment_method_id": "pm_1Oxxx..."
    },
    "amount": {
      "minor_amount": 2900,
      "currency": "USD"
    },
    "description": "Monthly Subscription - Pro Plan",
    "off_session": true,
    "mit_category": "RECURRING",
    "test_mode": true
  }' \
  localhost:8080 \
  ucs.v2.RecurringPaymentService/Charge

Response (Success)

{
  "connector_transaction_id": "pi_3Pxxx...",
  "status": "CHARGED",
  "status_code": 200,
  "merchant_charge_id": "charge_sub_001",
  "mandate_reference": {
    "connector_mandate_id": "seti_3Oxxx...",
    "payment_method_id": "pm_1Oxxx..."
  },
  "network_transaction_id": "txn_xxx...",
  "captured_amount": 2900
}

Response (Failure - Insufficient Funds)

{
  "connector_transaction_id": "pi_3Pxxx...",
  "status": "FAILED",
  "status_code": 402,
  "merchant_charge_id": "charge_sub_001",
  "error": {
    "code": "card_declined",
    "message": "Your card was declined.",
    "decline_code": "insufficient_funds"
  }
}

Status Values

MIT Categories

Best Practices

1. Set off_session: true - Always indicate that the customer is not present for recurring charges
2. Include mit_category - Properly categorize the charge type for compliance
3. Store connector_transaction_id - Save this for refund and dispute handling
4. Handle failures gracefully - Implement retry logic with customer notification
5. Use webhooks - Set up webhooks for asynchronous status updates

Next Steps

• Revoke - Cancel the mandate when customer unsubscribes
• SetupRecurring - Create initial mandate for new subscriptions
• Get - Check status of pending charges