To integrate with Blackbaud Checkout, include the bbCheckout.2.0.js script on your page just before the closing </body> tag.

<script src='https://payments.blackbaud.com/Checkout/bbCheckout.2.0.js'></script>
  

<script src='https://payments.blackbaud.com/Checkout/bbCheckout.2.0.js'></script>

Then create a JSON object that contains your transaction parameters, including the Blackbaud Payment Service account's public key and merchant account ID. The public key is a unique ID that identifies the organization communicating with Blackbaud Secure Payments. The merchant account ID identifies the account to use to process the payment. For information about how to retrieve these keys, see the Public key and Payment configuration list endpoints.

var transactionData = {
    'key': 'cf3cd5cc-43ef-4f89-9170-03c4fc55be61',
    'payment_configuration_id': 'f086c1c9-5512-4386-a9a4-ecc6fe755f64',
    'amount': 10.00
};
  

var transactionData = {
    'key': 'cf3cd5cc-43ef-4f89-9170-03c4fc55be61',
    'payment_configuration_id': 'f086c1c9-5512-4386-a9a4-ecc6fe755f64',
    'amount': 10.00
};

To open the payment form, call the corresponding payment method by passing in your transaction configuration object.

Blackbaud_OpenPaymentForm(transactionData); // credit card transaction
  

Blackbaud_OpenPaymentForm(transactionData); // credit card transaction

Checkout also accepts additional optional configurations. For information about all parameters, see transaction parameters.

The following transaction types are currently supported by Blackbaud Checkout:

• Card not present payment
• Card present payment
• Direct debit payment
• Store card info
• Update card info
• Store direct debit info
• Update direct debit info

To trigger the form submission on a page that uses a <form> element, just add the data-formtype="bbCheckout" attribute to the <form> element:

    <form action="/" method="post" data-formtype="bbCheckout"></form>
  

<form action="/" method="post" data-formtype="bbCheckout"></form>

By default, Blackbaud Checkout does not auto-submit forms without this attribute.

After you configure the client form and invoke the payment method, the Checkout form appears. If Checkout encounters an error, it triggers a checkoutError event that contains an error message and numeric code.

The calling application can handle errors by subscribing to the checkoutError event and parsing the response parameters.

document.addEventListener('checkoutError', function (event) {
    console.log('errorText: ', event.detail.errorText);
    console.log('errorCode: ', event.detail.errorCode);
});
  

document.addEventListener('checkoutError', function (event) {
    console.log('errorText: ', event.detail.errorText);
    console.log('errorCode: ', event.detail.errorCode);
});

The Blackbaud Checkout process can trigger the following events.

Sample usage:

document.addEventListener('checkoutComplete', function (event) {
    console.log('Token: ', event.detail.transactionToken);
});
  

document.addEventListener('checkoutComplete', function (event) {
    console.log('Token: ', event.detail.transactionToken);
});

After donors complete transactions on the Blackbaud Checkout payment page, a hidden input with the transaction token (named transactiontoken) is added to the bbCheckout form.

<input type="hidden" name="transactiontoken" value="34d65a59-4e5f-4913-ab18-03d33b874455" />
  

<input type="hidden" name="transactiontoken" value="34d65a59-4e5f-4913-ab18-03d33b874455" />

A custom event is also triggered indicating a successful transaction. This can be handled by subscribing to the checkoutComplete event.

document.addEventListener("checkoutComplete", function(event) {
    console.log('Token:', event.detail.transactionToken);
});
  

document.addEventListener("checkoutComplete", function(event) {
    console.log('Token:', event.detail.transactionToken);
});

If a <form> element with the data-formtype="bbCheckout" attribute is configured, the form is submitted.

After you receive the checkoutComplete event and have the token, the Checkout transaction endpoint should be called from a secure location such as a backend service that has access to an OAuth 2.0 access token. The Checkout transaction endpoint uses the transaction token to finalize the payment.

To stop Blackbaud Checkout from submitting the form, the data-disable-submit attribute on your bbCheckout form can be set to true. This disables the auto-submission of the form after the donor completes the transaction.

Blackbaud Checkout supports mobile devices through responsive design, but the underlying page that launches Checkout can affect its display. To ensure proper rendering, we recommend the following:

• Web pages that integrate with Blackbaud Checkout should include the appropriate meta tags for responsive design.

  Copy

          <meta name="viewport" content="width=device-width, initial-scale=1" />
        

  <meta name="viewport" content="width=device-width, initial-scale=1" />

• Web pages that integrate with Blackbaud Checkout should disable vertical scrolling when loading the payment form. This prevents additional scrollbars from being added to the UI and potentially confusing users.