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.