Skip to main content

Configure initial payment for Open API contract sign-ups

  • Updated

In this article, you will learn how to define per membership offer which charges should be collected directly at sign-up via the Open API, what happens when a payment fails, and how this affects your members' access.

Contents

Fast lane

  1. Settings / Membership signing / Membership offers
  2. Open the relevant membership offer
  3. Navigate to the Offer options section
  4. Select the charge types that make up the initial payment
  5. Optional: activate Require Initial Payment for Open API sign-ups
  6. Optional: activate Cancel contract creation on failed Initial Payment capture
  7. Save

What is the initial payment?

When a contract is signed via the Open API, your API partner can collect sign-up charges directly as part of the sign-up process. You control per membership offer which charge types count as an initial payment, whether that payment is mandatory, and what happens if the collection fails. These settings also directly affect access for members who were registered with outstanding payments.

Configuration in the membership offer

All initial payment settings are located in the Offer options section of the relevant membership offer under Settings / Membership signing / Membership offers. Open the offer you want to configure. The three new fields appear at the bottom of the section. Existing membership offers are automatically migrated with the default values described below. Your current operations are not affected by this.

Which charges are part of the initial payment?

In the field Initial Payment includes (if due on sign-up), you use a multi-select to define which charge types count as the initial payment. The available options are: membership fee, starter package, additional modules, and flat fees. By default, all four options are selected.

Important: only charges that are actually due at the time of contract conclusion are included. Future charges are not part of the initial payment. This definition applies not only to Open API sign-ups but also serves as the basis for access restriction across all other contract channels.

Making the payment mandatory for Open API sign-ups

The option Require Initial Payment for Open API sign-ups is inactive by default. When you activate it, your API partner must pass a valid payment token at the point of contract creation. The system automatically checks whether the authorized amount exactly matches the total of all due charges. If the amounts do not match, the sign-up is aborted and no contract is created.

If the option is inactive, no payment token can be passed at sign-up. An initial payment is then not possible through this channel.

You can activate this option in stages: define the charge types first, then switch on the requirement when you are operationally ready. Both steps are independent of each other.

What happens when a payment fails?

The option Cancel contract creation on failed Initial Payment capture is inactive by default. It takes effect when the actual payment collection fails after the sign-up has been submitted.

  • Option active: The system rolls back the contract creation. The contract is removed. The customer record is retained. Access is restricted until a new sign-up is completed successfully.
  • Option inactive (default): The contract remains in place. The outstanding amount is recorded in the member account and can be collected through your usual processes, for example via a payment run or a reminder.

How the payment process works

To understand when a failure can occur, here is how the process works: when a member signs up via the Open API, they authorize the payment upfront through your partner's payment interface. This authorization places a hold on the amount but does not yet collect it. The actual collection happens once the contract and the related charges have been booked in the system. A failure can occur at this point, for example if the card has been blocked or the authorization has expired in the meantime. If the payment token is not used within its validity period, the authorization is automatically released and the funds are freed.

For API partners: the preview endpoint returns the flag mandatoryOnSigning for each due charge, as well as the total of all mandatory charges in the dueOnSigningAmount field. The payment token must only be requested and passed based on this exact amount.

Special case: membership switch

For membership switches via the Open API, the same settings apply as for initial sign-ups. One exception exists: if the membership offer has the option to skip initial costs at membership start activated, all charges are treated as not due at the point of the switch. In this case, the preview endpoint returns mandatoryOnSigning: false for all charges and the total due amount is zero. The switch endpoint will not accept a payment token in this scenario.

Access restriction for outstanding initial payments

If your studio's access restriction configuration has the option to restrict access for unbalanced initial payments activated, the following scenarios apply:

  • Payment was authorized but collection fails later, no rollback: The contract remains. The member's access is restricted until the outstanding amount is settled.
  • Payment was not mandatory at sign-up: The member's access is restricted until the initial payment is settled retrospectively.
  • Payment fails and rollback is active: No contract exists. The customer record remains, but without an active membership access is not possible.
  • Sign-ups via other channels such as the sales support area, the Member Platform, or landing pages: these contracts are also subject to access restriction if the initial payment is defined in the membership offer and has not been settled. Access is only granted once all defined charge types have been balanced in the member account.

Related articles