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: https://<your instance>/en/region/commerce/?tab=payment-configurations

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), 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

Custom Portal

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:

1. Go to PayPal API access settings
2. Click NVP/SOAP Integration
3. Select API Signature and submit
4. Copy the Username, Password, and Signature values into Lumieos

PayPal Webhook ID:

1. Go to PayPal Developer Dashboard
2. Create a new application (name it “Lumieos”)
3. At the bottom, click Create Webhook
4. Open the PartnerPaymentConfiguration admin in Lumieos (see the Admin URL above — https://<your instance>/en/region/commerce/?tab=payment-configurations) and copy the PayPal Webhook URL it displays for this configuration. Paste that URL into PayPal’s webhook form.
5. Enable the Checkout and Dispute events
6. 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:

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: https://<your instance>/staff/django/first/partner/

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: https://<your instance>/staff/django/commerce/levelpaymentconfiguration/

Level Payment Configurations reference the Partner Payment Configurations created in Step 1. They define payment amounts and options for each program level.

Note: Level Payment Configurations must be created each season.

Step 4 — Set Up Event Levels

Admin URL: https://<your instance>/staff/django/events/eventlevel/

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.

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: https://<your instance>/en/region/commerce/

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 exempt status for invoices or teams to allow them to check in to events without payment.

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.