The code looks like this (both for v3 and v4):

  def merge(self, merge_commit_message=None,
              should_remove_source_branch=False,
              merged_when_build_succeeds=False,
              **kwargs):
        """Accept the merge request. """
...

The issue is that when you call:

mr.merge(merged_when_build_succeeds=True)

The MR is merged immediately, without waiting for the pipeline to finish, which is not what is expected.

The problem is that he argument is called merge_when_build_succeeds (note: no ed at the end of merge) in v3 and merge_when_pipeline_succeeds in v4.

Good news is that the fix is trivial:

gl = gitlab.Gitlab("http://example.com", 'token', api_version=4)
project = gl.projects.get("foo/bar")
mr = project.mergerequests.list(iid=42)[0]
mr.merge(merge_when_pipeline_succeeds=True)

I can make a pull request in the documentation if you like until there is a proper fix