This article provides information about working with Transactions via the API
Adding Transactions
Important when you add a transaction via the API Donorfy does not collect the payment via your payment processor or gateway - e.g. Stripe, GoCardless and so on - you must do that separately following the process required by the payment processor or gateway.
A transaction in Donorfy will have one payment and one or more allocations - when you add a transaction you are adding a payment and one associated allocation - if a transaction needs multiple allocations you should proceed as follows, suppose the payment was for £20 and you need two allocations for £15 and £5 - you should
Add a new transaction for £15 - using the product for the £15 allocation
Add the £5 allocation with a call to the AddAllocation method for your transaction
Note if you are adding payments for money collected for a Recurring Payment Instructions you should use the RPI PaymentCollected endpoint - i.e. https://data.donorfy.com/api/v1/<your api key>/rpis/<id>/PaymentCollected - see this for more information.
Mandatory and Optional Look Up Properties
When adding or updating a transaction some properties of a transaction must contain values that exist in your Donorfy settings as follows:
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
PaymentMethod - e.g. Cash - i.e. a valid Payment Method in your settings
Fund - e.g. General - i.e. a valid Fund in your settings
Optionally you can pass in
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
If AddGiftAidDeclaration is true then GiftAidDeclarationMethod must be in the list of Gift Aid Declaration Methods in your settings
Constituent Information
When you add a transaction you can
Add a new constituent at the same time as the transaction, or
Assign the transaction to an existing constituent, or
Make the transaction anonymous by using a guid containing all zeros - i.e. 00000000-0000-0000-0000-000000000000 - as the ExistingConstituentId
See 'Linking new Entities to a New or an Existing Constituent' in this article for more information
Gift Aid
When adding a transaction 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
GiftAidClaimed - means this transaction has already had the gift aid tax claimed against it - Donorfy will not claim the tax
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
Updating
To update a transaction you must pass in the Id associated with the payment element of the transaction.
The update method can only be used to change amounts of transactions that have one allocation - if a transaction has multiple allocations is should be adjusted by calling allocation methods associated with the transaction.
Connected Constituents & Beneficiaries
When adding or update a transaction you can specific the constituent id of a connected constituent or beneficiary.
To clear a connected constituent or beneficiary you should pass in a guid containing all zeros - i.e. 00000000-0000-0000-0000-000000000000.
Deleting Transactions
To delete a transaction you must pass in the Id associated with the payment element of the transaction - the payment transaction and its associated allocations will be deleted.
The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.