Architecture
Orgo never touches card data. Stripe collects the card and Orgo records what happened as aProductPayment. 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.
Statuses and amounts
- Payment statuses are lowercase:
open,success,refunded,canceled,pending_accept. - Invoice statuses are lowercase:
unpaid,paid,voided,refunded. Invoice types aremanual_invoice,member_renewalandevent_registration. - A payment’s
amountand an invoice’samountare in currency units (50.00is fifty dollars), with acurrencycode alongside.
Card payments
Where checkout starts
React through webhooks
Subscribe to the payment events (you need to be an Orgo administrator):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: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: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 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 withPOST /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: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: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
invoiceDueDate with today on your side to build the dunning list.
Common gotchas
The checkout fails because no Stripe account is configured
The checkout fails because no Stripe account is configured
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.
My payment shows success but I never saw the webhook
My payment shows success but I never saw the webhook
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.The refund returned 200 but the cardholder has no money yet
The refund returned 200 but the cardholder has no money yet
Stripe settles refunds over several business days, longer for some cards. The authoritative answer is in Stripe’s dashboard.
The invoice has the wrong VAT: can I edit it?
The invoice has the wrong VAT: can I edit it?
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.
Can I charge a saved card without redirecting?
Can I charge a saved card without redirecting?
Not through a general API call. Recurring fees run through the member’s subscription, which Stripe bills on its schedule.
What to do next
- Handle webhooks: react to payment events
- Create and sell event tickets: payment in the ticketing context
- Sync your CRM with Orgo: push payment events into your CRM or accounting system

