Skip to main content
This walkthrough covers the payment lifecycle as an integration sees it: card payments collected by Stripe and reconciled through webhooks, the parallel invoice flow for bank transfers, offline payments, and refunds. It uses the ProductPayment and Invoice resources. Who is this for: finance-ops tools that reconcile Orgo against accounting systems, and backends that react to membership fees, ticket sales and donations.

Architecture

Orgo never touches card data. Stripe collects the card and Orgo records what happened as a ProductPayment. Orgo’s own checkout surfaces start the Stripe flow: the member fee screens, the public event checkout, donation pages and the company payment checkout. An integration does not create card charges directly. It reads and reacts.
The bank-transfer flow is parallel and produces the same downstream event:
Your reconciliation code can treat both cases identically.

Statuses and amounts

  • Payment statuses are lowercase: open, success, refunded, canceled, pending_accept.
  • Invoice statuses are lowercase: unpaid, paid, voided, refunded. Invoice types are manual_invoice, member_renewal and event_registration.
  • A payment’s amount and an invoice’s amount are in currency units (50.00 is fifty dollars), with a currency code alongside.

Card payments

Where checkout starts

Redirect the payer to the URL in the answer. Stripe handles the card. If Stripe is not connected for the organization or center, the call fails; see Stripe integration.

React through webhooks

Subscribe to the payment events (you need to be an Orgo administrator):
In your handler:
See Handle webhooks for the full receiver pattern.

Recording an offline payment

For cash, a cheque, or a transfer you received outside Orgo, record a completed payment directly. It requires organization-wide finance rights:
Pass exactly one of user (a member id) or contact (a contact id), amount, and either product (a product uuid, with an optional price id) or customProductName for a one-off item. The payment is created as success with no Stripe charge. paymentDate is optional.

Refunding a card payment

When a member asks for a refund (cancelled event, mistaken purchase), refund the payment:
Refunds are full refunds: the endpoint takes no amount and no reason. It needs finance rights over the payment’s center, and only a payment with status success can be refunded. The side effects:
  • The payment becomes refunded.
  • Any linked event registrations are canceled, ticket capacity is released and sold counts go down.
  • For membership payments, fee validity dates are recalculated.
A payment with no Stripe reference (imported or recorded offline) is only marked refunded, for money you returned outside Orgo. A payment that has an invoice is refunded from the invoice instead (below). For a partial refund, refund in Stripe’s dashboard and record the adjustment in your own books.
A refund cannot be undone. To charge again, the payer must complete a new checkout.

Bank transfer with an invoice

Two actors can start a bank transfer.

A member requests an invoice

A signed-in member (any member, no admin rights) asks for a membership renewal invoice with POST /api/v1/invoices/create-for-bank-transfer, using their own session. The answer carries the invoice series, amount, currency and the organization’s banking details to pay into. A member can have only one pending bank-transfer invoice at a time. The member can withdraw it with POST /api/v1/invoices/cancel-bank-transfer, which voids their latest unpaid one (404 if there is none).

An administrator issues an invoice

A user with organization-wide admin rights creates a manual invoice, which Orgo numbers, generates as a PDF and emails to the payer immediately:
The invoice is created unpaid with type manual_invoice, a generated invoiceNumber and seriesNumber, and a download link (GET /api/v1/invoices/{id}/download). Use user, contact or company for the payer. For a membership invoice add isMembership: true, membershipProductPrice and the membership start and end dates, so payment extends the fee period. Billing fields (billingName, billingVatNumber, billingEmail, and so on) are printed on the PDF.

Mark as paid

When the transfer lands in the bank:
This sets the invoice to paid, creates a linked ProductPayment with status success, updates the fee validity of the member or company for membership invoices, confirms the registrations for event invoices, stamps a PAID badge on the invoice and emails the updated copy. Your webhook receiver sees the same product_payment events as for a card payment.

Void, refund and resend

All three need organization-wide admin rights. A refund sets the invoice to refunded, records who and when, turns the payment into refunded, cancels linked event registrations and recomputes fee validity.

Reporting and reconciliation

Payments in a date range

hydra:totalItems gives the count; the array gives the data. Paginate as usual. Other filters: user, contact, company, product.uuid, product.type, paymentType, amount[gte], amount[lte], exists[isRefunded].

Sum of successful payments

There is no aggregation endpoint. Fetch the pages and sum locally. For monthly reporting that is fine; for dashboards refreshing every minute, cache the result.

Unpaid invoices past their due date

Invoices cannot be filtered by due date, so compare invoiceDueDate with today on your side to build the dunning list.

Common gotchas

Stripe has to be connected for the organization or for the center that owns the product. Check the center’s payment settings, see Stripe integration.
Two usual causes: the subscription was paused (isActive: false) at the time, or your receiver returned non-2xx until the attempts ran out. Read GET /api/v1/webhook_subscriptions/{id}/delivery_logs and replay from there.
Stripe settles refunds over several business days, longer for some cards. The authoritative answer is in Stripe’s dashboard.
Do not edit a sent invoice. Void it and issue a corrected one. The void keeps the audit trail, and the new invoice gets a new number.
Not through a general API call. Recurring fees run through the member’s subscription, which Stripe bills on its schedule.

What to do next