Setting Up Payments
Payments are configured through a series of data models in Lumieos. This guide walks through creating payment provider configurations, setting up billing information, and connecting payment configurations to event levels so that event registration can collect fees.
Tip: Use the instance selector in the top navigation bar to personalize every admin URL on this page to your deployment. Until you pick one, URLs show a
<your instance>placeholder.
Step 1 — Create Partner Payment Configurations
Admin URL:
Partner Payment Configurations are reusable payment routings for each partner. You can have multiple configurations of each type, but only one of each type can be assigned to a specific Level Payment Configuration (covered in Step 3).
Supported types: Paper (Mail Check/Money Order), EFT / Bank Transfer, Custom Online Portal, PayPal, and Yoco. For each configuration, fill in the type-specific values described below.
Note: The “Custom Metadata” field allows you to set up specific metadata for financial use. However, this cannot be tested in the sandbox environment.
Type-Specific Instructions
Paper Payments
| Field | Details |
|---|---|
| Paper Mailing Address | Include all components of the address, including attention line. |
| Paper Memo Instructions | There is no additional copy text in the UI, so be verbose. For example: “Please write your team number(s) in the memo field.” |
EFT / Bank Transfer
Use this type to print your banking details on the invoice so a payer can make a bank transfer. EFT is settled manually: the payer uploads proof of payment and a region admin marks the invoice as paid.
| Field | Details |
|---|---|
| Bank Name | The bank holding the account, e.g. Standard Bank. |
| Account Holder | The name the account is registered in. This is what the payer’s bank will check against. |
| Account Number | Required. |
| Branch Code | Required. |
| Account Type | Cheque / Current, Savings, or Transmission. Optional — leave unset if it does not apply. |
| Reference Instructions | What the payer should quote as the payment reference, e.g. “Use your team number as the reference.” When left blank, the invoice shows the invoice number as the reference. |
| Additional Instructions | Any further guidance shown alongside the banking details. |
Once created, attach the configuration to a Team Formation Configuration or a Level Payment Configuration (Step 3) for the details to appear on invoices.
Note: A Team Formation Configuration with only the older Enable EFT switch turned on still offers EFT and proof-of-payment upload, but shows no banking details. Attach an EFT configuration to show them.
Custom Portal
| Field | Details |
|---|---|
| Portal Fee | Listed in cents, not dollars. For example, enter 500 for $5.00. |
PayPal
Note: For some PayPal business accounts, API access might not be enabled by default. The user should log in to their PayPal account and check their profile settings under Account Settings > Website payments > API access to ensure it is active.
PayPal API Username, Password, and Signature:
- Go to PayPal API access settings
- Click NVP/SOAP Integration
- Select API Signature and submit
- Copy the Username, Password, and Signature values into Lumieos
PayPal Webhook ID:
- Go to PayPal Developer Dashboard
- Create a new application (name it “Lumieos”)
- At the bottom, click Create Webhook
- Open the PartnerPaymentConfiguration admin in Lumieos (see the Admin URL above — ) and copy the PayPal Webhook URL it displays for this configuration. Paste that URL into PayPal’s webhook form.
- Enable the Checkout and Dispute events
- Copy the Webhook ID value into Lumieos
Warning: When saving the API Username, Password, and Signature, Lumieos will attempt to validate the credentials. While the error only appears tagged to the “Username” field, it could mean that any of the three values are wrong. For security reasons, the API does not indicate which value is incorrect — it only reports that the combination is invalid.
Note: If you are having trouble saving these credentials, try regenerating them from PayPal. There have been cases where PayPal provides bad credentials.
Yoco
Yoco is used for online card payments in South Africa. Lumieos redirects the user to Yoco’s hosted checkout and settles the invoice when Yoco sends the matching webhook event.
You will need the following values from the Yoco Business Dashboard:
| Field | Where to get it | Notes |
|---|---|---|
| Yoco Public Key | Dashboard → Sell Online → Integrations → Online Payments API | Starts with pk_live_... (or pk_test_... in sandbox). Safe to expose. |
| Yoco Secret Key | Same page as the Public Key | Starts with sk_live_... (or sk_test_...). Treat as a password — never commit or share. |
Enter both values in the Payment Configuration dialog and save. Lumieos will register the webhook with Yoco for you using its API — there is no manual webhook setup step.
Warning: When saving the configuration, Lumieos will validate the secret key by calling Yoco and then register the webhook. If validation or registration fails, double-check that you copied the full key and that you are using a live key for a production instance (sandbox keys will not work against live merchants).
Step 2 — Set Up Billing Information
Admin URL:
The organization information shown on invoices is configured on the FIRST Partner data model.
Billing Phone and Billing Email are shown on the invoice only if present.
Step 2a — Enable Donation Support (Optional)
On the same Partner admin page, you can enable donation support. This adds a donation workflow and line item to any invoice, regardless of payment backend.
Step 3 — Set Up Level Payment Configurations
Admin URL:
Where the Partner Payment Configurations from Step 1 hold your payment credentials and routing (your PayPal keys, your paper mailing address, and so on), a Level Payment Configuration sets the per-level pricing — the fee, the deadline, and which of those payment methods teams may use — and points at the provider configurations it needs. A Level Payment Configuration is then attached to one or more event levels (Step 4).
Manage them from Commerce → Level Pricing (). Adding, editing, or removing a configuration requires partner administrator privileges; commerce managers without that privilege can open the list and view a configuration read-only. The Used by column shows how many levels currently share each configuration at a glance.
Note: Level Payment Configurations must be created each season.
Creating or Editing a Configuration
- Open Commerce → Level Pricing.
- Click Add Level Payment Configuration, or choose Edit from the actions menu on an existing row.
- Fill in the fields described below.
- Click Create (or Save).
Warning: A Level Payment Configuration can be shared by many levels and events. Editing one changes the pricing and payment options for every level and event that uses it — not just the one you opened it from. If you need different pricing for a particular level, create a separate configuration instead.
| Field | Details |
|---|---|
| Name | A label for this configuration. This is what you pick from when attaching a configuration to a level. |
| Registration fee | The amount charged per registration, in whole dollars (no cents). |
| Deadline | Optional. The date by which payment is due. |
| Payment timing | Collect payment before registration — teams pay first, then register. Collect payment after registration — teams register first, then pay. |
| Registrations per payment | How many event registrations a single payment covers (default 1). |
| Payment policies URL | Optional. A link to your refund/payment policy, surfaced to teams during checkout. |
| Hide pricing externally | When enabled, the fee is hidden from public-facing pages. |
| Payment methods | For each provider — Paper, Custom Portal, PayPal, Stripe, and Yoco — choose which Partner Payment Configuration (from Step 1) teams may pay through, or None to disable that method. Only providers that already have a matching Partner Payment Configuration can be selected; the others are disabled with a Manage payment configurations link back to Step 1. |
Note: If the Registration fee is 0, Payment timing must be set to Collect payment after registration — Lumieos will not save a free configuration that collects before registration.
Enabling Purchase Orders (PO Received)
Some teams — particularly those backed by a school or district — pay via a purchase order that is issued and mailed before the funds actually arrive. If you want to let those teams participate while their payment is still in flight, enable the Allow PO option on the Level Payment Configuration.
| Setting | Effect |
|---|---|
| Allow PO | When enabled (default is off), region administrators can mark an active invoice for this configuration as PO Received. The team is then treated as awaiting payment rather than unpaid, so it can register and participate before the money settles. You mark the invoice paid manually once payment arrives. |
Leave Allow PO off for configurations where every team is expected to pay before participating. See Purchase Orders (PO Received) under Managing Invoices for the day-to-day workflow.
Removing a Configuration
Choose Delete from the actions menu on a configuration. Because a configuration can be tied to real money and live registrations, Lumieos blocks the deletion while it is still in use — you must clear the references first:
- Attached to one or more levels — detach it from every level that uses it first. Lumieos lists the affected levels so you know where to look.
- Referenced by a discount coupon — remove it from any coupon that targets it.
- Referenced by existing invoices — a configuration that has already been billed on an invoice cannot be deleted at all.
Note: A few advanced options are not part of the Level Pricing editor — for example the extra purchasable items that can be added to a configuration’s invoices — and remain on the Level Payment Configuration in the Django admin ().
Step 4 — Set Up Event Levels
Admin URL:
Once payment configurations are complete, attach them to levels for the season. Payment configurations are required for events to appear in the event registration flow — they are what connect payments to the front end.
When you edit a level and set its Level Payment Configuration, the level editor links straight to the Level Pricing tab (Step 3) so you can add a new configuration without losing your place — a configuration you create there is immediately available to select on the level.
Team Formation Invoices (Default Invoice Pricing)
Admin URL: — Team Formation tab
Regions that use Lumieos for initial team creation configure the default invoice line items on the Team Formation Configuration. Every formation invoice is pre-populated from these settings, so this is where you set up your standard pricing — for example a team registration fee, a challenge set, and a shipment fee.
All amounts are entered in whole units of the configuration’s currency (e.g. Rand, no cents).
| Setting | Invoice result |
|---|---|
| Fee | The team formation/registration fee — the base line item on every formation invoice. |
| Bundled Event Registration + Display Fee | Optionally bundles an event registration with formation. Split mode shows it as its own line that adds to the total; Included mode shows it at 0 with an “(Included)” label. |
| Requires Shipping | Collects a shipping address from the team on the invoice page before it can be finalized. |
| Shipped Items + Display Fee | Names the physical items shipped with formation (e.g. “Challenge Set”) and prices them as their own line. Supports the same Split / Included fee modes. |
| Shipping Fee + Label | The courier/delivery cost (e.g. “Shipment”), itemized as its own line on the invoice. |
Note: Teams can opt out of shipped items while their invoice is in draft. Opting out removes both the shipped items line and the shipping fee line, and the shipping address is no longer required.
Managing Invoices
Partner Invoice Dashboard
The partner invoice dashboard allows region administrators to view all invoices across their region, submit payments, and see overall payment statistics.
Admin URL:
Note: A new permission (accessible from the Partner admin page) is required to access the invoice dashboard.
From the dashboard, you can:
- View all invoices and their current status
- Submit payments on behalf of users using the Submit Payment button
- See how invoices were paid, including payer name, check numbers, and transaction IDs
Warning: When submitting a payment, the invoice creator and all users of all teams on the invoice will receive a notification.
Note: It is not currently possible to mark a general exempt status for invoices or teams. The PO Received workflow below is the supported way to let a team participate before payment settles, and it only applies to invoices backed by a purchase order.
Purchase Orders (PO Received)
When a team pays by purchase order, the funds often arrive well after the team needs to register and compete. The PO Received workflow lets you record the PO against an invoice and let the team participate immediately, while keeping the invoice in an unpaid state until payment actually settles.
Note: This workflow is only available when Allow PO is enabled on the invoice’s Level Payment Configuration (see Enabling Purchase Orders in Step 3). If it is not enabled, the Mark PO Received action does not appear.
Admin URL: Invoice detail page — → open the relevant invoice
Marking an Invoice PO Received
On an active invoice whose payment configuration allows purchase orders, a Mark PO Received button appears alongside the payment actions. Selecting it opens a dialog that asks for:
| Field | Details |
|---|---|
| PO Number | Required. The purchase order reference number from the team’s school or organization. |
| PO Document | Required. Upload a copy of the purchase order — a PDF or an image (PDF, PNG, JPG, JPEG, GIF, or BMP), up to 10 MB. |
Confirming the dialog moves the invoice into a distinct PO Received status and does the following:
- The team’s covered event registrations are treated as awaiting payment rather than unpaid, so the team is no longer flagged for missing payment and can register and participate.
- The invoice creator and the users on any team attached to the invoice receive a notification.
- The recorded PO number, the date it was received, and a link to the uploaded PO document are shown on the invoice detail page.
Important: A PO Received invoice is not counted as paid. Payment is still due, and the invoice continues to appear in your open/outstanding totals until you settle it.
Settling Payment
When the payment actually arrives, mark the invoice paid the same way you would any other invoice — use the Mark as Paid / Submit Payment action on the invoice. This moves the invoice from PO Received to Paid and clears the awaiting-payment flag from the team’s registrations.
Note: If the team instead completes an online payment (for example through PayPal) against a PO Received invoice, Lumieos reconciles it automatically — the incoming payment settles the invoice to Paid and clears the PO awaiting-payment flag without any manual step.
Reverting a Purchase Order
If a PO was recorded in error, use the Revert PO action on a PO Received invoice. This returns the invoice to the active (awaiting payment) state, clears the recorded PO number and document, and removes the awaiting-payment flag from the team’s registrations — restoring the normal unpaid behavior.
Impersonating the Payment Portal
Region administrators can impersonate users to view their payment portal and act on their behalf. This is accessible via the green impersonation button on the region team list.
The user’s payment portal includes a tabular view of all invoices on their account. Paid invoices are retained from prior seasons.
Extra Items & Coupons
- Extra Items — Additional purchasable items can be added to invoices beyond standard registration fees.
- Discount Coupons — Coupons can be configured to apply discounts to invoices during the payment flow.