Developers · API documentation

Moodle integration

How EduPay and Moodle work together: plugin, single sign-on, student block, cohorts, suspension for late payment and plugin routes.

EduPay and Moodle talk to each other both ways:

  • From Moodle to EduPay, through the plugin installed in Moodle: the student signs in to Moodle with their EduPay login, sees their financial status in a block and opens the student portal without typing a password.
  • From EduPay to Moodle, through Moodle's web service: when the enrollment is made, EduPay creates the user in Moodle and adds them to the Moodle cohort of their EduPay cohort. If the student falls behind on payments, EduPay removes them from the Moodle cohort; when they pay, it puts them back.

This page describes the integration as it works today, for whoever installs the plugin and whoever supports the school.

The pieces

Piece Where it lives What it is for
auth_edupay plugin (Edupay SSO) Moodle, in auth/edupay "Sign in with edupay" button on the Moodle login page
block_edupay plugin (edupay Financial Portal) Moodle, in blocks/edupay Block with the financial summary and the student portal button
EduPay Moodle integration EduPay panel, under Integrations → LMS Platforms Moodle address and web service token, so EduPay can enroll students, block them and restore their access

Both plugins work on Moodle 4.1 or newer and are available in Portuguese, English and Spanish.

What the student sees

  • On the Moodle login page, the Sign in with edupay button. They sign in with the same e-mail or CPF (Brazilian individual taxpayer ID) and the same password as the EduPay student portal.
  • In Moodle, the edupay Financial Portal block with "Welcome, name", how many installments are open, the contract status and the Access financial portal button, which opens the student portal in a new tab, already signed in.
  • In the EduPay student portal, the button to the academic system, which opens Moodle already signed in (after the student has been synced with Moodle at least once).
  • In the courses, they are added automatically when the enrollment is made, removed if they are late on payment beyond the school's deadline, and added back when they pay.

Install in Moodle

A Moodle administrator does the installation.

  1. Ask the EduPay team for the auth_edupay.zip and block_edupay.zip files.
  2. In Site administration → Plugins → Install plugins, upload both (or copy the edupay folders into auth/ and blocks/) and complete the Moodle upgrade.
  3. In Site administration → Plugins → Authentication → Manage authentication, enable Edupay SSO.
  4. In Site administration → Advanced features, turn on Enable web services, and in Plugins → Web services → Manage protocols, enable REST. The plugin does not turn these on by itself.

Install both plugins, even if the school only wants the block: the users that EduPay creates in Moodle use the auth_edupay authentication method.

During installation, the block creates the Edupay Integration external service (edupay_integration) in Moodle, with the six functions EduPay uses (see "From EduPay to Moodle" below).

Configure

1. In EduPay: the plugin keys

In Integrations → API Tokens, create the key with one of the Moodle bundles:

Bundle Permissions Where to use it
Moodle (full) moodle:auth, moodle:student, moodle:portal In both plugins
Moodle (SSO only) moodle:auth In auth_edupay
Moodle (block only) moodle:student, moodle:portal In block_edupay

The Moodle key works with the public API on or off. When you rotate it, the old key is valid for only 24 more hours: replace it in both plugins within that time.

2. In Moodle: the plugins

auth_edupay (Site administration → Plugins → Authentication → Edupay SSO):

Setting What it is Default
Edupay tenant URL The EduPay address (https://edupay.estudiosite.com) empty
API Token The edp_... key with moodle:auth empty
Login button text The button text on the login page Sign in with edupay
Auto-create users Creates the user in Moodle on the first login, if it does not exist yet on
Update user on login On every login, updates the first name and last name with the ones from EduPay on

block_edupay (Site administration → Plugins → Blocks → edupay Financial Portal):

Setting What it is
Edupay tenant URL The EduPay address
API Token The edp_... key with moodle:student and moodle:portal
Moodle REST token Generate Moodle token button: creates the token EduPay uses to call Moodle (see step 3)

Then add the block to the Dashboard or to the course pages. In each block you can hide the summary and change the button text.

3. In EduPay: the Moodle integration

  1. In Moodle, in the block settings, click Generate Moodle token under Moodle REST token and copy the token. It belongs to the administrator who clicked, does not expire and only works for the Edupay Integration service. Regenerate token deletes the service's previous tokens.
  2. In EduPay, under Integrations → LMS Platforms → Moodle, fill in the Moodle Platform base URL (with https://, exactly the Moodle site address), paste the Moodle REST Token, turn on Integration enabled and save.
  3. Click Test connection.

4. Cohorts and courses

EduPay puts the student in a Moodle cohort. Moodle itself is what brings the cohort into the courses:

  1. Each EduPay cohort is linked to a Moodle cohort. When you create the cohort, tick Also create in Moodle; for a cohort that already exists, use the Create cohort in Moodle button on the cohort page. The Moodle cohort is created site-wide, and the students already enrolled in the cohort are sent to Moodle. You can also enter the Moodle cohort ID by hand — it is the cohort's internal number (the id that shows in the cohort's address), not the "Cohort ID" field in Moodle.
  2. In each Moodle course, add the Cohort sync enrolment method with that cohort.

Single sign-on: how it works

  1. The student clicks Sign in with edupay in Moodle.
  2. Moodle takes them to https://edupay.estudiosite.com/moodle/sso, passing Moodle's own address. EduPay finds the school by this address: it must be the same as the base URL saved in the integration.
  3. If the student is already signed in to the EduPay portal, they go straight through. Otherwise, they sign in with the portal login and password.
  4. EduPay sends the student back to Moodle with a single-use code, valid for 5 minutes.
  5. The plugin exchanges the code for the student's data (name and e-mail), finds the Moodle user by e-mail — or creates it, if "Auto-create users" is on — and signs the student in.

The normal Moodle login stays available for anyone who does not use the button. Users with the edupay method can only sign in through the button: the Moodle password does not work for them, and neither does Moodle's password change.

From EduPay to Moodle

EduPay calls Moodle's web service (/webservice/rest/server.php) with the REST token:

Moodle function When
core_webservice_get_site_info Test connection
core_user_get_users Find the student's user by e-mail
core_user_create_users Create the user, if it does not exist (username = e-mail, edupay method)
core_cohort_create_cohorts Create the Moodle cohort for the EduPay cohort
core_cohort_add_cohort_members Add the student to the Moodle cohort (enrollment and access restored)
core_cohort_delete_cohort_members Remove the student from the Moodle cohort (block and cancellation)

When the student joins, leaves and comes back:

Moment What happens in Moodle
Enrollment made by the school (panel or API) Joins the cohort right away
Purchase through the sales page Joins when the first payment is confirmed (right away, if there is nothing to pay)
Installment overdue for more days than the school's deadline Leaves the cohort (daily routine, overnight)
Payment that clears the overdue amount Comes back to the cohort
Enrollment cancelled Leaves the cohort

The blocking deadline is the Days to mark as overdue field in Settings (default: 30). Despite the name, the installment becomes overdue the day after the due date; this number only decides how many days late take the student out of Moodle.

When a call to Moodle fails, the enrollment's sync status becomes "failed" and the error shows up in the integration. On the enrollment screen, the Re-sync Moodle button tries again.

Points to watch

  • Everything is matched by e-mail. The EduPay student and the Moodle user are the same person when the e-mail is the same. A student without an e-mail does not go to Moodle.
  • "Update user on login" changes the authentication method of an existing Moodle user with the same e-mail to edupay. After that, their old Moodle password stops working. For teachers and administrators whose e-mail is the same as a student's, turn this option off.
  • Name or e-mail changes in EduPay do not reach Moodle on their own. The name is updated on the next login through the button, if the option is on.
  • Completing the enrollment does not remove the student from Moodle. Only cancellation and the block for late payment do.
  • Leaving the cohort has, in the course, the effect configured in Moodle's cohort sync enrolment. With Moodle's default, the student is unenrolled from the course.
  • Teachers and administrators who are not students in EduPay see "Could not load data" in the block. This is expected.
  • The block keeps the summary for 5 minutes in the Moodle session. A new payment shows up in the block after that, or on the next login.

Routes used by the plugins

The routes below are for the plugins only. They are frozen: they do not change with public API versions, so that the plugin installed at schools keeps working without an update. To integrate other systems, use the public API.

Route Permission Success response
GET /api/moodle/auth/verify?token= moodle:auth {"name", "email", "student_id"}
GET /api/moodle/student/summary?email= moodle:student {"student_name", "open_installments", "contract_status", "contract_status_label"}
POST /api/moodle/auth/portal-token (body {"email"}) moodle:portal {"url", "expires_in": 300}
  • Key in the Authorization: Bearer edp_... header, the same as the public API keys. The school is the key's school.
  • Errors in the old format, {"error": "..."}: 401 "Unauthorized", 403 "Forbidden — insufficient scope", 404 "Not found" (or "Invalid or expired token" and "Student not found" in verify) and 422 "Portal not configured".
  • Limit of 60 calls per minute per key, separate from the public API limits.
  • They do not depend on the public API switch.

Moodle in the public API

To follow the sync from another system:

  • GET /students/{id} returns moodle_user_id, the user's ID in Moodle.
  • GET /enrollments returns moodle_sync_status: null (not sent to Moodle yet), synced, suspended (out of the cohort for late payment), removed (out because of cancellation) or failed.
  • GET /cohorts returns moodle_cohort_id, and GET /offerings, moodle_course_id.
  • The enrollment.suspended and enrollment.reactivated webhooks arrive when the student leaves the cohort for late payment and when they come back. See Webhooks.
  • POST /students/{id}/portal-link generates the same portal sign-in link that the block uses, for any system.