Creating payments for constituents via API

You may be looking for the web/cart resources. You can use the "AddContribution" method to post a contribution to the cart, use the "ApplyCashPayment" or "AddOnAccount" depending on how you want it to be reflected in Tessitura, and then the "checkout" method to actually post the information onto a given account.

https://www.tessituranetwork.com/REST_v151/TessituraService/HELP/RESOURCES/CART.HTM

Thank you! Looking at these resources, I'm not seeing anywhere for me to provide a constituent id to apply the payment to... 

You don't use the account ID in the call itself. The session authenticates, using the account's username and password, and the account is accessed that way. In other words, the API knows which account based on the username supplied, not an account number supplied.

If you're trying to import contributions in bulk using only Tessitura account ID you'll want to check out the Contribution Import Utility.

If this is going to be a web process where an application is making a payment inside Tessitura then as far as I know username/password authentication will be needed to add it to an existing account.

Cliff Bailey said:

You don't use the account ID in the call itself. The session authenticates, using the account's username and password, and the account is accessed that way. In other words, the API knows which account based on the username supplied, not an account number supplied.

Thanks for clarifying that. I'd only implied it in my comment about authenticating the session.

Sorry about the confusion. I'm not talking about the Account Id.  I'm trying to associate a payment record and have it show up on a CONSTITUENT record.  So I need to create a contribution record in Tessitura and have it show up on the constituent record so that we know that this constituent gave us $X on Y date.

When I'm saying account ID I mean the ID associated with a constituent record.

There is no API call to simply associate payments with a bulk of constituent records. You have to use the API to actually make the financial transaction for each account. Each constituent record would need to be authenticated via username and password before those kinds of transactions can happen via the API.

You can't just tie a payment to a constituent record. It has to be *for* something. An order or contribution for example.

If you want to put a bulk of payments/contributions into Tessitura you'll probably want to use the contribution import utility.

I see. So each constituent record has a username/password that I have to login as via the api (i.e. create a session with), and then add to their cart etc?  I understand the payment has to be for something, and in this case they would all be contributions they made.  I didn't realize each constituent has a username/password... This is a bit bizarre to me that I would have to login as a constituent to add a contribution to that constituent's record via the API.  So basically we can't really import contributions into Tessitura via the API, because we will never know each constituent's credentials.  Does that sound right?

Hi Tunc,

That sounds right based on what I've seen; hopefully this sort of thing will be addressed in a future release. This is one reason why we use a stored procedure to import contributions from Stripe.

Thanks,
David

Each record doesn't necessarily have a username and password, but that's how the API allows for taking payments for them. So if they didn't have one, it would need to be created.

But yeah, in the end the API isn't meant for bulk importing of financial transactions. They've got a contribution import utility and order import utility for that.

The API is more for supporting normal website functionality. There aren't a lot of reasons for bulk importing of contributions for the average website.

This is good to know.  We sell memberships for our retail store out of Shopify POS and are looking at starting a project to create a constituent in Tessitura and pass the contribution/payment info via the API.  Sounds like we might have to look into that username and password to make it work...

Since the user's password won't be available to you, there are other methods of authenticating a session that only require an email or username. Endpoints like

https://www.tessituranetwork.com/REST_v151/TessituraService/HELP/API/POST_WEB_SESSION_SESSIONKEY_L_4.HTM

and

https://www.tessituranetwork.com/REST_v151/TessituraService/HELP/API/POST_WEB_SESSION_SESSIONKEY_L_7.HTM

might be helpful. I know with the Guest Checkout endpoint, you can check the constituent Id on the session after authenticating. If a user under that email does not exist, the ConstituentId on the session will be 0.

Following that, another consideration is if the patrons that made these donations event exist in Tessitura when you're importing them. If not, you'll probably need to create accounts for them using the registration endpoint. To me it seems unlikely that the scenario mentioned in the OP would be such a happy path that everyone who's made contributions in some system that is not Tessitura, would exist in Tessitura.

Still, I'm not even certain going through a scripted "purchase path" using the WEB API to import data is the way to go about this. I'm not familiar with it, the import utilities mentioned earlier seem like the way to go. That, or a custom SQL process in Tessitura.

It really all just depends on what you're trying to do. If you're looking to create the contributions in Tessitura on the fly as they come in, the API is the way to go. If you're just worried about importing the data in bulk and you're not necessarily concerned about it being available immediately then setting up an import process is the way to go. 

You can even set up a job to scan a network/FTP location and look for new files to import automatically. So rather than have the API do anything you can set up your application to create a data file, move it to an FTP location, and then let SQL Server/Tessitura take over from there.

It just depends on the needs and how soon you need Tessitura to be updated with the transactions.

It really all just depends on what you're trying to do. If you're looking to create the contributions in Tessitura on the fly as they come in, the API is the way to go. If you're just worried about importing the data in bulk and you're not necessarily concerned about it being available immediately then setting up an import process is the way to go. 

You can even set up a job to scan a network/FTP location and look for new files to import automatically. So rather than have the API do anything you can set up your application to create a data file, move it to an FTP location, and then let SQL Server/Tessitura take over from there.

It just depends on the needs and how soon you need Tessitura to be updated with the transactions.

It's not so much that the transactions have to be realtime or near time synced, but that we would like to not have to do a manual process of using a utility to get the donations synced.  We would like to just have a batch job that syncs the donors and donations over to Tessitura via the API.

Gotcha. Unfortunately I don't think that really exists for the API out of the box but the link that Joe sent is probably good to look at. You might be able to log accounts in using those methods and then automate the checkout process one at a time. 

Alternately, you can take steps to automate the import utility but it would not be via the API. Specifically you could write something to get the data you need, generate a text/data file, upload it to an FTP location, and then have the Tessitura import utility run on a schedule. Theoretically that should make it handsfree albeit a bit low-tech. 

You can also write your own custom API call that you could potentially accomplish what you need with that. You could pass whatever parameters you wanted if you set something up yourself. 

Tunc Samiloglu -- I'm not entirely certain I've caught up 100% on the problem you're trying to solve, but I built a MobileCause integration while working at Arsht Center that imported donations from a 3rd-party in a way that sounds very much like what you're trying to do.  You do not need to log a Constituent into a Session if you create a Business Facing Session using `POST` to `Web/Session/BusinessFacing`.  You can set the Constituent ID of the Business Facing Session using `PUT` to `Web/Session/{sessionKey}/Constituents`.

I'm trying to get access back to the Postman queries that detail the process I used to integrate MobileCause for Arsht Center.  But Business Facing Sessions was my go to for things like this.

Pinging Cliff Bailey and Joe Begly -- just to close the loop on your comments, this functionality absolutely does exist out-of-the-box via the REST API.  It's just Business Facing Sessions and not the normal Sessions a lot of web integrators are used to using for Constituents who are expected to login or register an account.

I will look into this!  what you did sounds exactly like what we're trying to do.  Thank you!

That's really cool! I've actually never used that endpoint since most of the "bulk/import" stuff we've done is always in SQL. Great to know though, thanks for exposing me to that functionality.

I completely forgot about the BusinessFacing session. Very helpful. I'd be interested in seeing the resources you used for the MobileCause integration if you're able to find that. Thanks!

You bet, David Frederick!  Here's the basic outline from memory:

1. Create or Identify Batch
   • Identify if batch already exists: POST to Finance/BatchMaintenance/Active
   • Create batch if one doesn't exist: POST to Finance/BatchMaintenance
2. Create Business Facing Session
   • POST to Web/Session/BusinessFacing
   • You will need a batch, mode of sale, and source no. for the SessionInfo object.  I opted to reproduce the way in which Tessitura creates or uses a daily batch for website transactions/orders, but with a different Batch Type.
3. Attempt to Find Constituent
   • GET to CRM/Constituent/Search
   • If none found, create Constituent using POST to CRM/Constituents/Snapshot
4. We stored the 3rd-party Constituent ID in an Attribute at this point
5. Set Constituent ID of the Business Facing Session
   • PUT to Web/Session/{sessionKey}/Constituents
6.  Add Contribution
   • POST to Web/Cart/{sessionKey}/Contributions
7. We set a CSI to capture additional form data related to the Contribution
8. Checkout
   • POST to Web/Cart/{sessionKey}/Checkout
     • "Authorize": false
     • "AuthorizationCode": "{externalPaymentID}"

I'll post the Postman docs if I'm able.

Thanks a lot, Daniel! I had no idea that existed.