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

Rick Root
Rick Root
Tenth Anniversary Kudos 2 Name Dropper Participant
in Blackbaud CRM Developer Discussions

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.

Answers

  • Emily Root
    Emily Root
    Kudos 1 Facilitator 1

    It looks like the issue is the x-token header on the call. On the failing Create request it's the same value as the tokenId in the donate.html page's script with checkoutData. Loading the page in a few fresh incognito sessions returns that same token every time. These tokens are normally generated fresh per session/page load, so a static one won't line up with the current session and the request gets rejected at auth (which is why you see the 401 with an empty body). You'll have to get a working session ID for it to go through.

  • Rick Root
    Rick Root
    Tenth Anniversary Kudos 2 Name Dropper Participant

    Thanks! That led me down the right path. I had copied the "var checkout" line that the ADF creates when the part is embedded on a BBIS page, and that included the token. I also tried randomly generating a token but that didn't work either. It seems that the ADF creates the token and puts it in the BBWEBAUTHENTICATIONTOKEN table, and the /WebAPI/Payment/Create expects the X-Token header to match that.

    I can't find any legit way to generate the token though.

    I thought maybe the /DonationEditor/{partId} would do the trick because it returns much of the same data, but it returns the data with different field names than defined in the CheckoutModel, and doesn't include the APIControllerName (which I know to be "Payment"), and doesn't include, most importantly, the TokenId.

    So, to get it working, here's what I did:

    Before loading my regular custom online giving javascript, I'm using a syncrhonous ajax call to retrieve the content of the actual BBIS Donation Form, which causes it to generate the token, and then I strip out the value it sets for checkoutdata using a regular expression and then put that into the checkoutdata variable.

    This seems to work reasonably well and the synchronous call is pretty fast, but it's a hack.

    The example documentation provides no information on how to do this, even though the example is intended to work on non-BBIS pages.

  • David Seager
    David Seager Blackbaud Employee
    Tenth Anniversary Kudos 1 Name Dropper Facilitator 1

    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.

  • Rick Root
    Rick Root
    Tenth Anniversary Kudos 2 Name Dropper Participant

    @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.

Categories