Payment Agreements

What are payment agreements?

In the context of RaiseNow, a payment agreement is understood 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 pledges (non-binding) as well as contractual obligations, such as membership fees. Enforcement of payment agreements is the responsibility of the payee and 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?

Longtime RaiseNow customers may be used to seeing "pledges" in the legacy RaiseNow Manager as transactions with some extra properties, but this approach treats two things that are actually quite different as the same thing — an agreement and its corresponding payment. This causes a number of problems. For example, a successfully submitted payment agreement will not count towards the total revenue as pledges on RaiseNow Manager used to. Only when an actual payment is registered will revenue be shown, just as it would be for any other payment.

Additional problems arise from handling one-off and recurring "pledges" in the same object. This causes a number of challenges for third-party integrations, which have to deal with an inconsistent data model.

By modeling payment agreements as a dedicated object, payments can now be reconciled with payment agreements, allowing for a cleaner presentation of various 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 now have no direct impact on transactions unless they are confirmed. This provides a more accurate representation of funds actually received.

API documentation

Technically, the payment agreement is a new object similar to payments and subscriptions in RaiseNow, and clients can subscribe to events as usual.

• Documentation of available endpoints.
• Documentation of available events.

Method of payment and payment agency

Payments for a given payment agreement may either be initiated 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 implies 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 in 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 is the payee.

Payment agreements are predominantly intended for use when RaiseNow is not the payment initiation agent. However, use cases exist where this distinction is blurred.

Example: A donor commits to a recurring payment agreement using Swiss QR as the selected method of payment. At a later point in time, they change their method of payment for the payment agreement to credit card. The payment initiation agent has changed 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 have a corresponding flag:

charged_by: "external"

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

Payment agreements with Swiss QR bill

tip

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

With the introduction of payment agreements, a new payment method also becomes available in RaiseNow Hub: ch_qr_reference. If a payment agreement is created with that payment method, RaiseNow will automatically generate a Swiss QR bill in the form of a PDF document, and the payment agreement will be created with a reference property. To retrieve that PDF, two URLs are provided:

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

The protected client-side access will require the user to answer a gate question with information previously submitted on the donation form: firstName, lastName, postalCode. Providing correct values will generate the direct access token link to download the PDF.

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

sha512(paymentUuid,firstName,lastName,postalCode)

Required creditor information

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

• 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 in order for RaiseNow to generate ISR numbers. RaiseNow will enforce uniqueness on configurations for a given account to avoid generation of duplicate reference numbers for that account.

• Prefix for the reference number: All generated reference numbers will start with this value.
• Running variable range minimum value & running variable range maximum value: Reference numbers will be generated in the range resulting from this definition, starting with the minimum value.

info

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

Recurring payment agreements

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

• It avoids duplicate modeling of payment schedules. This is intended to reduce implementation effort on the side of consumers of the API.
• Donors can update the payment method for a subscription belonging to a payment agreement via Tamaro, as they would for any other recurring payment.

Reconciling payments and payment agreements

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

For one-off payment agreements, the payment will automatically reference that payment agreement and update its status to fulfilled.

For a recurring payment agreement, incoming payments will be associated with the corresponding subscription.

• For direct debit:

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

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

info

Currently, pain.008 file download and CAMT file upload is only supported via API. Reach out to your account manager if you are interested in this option. Please note that these options are only available for clients with a RaiseNow Growth price plan.