In eTapestry, there is a page for checking off required fields. Please be aware of what your organization's settings are and make certain to require those fields on your forms.
Find the list under
eTapestry>Management>Organization>Date Entry Rules
eTapestry now mandates the use of their Blackbaud Checkout (BB Checkout) interface to process payments. So, if you're still using eft and credit card fields in your forms, you need to switch to the BB Checkout field.
To use this field for accepting donations/gifts you must first enter your credentials, then add at least one BB Checkout field (listed under Pricing fields) to your forms. See Screenshot 1
- Go to your Forms>Settings>eTapestry Payment and Check Serial Key to make sure your active serial key is registered.
- On the Payment plugin settings, enter your credentials for the BB Checkout field. The instructions for finding those in your eTapestry account are in the field settings information. Until you have completed this step, the BB Checkout field will not appear in your form's Pricing fields.
- Open all your active forms that accept payments through Blackbaud and replace the existing credit card and eft/echeck fields with a BB Checkout field. NOTE: if your eft/cc fields were set to show conditionally, make a note of the conditions. You will need to apply those to the new BB Checkout field that replaces it. Each BB Checkout field has a field setting for specifying whether it is for eft or credit card. See Screenshot 2
- Re-establish any conditions under which the BB Checkout fields will show if applicable. (This was likely already set up if you had both credit cards and checks fields on your form so you just need to apply the same conditions to your BB Checkout field.) If you only accept one payment type, you only need one BB Checkout field.
add_filter('eTapPayment_bbcheckout_fields', function($fields, $form){
// can check form['id'] first if desired.
$fields['autosubmit'] = true;
return $fields;
}, 10, 2);
Screenshots:
Field settings in the BB Checkout field. Select the transaction type and if the field is required. If you have more than one BB Checkout field in your form, be sure to set a conditional to only show the correct field (usually based upon a Payment Method radio button selected by the user).
In order to use the Blackbaud Checkout PCI compliant SCA field, you need to enter special Blackbaud checkout credentials in your plugin settings.
Go to Forms>Settings>eTapestry Payment to enter the two credentials you need.
For more information regarding the Blackbaud Checkout process, go to the FAQ Blackbaud Checkout
BBPS Public Key: found on Management...My Organization...Preferences page (bottom of Preferences tile)
BBMS Merchant Account Id: found at Management...My Organization...eCommerce (see Merchant Account Id for the desired BBMS processor).
Once you've entered correct credentials, you will see the BB Checkout field in your form's Pricing Fields section. Add this to your form and follow the instructions in the field to designate it as credit card or check. You can add two BB Checkout fields to your form. Just use a radio button for the Payment Method and conditionally show the correct BB Checkout field based on the user's choice.
For more information regarding the Blackbaud Checkout process, go to the FAQ Blackbaud Checkout
If there is an X next to your credentials, they are incorrect.
If you are using the legacy login method by entering a user's login and password, the user may not have appropriate access to the account.
I recommend using the new login method of a database ID and API key.
The Database Id and API Key are visible to admin users within eTapestry. They can be found by visiting your eTapestry account and navigating to Management...My Organization...Subscriptions and looking within the API Subscription tile.
The following are examples of how to filter / modify the eTapestry Mapping gift transaction. Add the filter and function to your functions.php file.
The transaction is an array. To see the structure and possible values, view the Blackbaud API documentation HERE.
To add a note to the gift transaction:
add_filter('eTapMapping_gift_transaction', 'custom_filter_gift', 10, 2);
function custom_filter_gift( $transaction, $entry){
$my_field_no = '8'; // change to your field id number
if ( ! empty( $entry[ $my_field_no ] ) ){
$transaction['note'] = sanitize_text_field($entry[ $my_field_no ]);
}
return $transaction;
}
Modify a constituent or tribute user defined field created with a Gravity Forms date field to match the etapestry required date format mm/dd/yyyy
(You can also change your field from a date field to a text field with a Date input mask. This will match eTapestry's format requirement.)
add_filter('eTapMapping_defined_values', 'custom_filter_udfs', 10, 2);
function custom_filter_udfs( $defined_values, $entry ){
//var_dump( $defined_values );die(); // uncomment while testing to see array structure and get reference no
if ( ! empty( $defined_values ) ){
$reference_no = '3188.0.2675'; // hard code this to match your mapped account
foreach ( $defined_values as $k => $a ){
if ( $reference_no == $a['fieldRef'] ){
// This is our date field so format the date
$defined_values[$k]['value'] = date('m/d/Y', strtotime( $a['value'] ) );
break;
}
}
}
//var_dump($defined_values);die(); //uncomment to test to see if the array was properly changed (not for live sites!)
return $defined_values;
}
There are a couple of things to check if you are getting this error.
- Are your credentials correct? You should be able to log into your eTapestry account using the same username and password.
- Is the url correct?
- Have you asked for API access from eTapestry? eTapestry API access is not automatic. So make sure you have explicitly added it to your account
Please check your url in settings and make sure it corresponds to your version (2 or 3).
If you are using the eTapestry Plus plugin and get this email, you need to set the Defined Values field in Forms>Settings. Your options are listing in the info window.
NOTE The eTapestry Plus plugin was discontinued. Users need to upgrade to the eTapestry Mapping plugin.
Yes. However, you may need to modify the account object according to etapestry rules per country.
Here is an example of how to accommodate an address in the UK/Great Britain:
add_filter('eTapMapping_donor','my_modify_donor_fields',10,3); // for Mapping plugin
add_filter('eTapPayment_donor','my_modify_donor_fields',10,3); // for Payment plugin
/**
* Change state to county
* @param array $donor
* @param array $data
* @param array $feed
* @return array modified $donor
*/
function my_modify_donor_fields($donor,$data,$feed){
// change state to county
if (!empty($donor['state']) && $donor['country'] == 'GB'){ // your country code
$donor["county"] = $donor['state'] ;
unset($donor['state']);
}
return $donor;
}
Please visit
https://app.etapestry.com/hosted/files/api3/objects/Account.html
to see all country adaptations. Address field rules are at the bottom of the page.
Use the 'eTapPayment_donor' filter to modify the account array before it goes to eTapestry.
Here is an example that changes the address fields to accommodate etapestry Australia address parameters to use 'Suburb' instead of 'City' and also add salutations.
add_filter('eTapPayment_donor','my_donor_changes',10,3);
/**
* Add salutations
* @param array $donor
* @param array $data
* @param array $feed
* @return array modified donor
*/
function modify_donor_fields($donor,$data,$feed){
if (!empty($donor['city']) && $donor['country'] == 'AU'){
$donor["suburb"] = $donor['city'] ;
unset($donor['city']);
}
// salutations
$donor['shortSalutation'] = $donor["firstName"];
if (isset($donor['title'])){
$donor['longSalutation'] = $donor['title'].' '.$donor['lastName'];
$donor['envelopeSalutation'] = $donor['title'].' '.$donor["firstName"].' '.$donor["lastName"];
}
else {
$donor['longSalutation'] = $donor['firstName'].' '.$donor['lastName'];
$donor['envelopeSalutation'] = $donor["firstName"].' '.$donor["lastName"];
}
return $donor;
}
There is a hook for modifying a transaction before it is sent to eTapestry. The transaction is an array. To see the API structure visit the Blackbaud API documentation HERE.
For example, let's say you want to add a note to the Payment that would be attached to the gift. (A gift is created when a donation is made using the Payment plugin. If you wish to create another type of journal entry, you need to use the eTapestry Mapping plugin.)
Add a filter to your functions.php file in your theme (or even better, create a little plugin so your functionality is separated from your theme ):
add_filter('eTapPayment_transaction', 'custom_filter_gift', 10, 4);
function custom_filter_gift( $transaction, $feed, $data, $entry){
if ( $entry['form_id'] != "16" ) { // change to your form ID or remove this condition to apply to all your forms with an eTap Payment feed
return $transaction;
}
$my_field_no = "8"; // change to your field id number
if ( ! empty( $entry[ $my_field_no ] ) ){
$transaction['note'] = sanitize_text_field( $entry[$my_field_no] ); // choose appropriate filter for your field
}
return $transaction;
}
If you are using international addresses, you will need to filter your address fields. Please visit
https://www.blackbaudhq.com/files/etapestry/api3/objects/Account.html
to view the allowed address fields by country.
Filter example:
add_filter('eTapMapping_donor','my_modify_donor_fields',10,3); // for Mapping plugin
add_filter('eTapPayment_donor','my_modify_donor_fields',10,3); // for Payment plugin
/**
* Change city to suburb for AU residents
* @param array $donor
* @param array $data
* @param array $feed
* @return array modified $donor
*/
function my_modify_donor_fields($donor,$data,$feed){
// change city to suburb for AU
if (!empty($donor['city']) && $donor['country'] == 'AU'){
$donor["suburb"] = $donor['city'] ;
unset($donor['city']);
}
return $donor;
}
