Payment Agreements

What are payment agreements?

In the context of RaiseNow, a payment agreement is defined as an agreement between a payer and a payee (the entity receiving funds) for a one-off or recurring payment of a defined amount. A payment agreement may refer to both non-binding pledges as well as contractual obligations, such as membership fees. Enforcement of payment agreements is the responsibility of the payee, not RaiseNow. Depending on the payment method (for example, direct debit), the payee may leverage RaiseNow functionality such as dunning to recover missed payments.

Why are payment agreements not payments?

Long-time RaiseNow customers may be used to seeing “pledges” in the legacy RaiseNow Manager represented as transactions with additional properties. However, this approach treats two fundamentally different concepts as the same thing—an agreement: the agreement itself and its corresponding payment. This leads to a number of issues. For example, a successfully submitted payment agreement does not count towards total revenue, unlike pledges in RaiseNow Manager. Revenue is only recognised once an actual payment is registered, just as it is for any other payment.

Additional issues arise from handling one-off and recurring “pledges” within the same object. This creates challenges for third-party integrations, which must deal with an inconsistent data model.

By modelling payment agreements as a dedicated object, payments can now be reconciled with payment agreements. This allows for a cleaner representation of use cases where data is captured on RaiseNow forms but may or may not be reconciled against payments on the RaiseNow platform. In addition, payment agreements no longer have a direct impact on transactions unless they are confirmed. This provides a more accurate representation of funds actually received.

Method of payment and payment agency

Payments for a given payment agreement may be initiated either by the payer or by the payee. If the payment is initiated by the payer, the payer is considered the payment initiation agent. If the payment is initiated by the payee, then the payee is considered the payment initiation agent. A method of payment therefore implies the payment initiation agency. For example:

• Payment by payment slip (Swiss QR Bill): the payer is the payment initiation agent.
• Payment by direct debit: the payee is the payment initiation agent.

If RaiseNow acts on behalf of the payee when initiating the payment, RaiseNow is considered the payment initiation agent on behalf of the payee. For example:

• A direct debit payment is initiated via a provider such as Stripe or via a file-based direct debit process (pain.008 generation). In this case, RaiseNow acts as the payment initiation agent on behalf of the payee.
• Direct debit information is captured via RaiseNow payment agreements, but payments are initiated via third-party tools. In this case, the payment initiation agent remains the payee.

Payment agreements are predominantly intended for use cases where RaiseNow is not the payment initiation agent. However, some scenarios blur this distinction.

Example: A donor commits to a recurring payment agreement using Swiss QR Bill as the selected method of payment. At a later point in time, the donor changes the payment method to a credit card. In this case, the payment initiation agent changes from the donor to RaiseNow on behalf of the payee.

charged_by: "external"

If the payment initiation agent is not RaiseNow, subscriptions resulting from recurring payment agreements will include the following flag:

charged_by: "external"

This indicates that RaiseNow does not manage the payment schedule for this recurring donation and therefore does not generate invoices, charge attempts, or payments based on the configured payment schedule. However, if RaiseNow later processes a payment corresponding to such a subscription (for example, by processing a CAMT file), these objects will still be created.

RaiseNow will also not generate SEPA mandate references for payments or subscriptions when it is not the payment initiation agent.

Payment agreements with Swiss QR Bill

tip

For customers migrating from RaiseNow Manager, required configurations will be transferred to RaiseNow Hub. For new customers or new configurations, RaiseNow Support will initially configure these variables for you.

With the introduction of payment agreements, a new payment method becomes available in RaiseNow Hub: ch_qr_reference. If a payment agreement is created using this payment method, RaiseNow automatically generates a Swiss QR Bill as a PDF document, and the payment agreement is created with a reference property. To retrieve the PDF, two URLs are provided:

• Protected client-side access:
  https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/swiss-qr.pdf
• Direct access via token:
  https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/{{token}}/swiss-qr.pdf

Protected client-side access requires the user to answer a gate question using information previously submitted on the donation form (firstName, lastName, postalCode). Providing the correct values generates the direct access token used to download the PDF.

You can use the following formula to generate the token for direct access in your backend systems:

sha512(paymentAgreementUuid,firstName,lastName,postalCode)

locale refers to the two-letter, lowercase ISO language code in which the PDF is rendered.

Required creditor information

To generate the PDF, the following variables are mandatory in the payment method configuration:

• Creditor name
• Creditor address line 1
• Creditor address line 2
• Creditor IBAN
• Creditor default locale

ISR reference number configuration

The following variables must be defined for RaiseNow to generate ISR reference numbers. RaiseNow enforces uniqueness per account to prevent the generation of duplicate reference numbers.

• Prefix for the reference number: all generated reference numbers start with this value.
• Running variable range minimum and maximum values: reference numbers are generated within the defined range, starting from the minimum value.

info

It is not possible to directly include variables used or generated during the donation process, such as campaign or customer numbers, in the generated ISR reference. As these values may be freely injected by client-side business logic, this could introduce incompatible string values and/or duplicate reference numbers.

Documents generated for payment agreements

Depending on the payment agreement variant and the customer’s configuration, an optional documents object may be included with the payment agreement.

For Swiss QR Bill payment agreements, a QR Bill is always generated, resulting in a document object with the following properties:

{
  "uuid": "<payment-agreement-uuid>",
  ...
  "documents": {
    "ch_qr_reference_form_url": "https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/swiss-qr.pdf",
    "ch_qr_reference_token_url": "https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/{{token}}/swiss-qr.pdf"
  },
  "reference": "<27-digit-isr-reference>",
  ...
}

For direct debit payment agreements, a direct debit mandate PDF is generated if:

• the customer has a mandate template stored at RaiseNow, and
• the payment method is either ch_dd or ch_ta.

{
  "uuid": "<payment-agreement-uuid>",
  ...
  "documents": {
    "direct_debit_form_url": "https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/dd-mandate.pdf",
    "direct_debit_token_url": "https://documents.raisenow.com/{{locale}}/payment-agreements/{{payment_agreement_uuid}}/{{token}}/dd-mandate.pdf"
  },
  ...
}

In both cases, the token is calculated as:

sha512(paymentAgreementUuid,firstName,lastName,postalCode)

Recurring payment agreements

A recurring payment agreement is linked to a RaiseNow subscription. In this context, the subscription object serves as the payment schedule and also provides the link to the payment source, just as it does for any other subscription. This approach has several advantages:

• It avoids duplicate modelling of payment schedules, reducing implementation effort for API consumers.
• Donors can update the payment method for a subscription associated with a payment agreement via Tamaro, just as they would for any other recurring payment.

Reconciling payments and payment agreements

RaiseNow can automatically match referenced payments and direct debit payments by processing CAMT files provided by your bank. See this article for details on RaiseNow reconciliation services.

For one-off payment agreements, the resulting payment automatically references the payment agreement and updates its status to fulfilled.

For recurring payment agreements, incoming payments are associated with the corresponding subscription.

• Direct debit

  • If RaiseNow acts as both the payment initiation agent and the reconciliation agent, the subscription is fully managed, and invoices and charge attempts are created automatically based on the cron expression defined in recurring_interval.
  • If RaiseNow does not act as the payment initiation or reconciliation agent, RaiseNow does not generate invoices, charge attempts, or payments. The subscription is flagged as charged_by: "external".

• Referenced payments (Swiss QR Bill)
  RaiseNow generates invoices, charge attempts, and payments when the payment is processed, not based on the cron expression defined in recurring_interval. The subscription is flagged as charged_by: "external".

info

Currently, pain.008 file download and CAMT file upload are only supported via the API. Please contact your account manager if you are interested in this option. These features are only available to clients on the RaiseNow Growth price plan.

API documentation

From a technical perspective, the payment agreement is a new object, similar to payments and subscriptions in RaiseNow. Clients can access endpoints and subscribe to events as usual.

• Documentation of available endpoints
• Documentation of available events

Integration approach

Partners and customers can choose to subscribe to events or poll the API directly. Please refer to this section for more information on both approaches.

For recurring payment agreements, both a payment agreement and a subscription are created. The subscription acts as the payment schedule for the agreement and, if RaiseNow manages payment initiation and reconciliation, also serves as the container for invoices and charge attempts.

Integrations that do not account for this relationship may create duplicate objects in downstream systems. We therefore recommend adding an appropriate filter to the event subscription.

For example:

• Your integration listens to raisenow.payments.payment_agreement.created and raisenow.subscriptions.subscription.activated events.
• For one-off payment agreements, the raisenow.payments.payment_agreement.created event provides all required information to retrieve both direct debit and Swiss QR Bill payment agreements.
• To avoid duplicate notifications for recurring agreements, you can define a filter on raisenow.payments.payment_agreement.created using the created_subscription_uuid property, for example:
  (!event.pathExists("created_subscription_uuid", event.data)).
• When processing raisenow.subscriptions.subscription.activated events, an additional GET request may be required to retrieve information such as the ISR reference from the associated payment agreement using the payment_agreement_uuid property.

If you choose to poll the API, subscriptions and payment agreements can be matched using corresponding properties on the respective objects.

On the subscription object:

{
  "uuid": "cffa7d3c-f3a7-45f3-9ff7-7bc7b69e501e",
  "raisenow_parameters": {
    ...
    "payment_agreement_uuid": "23c427a5-8730-47ff-9e3a-be0ed33f8108"
  },
  ...
}

On the payment agreement object:

{
  "uuid": "23c427a5-8730-47ff-9e3a-be0ed33f8108",
  ...
  "created_subscription_uuid": "cffa7d3c-f3a7-45f3-9ff7-7bc7b69e501e"
}

These properties are also included in emitted events and can be used for filtering within your integration logic.