Help creating a BBIS ADF *NOT* on a BBIS Page

Question

I've been working on trying to create a gift form that doesn't live on a BBIS page.  For now, I'm testing this on my BBIS Server but in a normal HTML file and I have it mostly working.

The example on the BB web site is pretty awful, and uses AngularJS which is a pretty worthless example at this point.  It also isn't even remotely "complete" as there's no code in the example for actually submitting and completing a donation.

I feel like I'm pretty close to making this work I think.

https://give.unc.edu/custom/home/donate.html?p=unre&f=000001&a=15.00

This form is in test mode so you can go all the way through it.

Basically, it successfully validates the donation, but then fails to call /WebApi/Payment/Create with a 401 error "Unauthorized"

Now when I use my regular donation form the URL for that c all is exactly the same, and basically the payload is the same as well.

The ADF API Technical Reference doesn't mention the Payment/Create end point (or any Payment/* endpoint, really), so I don't know what the 401 error means.

Just not sure what I'm missing here.

David Seager · Answer

Thank you @Rick Root for your feedback.

I wanted to let you know that I’m currently working with both our Product and Documentation teams to review and update the existing Advanced Donation Form (ADF) guidance so that it more accurately reflects what is currently supported within BBIS.

We recognize that the “complete” standalone example can create some confusion around what is fully supported in external vs. embedded scenarios, and we’re taking steps to clarify that in the documentation.

In the meantime, I’ll continue to keep you updated on any changes or clarifications that come out of that effort. I appreciate your patience and for bringing this to our attention, it’s exactly the kind of feedback that helps us improve the experience for everyone.

Rick Root · Answer

@David Seager …. thank you.  I'm a bit confused by the wording for the example on the blackbaud web site, I guess.

This last example is meant to show a more realistic real-world example of the Advanced Donation Form API, including all the necessary error handling and styling. This example also incorporates the use of the CountryService, which is the javascript wrapper for the Country REST API endpoint.

Whereas all the other examples are designed to be inserted into an Advanced Donation Form Part, the complete example is designed to be completely standalone - even on a different server than the one serving your BBIS website.

Please note you'll need to update the references in the example below to your BBIS installation.

Your suggested options would basically have nothing to do with the Advanced Donation Form API.

Furthermore, the DonationService has an option to pass in { crossdomain: true } when instantiating the service which would seem to imply that it was intended to work the way I'm expecting.

If there is no ADF functionality that can be embedded on an external web site that interacts with the ADF API, then that example should be removed.

David Seager · Answer

Hi @Rick Root

I took a look at what you’re trying to do with running an Advanced Donation Form outside of a BBIS page, and the behavior you’re seeing is expected. The 401 error on /WebApi/Payment/Create is occurring because that endpoint requires a valid authenticated BBIS session and server-side security context (cookies, request validation tokens, etc.). When the form is hosted outside of BBIS, that context isn’t present, so the request is rejected, even if the payload itself looks correct.

From a security standpoint, attempting to call internal BBIS endpoints outside of their intended context can also raise concerns. Blackbaud policy requires access to systems only within their intended and authorized use, and specifically prohibits attempts to bypass or circumvent authentication and security controls. Because this approach tries to operate outside the normal BBIS execution model, it could be considered a potential violation of the Acceptable Use Policy.

If the goal is to build a standalone donation form, the supported path is to:

* Use the Blackbaud Payments API for payment processing
* Use the Blackbaud CRM APIs to create and manage the gift

This approach is designed for external form experiences and avoids the dependency on BBIS page/session context.