Adding and Updating Recurring Payment Instructions 

Important when you add an RPI via the API Donorfy does not lodge any details with your payment processor or gateway - e.g. Stripe, GoCardless and so on - if you need to lodge details you must do that separately following the process required by the payment processor or gateway.

You can pass any ids or tokens etc returned by the payment processor or gateway to the API and store them in the collection references of the RPI.

When adding or updating Recurring Payment Instructions (RPIs) some properties of a RPI must contain values that exist in your Donorfy settings or be chosen from a list of allowed values as follows:

• To link a new RPI to a new or existing constituent - see 'Linking new Entities to a New or an Existing Constituent' in this article

• You must pass in

  • Product - e.g. Donation  - i.e. a valid Product in your settings
  • Campaign - e.g. General Campaign - must be a valid campaign in your Donorfy 
  • Fund - e.g. General - i.e. a valid Fund in your settings
  • CollectionMethod can be either 
    • One of the built-in types i.e. 'GoCardless', 'Stripe' or 'Standing Order', or 
    • A collection method you have defined
  • RecurringPaymentInstructionType can be either 'RecurringDonation' or 'Membership' - if not specified then 'RecurringDonation' will be used 
  • StartOption
    • can be one of 'OnOrAfter' or 'NextCollectionDay'
    • if you specify OnOrAfter you must also provide a StartDate 
    • if a StartOption is not provided 'NextCollectionDay' will be used
  • EndOption
    • can be one of 'OpenEnded' or 'NoPaymentsAfter' 
    • if you specifyNoPaymentsAfter you must also provide a EndDate
    • if an EndOption is not provided 'OpenEnded' will be used
  • PaymentFrequency must be one of  'HalfYear', 'Month', 'Quarter' or 'Year' - if a payment frequency is not provided Month will be used
  • CollectionReferences 1 to 5 are the account numbers, references or codes needed by a payment gateway to process the payment - you should provide at least one of these

• Optionally you can pass in 
  • DateAdded - by default the date added will be set to the current system date - if you are adding old instructions you can pass a date added which will be used instead - this means the RPI will appear in the correct place chronologically in the timeline
  • Channel - if specified must be in the list of Channels in your settings
  • Currency - if specified must be in the list of Currencies in your settings
  • Department - if specified must be in the list of Departments in your settings
  • BankAccount - if specified must be in the list of Bank Accounts in your settings
  • Acknowledgement - if specified must be in the list of Acknowledgements in your settings
  • CollectionDay - is the day in the month when the payment will be collected - this must be a number in the range 1 to 31 - if not specified 1 will be used
  • StartMonth - is the number of the month when the RPI will start - i.e. January is 1 and so on - if not specified then the month after the current month will be use
  • Gift Aid - when adding a RPI the following properties are available
    • CanRecoverTax - if set to true - then tax may be reclaimed against the transaction - provided all the other conditions for gift aid are met
    • AddGiftAidDeclaration - if set to true a new gift aid declaration will be added for a new or existing constituent  - as long as the constituent does not already have a declaration 
    • GiftAidDeclarationMethod - if you are adding a gift aid declaration then you can specify the declaration method in this property - if you leave this empty a method of 'Web' will be used

Connected Constituents & Beneficiaries 

When adding a RPI you can specific the constituent id of a connected constituent or beneficiary.

Operations on Existing RPIs

• Upgrading an RPI allows you to add a new payment and allocation perform the upgrade by calling https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/Upgrade
• To change the status of an RPI use the following methods
  • https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/Pause
  • https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/Cancel
  • https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/Activate

Handling Payments

If you are collecting payments for RPIs outside of Donorfy you can pass details of the payments as follows.

Successful Payments can be passed into the API via the  PaymentCollected endpoint - i.e. https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/PaymentCollected. You must pass in the 

• Month and year the payment is for - month is a number, 1 for January etc
• Amount of the payment 

Optionally you can pass in 

• ProcessingCosts - e.g. the fee deducted by a payment gateway for collecting the payment
• Date payment was collected - if you leave this blank the current system date will be used
• Reference & Transaction Id - these are stored in the payment report - note that the Transaction Id is the id allocated by the payment gateway which is collecting the funds - it is not a Donorfy Transaction Id 

The payment will handled via the Donorfy payment processing workflow as follows

• If an expected payment does not exist for the RPI for the month & year it will be added
• If an expected payment does exist its status must be 'Expected' or 'Failed' - i.e. the payment must not have been previously collected - otherwise, the PaymentCollected call will fail
• If the payment has been previously marked as 'Failed' its status will be changed to 'Expected' so the collection can be processed
• A payment report will created using the values you pass in
• The expected payment and payment report will be shown on History tab of the RPI
• The overnight payment reconciliation process will verify the data and add a transaction to the constituent's timeline 

Failed Payments - If a payment fails you can pass details of failed payments into the API via the  PaymentFailed endpoint - i.e. https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/PaymentFailed. You must pass in the 

• Month and year the failed payment is for - month is a number 1 for January etc
• Optionally a reason for the failure - e.g. account closed

The payment will handled via the Donorfy payment processing workflow as follows

• If an expected payment does not exist for the RPI for the month & year it will be added
• If an expected payment does exist its status must be 'Expected' - i.e. the payment must not have been previously collected - otherwise the call will fail
• The expected payment will be set to failed and an activity will be added to the constituent's timeline
• The overnight status update process will determine whether the RPI should be lapsed - for more information see this

The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.