Understand RPI API Limitations
When working with RPIs via the API, Donorfy acts as a record-keeping and processing system only.
Donorfy does not create mandates or payment instructions with payment gateways.
You must store any gateway IDs, tokens, or references returned by the payment processor.
Gateway references should be stored in CollectionReference1 to CollectionReference5 on the RPI.
Add or Update a Recurring Payment Instruction
When creating or updating an RPI, certain properties are mandatory and must match values in your Donorfy settings.
Required Properties
You must provide all of the following:
Product – Must be a valid Product in settings.
Campaign – Must be a valid Campaign in settings.
Fund – Must be a valid Fund in settings.
CollectionMethod – One of the built-in methods such as GoCardless, Stripe, Standing Order, or a custom method you created.
RecurringPaymentInstructionType – RecurringDonation or Membership.
StartOption – OnOrAfter or NextCollectionDay.
EndOption – OpenEnded or NoPaymentsAfter.
PaymentFrequency – HalfYear, Month, Quarter, or Year.
CollectionReference1–5 – At least one reference must be supplied.
If a required option is not supplied, Donorfy applies default values where supported.
Configure Start and End Options
Start and end rules control when payments begin and stop.
Start Options
Use OnOrAfter and provide a StartDate.
Use NextCollectionDay to start automatically on the next cycle.
If no StartOption is provided, NextCollectionDay is used.
End Options
Use OpenEnded for ongoing payments.
Use NoPaymentsAfter and provide an EndDate.
If no EndOption is provided, OpenEnded is used.
Set Optional RPI Properties
You can include additional properties to control behaviour and reporting.
DateAdded to backdate historic instructions.
Channel, Currency, Department, BankAccount, or Acknowledgement, if valid in settings.
CollectionDay, using a value from 1 to 31.
StartMonth, using numbers where January equals 1.
Configure Gift Aid on RPIs
Gift Aid options can be applied when adding an RPI.
Set CanRecoverTax to true to enable Gift Aid eligibility.
Set AddGiftAidDeclaration to true to create a declaration if one does not already exist.
Optionally set GiftAidDeclarationMethod, otherwise Web is used.
Gift Aid declarations are only added if the constituent does not already have one.
Link RPIs to Constituents
You can associate an RPI with a new or existing constituent.
Provide ExistingConstituentId to link to an existing constituent.
Omit ExistingConstituentId to create a new constituent automatically.
You can also specify a connected constituent or beneficiary when adding the RPI.
Perform Operations on Existing RPIs
Several actions are available for managing RPIs after creation.
Upgrade an RPI
Upgrading adds a new payment and allocation.
Call the Upgrade endpoint for the RPI.
Confirm the upgrade is applied successfully.
Change RPI Status
You can control the lifecycle of an RPI.
Use Pause to temporarily stop collections.
Use Cancel to end the RPI permanently.
Use Activate to restart a paused RPI.
Record Successful Payments
If payments are collected outside Donorfy, you can record them manually.
Call the PaymentCollected endpoint for the RPI.
Provide the Month, Year, and Amount collected.
Optional fields include:
ProcessingCosts charged by the gateway.
CollectionDate, otherwise the current date is used.
Reference and TransactionId from the payment gateway.
The TransactionId is the gateway reference, not a Donorfy transaction ID.
Understand Successful Payment Processing
When a successful payment is recorded, Donorfy processes it automatically.
An expected payment is created if none exists.
Existing expected or failed payments are reused.
A payment report is created and shown on the RPI History tab.
Overnight reconciliation adds a transaction to the constituent timeline.
Payments already marked as collected cannot be collected again.
Record Failed Payments
You can also record failed payment attempts.
Call the PaymentFailed endpoint for the RPI.
Provide the Month and Year of the failed payment.
Optionally include a Failure Reason.
Donorfy then:
Creates an expected payment if one does not exist.
Marks the payment as failed.
Adds an activity to the constituent timeline.
Evaluates whether the RPI should be lapsed overnight.
⚠️Important:The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.