Overview#

Open Collective's payment layer is built around three distinct model types, each serving a different role in the money flow:

Payment processing logic lives in server/paymentProviders/ 1, with four provider implementations: stripe, paypal, opencollective, and transferwise. All providers implement the BasePaymentProviderService interface defined in server/paymentProviders/types.ts.

PaymentMethod — Inbound Contributions#

server/models/PaymentMethod.ts represents a payment instrument used to fund orders (contributions).

Key fields:

• service — one of stripe, paypal, opencollective, wise (deprecated: thegivingblock) 2
• type — one of ~20 values including creditcard, giftcard, manual, collective, bank_transfer, virtual_card, us_bank_account, sepa_debit, and more 3
• CollectiveId — the owner collective; can be NULL for one-time, unsaved payments 4
• limitedToTags, limitedToHostCollectiveIds — restrict usage to specific collectives or hosts 5
• monthlyLimitPerMember, initialBalance — spending caps enforced at use time 6

Core logic:

• canBeUsedForOrder() validates expiry, recurring support, tag/host restrictions, and available balance before allowing an order to proceed.
• getBalanceForUser() delegates to the provider's getBalance() method, then applies monthlyLimitPerMember and initialBalance caps.
• The features getter 7 calls findPaymentMethodProvider(this).features to expose provider capabilities like recurring support.

PayoutMethod — Outbound Expense Payments#

server/models/PayoutMethod.ts represents where a payee wants to receive expense payments.

Types 8:

• BANK_ACCOUNT — Wise-compatible bank account (uses RecipientAccount from transferwise types)
• PAYPAL — PayPal email; supports OAuth verification flow 9
• ACCOUNT_BALANCE — Pay to the payee's Open Collective balance
• STRIPE — Created automatically by ConnectedAccount hooks; cannot be manually edited or deleted 10
• CREDIT_CARD — Token-based card payout
• OTHER — Free-text custom instructions 11

Key behaviors:

• getFilteredData() whitelist-filters sensitive fields (IBAN, account numbers, etc.) before the data is sent to authorized users.
• createFromUserData() whitelists user input before persisting — prevents over-posting.
• findSimilar() detects duplicate payout methods using identifiable fields (IBAN, accountNumber, BIC, etc.) defined in IDENTIFIABLE_DATA_FIELDS.
• Only BANK_ACCOUNT, OTHER, and STRIPE types support fees-payer configuration 12.
• A payout method cannot be edited/deleted once it has been used in a non-cancelled/non-rejected expense 13.

ManualPaymentProvider — Host-Configured Manual Methods#

server/models/ManualPaymentProvider.ts models payment instructions that a fiscal host defines for contributors who cannot use automated processors (e.g., bank wire, checks). Unlike PayoutMethod (which belongs to a payee), this model belongs to the host and is presented to contributors at checkout.

Types 14: BANK_TRANSFER and OTHER

Key fields 15:

• CollectiveId — the fiscal host that owns this provider
• name, instructions (HTML, XSS-sanitized), icon — displayed to contributors at checkout
• data.accountDetails — optional structured bank account details (Wise RecipientAccount format)
• order — integer controlling display order; supports drag-and-drop reordering
• archivedAt — soft-disable when orders reference the provider (cannot be hard-deleted in that case)

Lifecycle:

• Can be hard-deleted only if no orders reference it; otherwise archive() sets archivedAt 16.
• Contributions made via a ManualPaymentProvider stay in pending status until a host admin manually confirms them 17.

GraphQL mutations in server/graphql/v2/mutation/ManualPaymentProviderMutations.ts cover create, update, delete/archive, and reorder. All mutations require host admin scope and enforce 2FA 18. The reorderManualPaymentProviders mutation validates that all providers belong to the same host before updating their order field 19.

Payment Provider Implementations (Automated)#

The four automated payment providers are registered in server/paymentProviders/index.ts and each lives in its own subdirectory: stripe/, paypal/, transferwise/, opencollective/.

Every provider must implement BasePaymentProviderService:

For providers with externally-managed recurring (e.g., Stripe subscriptions), the interface variant adds pauseSubscription() and resumeSubscription() methods. When implementing a new provider with external recurring, the freeze-account UI (FreezeAccountModal.tsx) and AccountMutations.ts must also be updated 20.

To add a new provider: create a class extending the appropriate BasePaymentProviderService variant in server/paymentProviders/{providerName}/, then export it from server/paymentProviders/index.ts 1.

Host-Level Configuration UI#

Fiscal hosts configure payment methods through two settings sections in the Dashboard:

Receiving Money#

components/edit-collective/sections/ReceivingMoney.tsx renders two subsections:

1. Automatic Payments — Stripe (EditStripeAccount) and PayPal (EditPayPalAccount with variation="RECEIVING") 21
2. Manual Payments — Bank Transfers (BankTransferMethods.tsx) and Custom Payment Methods (CustomPaymentMethods.tsx)
   • Manual payment editing is gated by the host's plan.manualPayments feature flag 22
   • BankTransferMethods manages BANK_TRANSFER type providers; CustomPaymentMethods manages OTHER type providers

Sending Money#

components/edit-collective/sections/SendingMoney.tsx exposes:

• Wise (TransferWise) — for batch expense payouts; gated by TRANSFERWISE feature flag with an upgrade prompt if needed 25
• PayPal — for PayPal expense payouts; gated by PAYPAL_PAYOUTS feature 26

Both BankTransferMethods and CustomPaymentMethods use the same set of GraphQL mutations from receive-money/gql.ts: createManualPaymentProvider, updateManualPaymentProvider, deleteManualPaymentProvider, and reorderManualPaymentProviders.

Key Entry Points#