Process payments - Orgo Documentation

This walkthrough covers the full payment lifecycle: card payment via Stripe checkout, payment reconciliation via webhook, refund, and the parallel bank-transfer flow with invoice generation. It uses the Product, ProductPayment, and Invoice resources. Who is this for: backend integrations that drive the membership fee collection, ticket sales, or donation campaigns; finance-ops tools that automate refunds and reconcile against accounting systems.

Architecture

Orgo doesn’t process card data directly — that’s Stripe’s job. Orgo orchestrates the flow:

Create a Product             (or Product already exists from setup)
Generate Stripe checkout URL — Orgo creates the Stripe session
Member pays on Stripe        — Orgo never sees the card
Stripe webhook → Orgo        — payment captured
Orgo webhook → your system   — product_payment.updated fires
You reconcile                — update CRM, send receipt, etc.

Bank-transfer flow is parallel:

Issue Invoice                — generates PDF, emails to member
Member sends transfer        — out-of-band
Admin marks as paid          — via UI or API
Orgo webhook → your system   — product_payment.updated fires (same as card)

Same downstream event from your system’s perspective. That’s deliberate — your reconciliation code handles both cases identically.

Card payment — Stripe checkout

Step 1 — Generate a checkout URL

For a membership product the member is buying:

curl https://acme.orgo.space/api/v1/companies/01938d8e-c2f4-7c2a-b8e1-3f7a9b8c4f88/payment-checkout \
  -H "Api-Token: $ORGO_API_TOKEN"

For event-ticket purchases, the checkout URL comes back automatically inside the EventAttend response when the event has paid tickets — see Create and sell event tickets. Response includes a checkoutUrl:

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6...",
  "sessionId": "cs_test_a1B2c3D4e5F6",
  "expiresAt": "2026-01-15T11:30:00+00:00"
}

Redirect the user to checkoutUrl. Stripe handles the card collection.

Step 2 — Stripe completes the charge

On Stripe’s side, the charge succeeds (or fails). Stripe POSTs to Orgo’s webhook at /api/v1/stripe-webhook. This is invisible to your integration — Orgo handles it. Internally, Orgo creates a ProductPayment record with status: SUCCESS (or FAILED).

Step 3 — React via webhook

Subscribe to product_payment.updated:

curl -X POST https://acme.orgo.space/api/v1/webhook_subscriptions \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/orgo",
    "events": ["product_payment.created", "product_payment.updated"],
    "secret": "whsec_a3f8b2c4d6e8f1a3b5c7d9e1f3a5b7c9"
  }'

In your handler:

def handle(payload):
    if payload["event"] != "product_payment.updated":
        return
    if payload["object"]["status"] == "SUCCESS":
        record_payment_in_accounting(payload["object"])
        send_thank_you_email(payload["object"]["user"])

See Handle webhooks for the full receiver pattern.

Refunding a paid charge

When a member requests a refund (cancelled event, mistaken purchase, dispute settlement), call the refund endpoint:

curl -X PATCH https://acme.orgo.space/api/v1/product-payment/107/refund \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "amount": 5000,
    "reason": "duplicate"
  }'

amount in cents. Omit for a full refund. reason is passed through to Stripe — common values: duplicate, fraudulent, requested_by_customer. Used for Stripe’s dispute analytics. The refund returns immediately with the updated ProductPayment showing status: REFUNDED. Stripe processes the actual transfer over the following 5-10 business days. For partial refunds, call repeatedly until cumulative amount equals the original charge.

Refunds are not reversible. Once issued, the funds are returned to the cardholder. To re-charge, the cardholder must complete a new checkout.

Bank transfer with invoice

For members who pay by bank transfer (corporate memberships, multi-thousand-dollar annual fees, regions where cards are uncommon), the flow is:

Step 1 — Issue an invoice

curl -X POST https://acme.orgo.space/api/v1/invoices/create-for-bank-transfer \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productPrice": "/api/v1/product_prices/22",
    "billingName": "James Patterson",
    "billingAddress": "123 Beacon Street, Boston, MA 02108",
    "billingEmail": "james.patterson@example.com",
    "vatNumber": null
  }'

Response:

{
  "id": 284,
  "number": "INV-2026-00284",
  "status": "PENDING",
  "amount": 5000,
  "currency": "USD",
  "pdfUrl": "https://cdn.orgo.space/invoices/INV-2026-00284.pdf",
  "dateDue": "2026-02-14T10:30:00+00:00"
}

A PDF is generated and emailed to billingEmail. The member transfers funds to the account printed on the invoice.

Step 2 — Mark as paid

When you see the transfer hit the bank, mark the invoice:

curl -X PATCH https://acme.orgo.space/api/v1/invoices/284/mark-as-paid \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{"datePaid": "2026-01-18T14:22:00+00:00"}'

This creates the linked ProductPayment with status: SUCCESS and method: BANK_TRANSFER. Your webhook receiver sees the same product_payment.updated event it sees for card payments.

Cancellation, void, refund

Action	Endpoint	When to use
Cancel before payment	`PATCH /api/v1/invoices/cancel-bank-transfer`	Member changed mind; invoice never paid
Void	`PATCH /api/v1/invoices/{id}/void`	Issued in error; correct accounting record
Refund	`PATCH /api/v1/invoices/{id}/refund`	Paid invoice needs to be refunded (creates a credit memo)

Resending the invoice email

curl -X PATCH https://acme.orgo.space/api/v1/invoices/284/send-email \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{}'

Useful when the member’s accounts-payable department asks for a copy.

Reporting and reconciliation

All payments in a date range

curl "https://acme.orgo.space/api/v1/product_payments?datePaid[after]=2026-01-01&datePaid[before]=2026-01-31&order[datePaid]=asc" \
  -H "Api-Token: $ORGO_API_TOKEN" \
  -H "Accept: application/ld+json"

hydra:totalItems gives you the count, the array gives you the data. Paginate as usual.

Sum of successful payments

There’s no aggregation endpoint — fetch the page and sum locally. For monthly reporting, this is fine. For dashboards refreshing every minute, cache the result.

Stuck-pending invoices

curl "https://acme.orgo.space/api/v1/invoices?status=PENDING&dateDue[before]=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -H "Api-Token: $ORGO_API_TOKEN"

Returns invoices past their due date but still unpaid — your dunning list.

Common gotchas

The checkout URL returns Stripe's 'no account configured' error

Stripe is connected at the local-center level (preferred) or the tenant level. The product’s unit determines which Stripe account is used. If the unit doesn’t have Stripe connected, checkout creation fails. Check Settings → Local Centers → [Center] → Payments.

My ProductPayment shows SUCCESS but I never saw the webhook

Two causes: (1) the subscription wasn’t active at the time of the event — check the subscription state; (2) the receiver returned non-2xx 3 times in a row, so delivery is in the failed log. Hit GET /api/v1/webhook_subscriptions/{id}/delivery_logs and replay.

Refund returned 200 but the cardholder hasn't received the money

Stripe processes refunds asynchronously — typically 5-10 business days for cards, longer for some debit cards and most international cards. Check the refund status in Stripe’s dashboard for the authoritative answer.

Bank transfer invoice has the wrong VAT — can I edit it after issuing?

No. Invoices are immutable once issued (legal requirement). Void the existing invoice and issue a corrected one. The void preserves the audit trail; the new invoice carries a new number.

Can I charge a saved card without redirecting to Stripe?

Not via this endpoint. Orgo’s payment surface routes everything through Stripe’s hosted checkout. For card-on-file MOTO/subscription charges, use the SubscriptionProfile resource — Stripe handles the recurring billing.

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 accounting system

​Architecture

​Card payment — Stripe checkout

​Step 1 — Generate a checkout URL

​Step 2 — Stripe completes the charge

​Step 3 — React via webhook

​Refunding a paid charge

​Bank transfer with invoice

​Step 1 — Issue an invoice

​Step 2 — Mark as paid

​Cancellation, void, refund

​Resending the invoice email

​Reporting and reconciliation

​All payments in a date range

​Sum of successful payments

​Stuck-pending invoices

​Common gotchas

​What to do next

Architecture

Card payment — Stripe checkout

Step 1 — Generate a checkout URL

Step 2 — Stripe completes the charge

Step 3 — React via webhook

Refunding a paid charge

Bank transfer with invoice

Step 1 — Issue an invoice

Step 2 — Mark as paid

Cancellation, void, refund

Resending the invoice email

Reporting and reconciliation

All payments in a date range

Sum of successful payments

Stuck-pending invoices

Common gotchas

What to do next