# How to Configure Adyen Giving for Donation Processing in Salesforce Commerce Cloud

> Configure Adyen Giving for donation processing in Salesforce Commerce Cloud. Learn to set up custom preferences, charity details, and donation tokens to enable seamless giving.

- Repository: [Adyen/adyen-salesforce-commerce-cloud](https://github.com/adyen/adyen-salesforce-commerce-cloud)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Enable Adyen Giving by setting the `AdyenGiving_enabled` custom preference to `true` in Business Manager, configure charity details and donation amounts, and ensure the order payment instrument contains a valid `Adyen_donationToken` to trigger the donation UI on the order confirmation page.**

Adyen Giving integrates charitable donations directly into the checkout flow of your Salesforce Commerce Cloud (SFCC) storefront. To configure Adyen Giving for donation processing, you must enable custom preferences in Business Manager and ensure the server-side and client-side components are properly synchronized. This guide walks through the complete implementation based on the `adyen/adyen-salesforce-commerce-cloud` repository.

## Enable Adyen Giving in Business Manager

Start by configuring the custom preferences that control the feature availability and charity details.

### Required Custom Preferences

Set the following preferences in Business Manager under **Merchant Tools > Site Preferences > Custom Preferences**:

- **`AdyenGiving_enabled`**: Set to `true` to activate the feature.
- **`AdyenGiving_donationAmounts`**: Comma-separated values (e.g., `10,20,30`) defining selectable donation amounts.

These values are retrieved via `getCustomPreference` in [`src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenConfigs.js):

```javascript
// adyenConfigs.js
getAdyenGivingEnabled() {
    return getCustomPreference('AdyenGiving_enabled');
},
getAdyenGivingDonationAmounts() {
    return getCustomPreference('AdyenGiving_donationAmounts');
},

```

### Charity Configuration Settings

Configure the nonprofit organization details using these preferences:

- **`AdyenGiving_charityAccount`**: Your Adyen charity account ID
- **`AdyenGiving_charityName`**: Display name of the nonprofit
- **`AdyenGiving_charityDescription`**: Short description shown to shoppers
- **`AdyenGiving_charityUrl`**: Link to the nonprofit's website
- **`AdyenGiving_backgroundUrl`**: Optional background image URL
- **`AdyenGiving_logoUrl`**: Optional charity logo URL

## Server-Side Implementation

The server-side logic determines when to display the donation option and prepares the campaign data.

### Checking Donation Availability

In [`src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenHelper.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenHelper.js), the `isAdyenGivingAvailable` function validates whether the donation flow should trigger:

```javascript
// adyenHelper.js
isAdyenGivingAvailable(order) {
    if (!order) return false;
    const paymentInstrument = order.getPaymentInstruments(
        adyenHelperObj.getOrderMainPaymentInstrumentType(order)
    )[0];
    return AdyenConfigs.getAdyenGivingEnabled() &&
           !!paymentInstrument.paymentTransaction.custom.Adyen_donationToken;
},

```

This returns `true` only when the feature is enabled and the order's payment instrument contains a valid `Adyen_donationToken` custom attribute (added during the payment response).

### Preparing Campaign Data for the View

The order confirmation middleware in [`src/cartridges/int_adyen_SFRA/cartridge/controllers/middlewares/order/confirm.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/controllers/middlewares/order/confirm.js) checks availability and injects donation data:

```javascript
// confirm.js
if (AdyenHelper.isAdyenGivingAvailable(order)) {
    handleAdyenGiving(req, res);
}

function handleAdyenGiving(req, res) {
    const clientKey = AdyenConfigs.getAdyenClientKey();
    const environment = AdyenHelper.getCheckoutEnvironment();
    const campaign = adyenGiving.getActiveCampaigns().donationCampaigns[0];
    
    const viewData = res.getViewData();
    viewData.adyen = {
        clientKey,
        environment,
        adyenGivingAvailable: true,
        donationProperties: JSON.stringify(campaign.donation),
        nonprofitName: encodeURI(campaign.nonprofitName),
        nonprofitDescription: encodeURI(campaign.nonprofitDescription),
        nonprofitUrl: campaign.nonprofitUrl,
        logoUrl: campaign.logoUrl,
        bannerUrl: campaign.bannerUrl,
        termsAndConditionsUrl: campaign.termsAndConditionsUrl,
        orderToken: getOrderToken(req),
    };
    res.setViewData(viewData);
}

```

## Client-Side Component Rendering

The front-end script in [`src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/giving/adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/giving/adyenGiving.js) mounts the donation UI.

### Initializing the Donation UI

The component reads configuration injected into `window.givingConfig` and creates the Adyen donation component:

```javascript
// client/adyen/giving/adyenGiving.js
const donationConfig = {
    donation: getDonationProperties(),
    nonprofitName: decodeURI(nonprofitName),
    nonprofitDescription: decodeURI(nonprofitDescription),
    nonprofitUrl,
    logoUrl,
    bannerUrl,
    termsAndConditionsUrl,
    showCancelButton: true,
    onDonate: handleOnDonate,
    onCancel: handleOnCancel,
    ...(isRoundupDonation(getDonationProperties()) && {
        commercialTxAmount: orderTotal,
    }),
};

async function initializeGivingComponent() {
    checkout = await window.AdyenWeb.AdyenCheckout(store.checkoutConfiguration);
    adyenGivingComponent = window.AdyenWeb.createComponent(
        'donation',
        checkout,
        donationConfig,
    );
    adyenGivingComponent.mount(adyenGivingNode);
}

```

### Handling Donation Selection

When the shopper clicks **Donate**, the `handleOnDonate` function posts the selection to the server:

```javascript
async function handleOnDonate(state, component) {
    const donationData = {
        csrf_token: window.givingConfig.csrfToken,
        donationReference: window.givingConfig.orderReference,
        donationAmount: state.data.amount,
    };
    
    const response = await httpClient({
        method: 'POST',
        url: window.donateURL,
        data: donationData,
    });
    
    if (response.status === 'success') {
        component.setStatus('success');
    }
}

```

## Processing the Donation Request

The server-side endpoint receives the POST request in [`src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/donations/adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/donations/adyenGiving.js). The `donate` function validates the order, builds the Adyen Giving request, and executes the API call:

```javascript
// server/adyen/scripts/donations/adyenGiving.js
function donate(donationReference, donationAmount, orderToken) {
    const order = OrderMgr.getOrder(donationReference, orderToken);
    const paymentInstrument = order.getPaymentInstruments(
        AdyenHelper.getOrderMainPaymentInstrumentType(order)
    )[0];
    
    // Build request object with merchantAccount, donationCampaignId, amount
    const requestObject = {
        merchantAccount: AdyenConfigs.getAdyenMerchantAccount(),
        donationCampaignId: paymentInstrument.paymentTransaction.custom.Adyen_donationCampaignId,
        donationOriginalPspReference: paymentInstrument.paymentTransaction.custom.Adyen_pspReference,
        amount: donationAmount,
    };
    
    const response = AdyenHelper.executeCall(
        constants.SERVICE.ADYENGIVING,
        requestObject,
    );
    
    Transaction.wrap(() => {
        order.custom.Adyen_donationAmount = JSON.stringify(donationAmount);
        if (response.status === constants.DONATION_RESULT.COMPLETED) {
            paymentInstrument.paymentTransaction.custom.Adyen_donationToken = null;
        }
    });
    
    return response;
}

```

## Summary

- **Enable the feature** by setting `AdyenGiving_enabled` to `true` and configuring charity details in Business Manager custom preferences.
- **Validate availability** on the order confirmation page using `AdyenHelper.isAdyenGivingAvailable()`, which checks for the `Adyen_donationToken` on the payment instrument.
- **Inject campaign data** via the [`confirm.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/confirm.js) middleware to expose configuration to the front-end through `window.givingConfig`.
- **Render the UI** using the client-side [`adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenGiving.js) script that mounts the Adyen Web Components donation component.
- **Process donations** through the server-side `donate()` function in [`adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenGiving.js), which calls the Adyen Giving API and stores the result on the order.

## Frequently Asked Questions

### What custom preferences are required to enable Adyen Giving?

You must set `AdyenGiving_enabled` to `true` and define `AdyenGiving_donationAmounts` with comma-separated values. Additionally, configure `AdyenGiving_charityAccount`, `AdyenGiving_charityName`, `AdyenGiving_charityDescription`, and `AdyenGiving_charityUrl` to display the nonprofit details to shoppers. All preferences are accessed via [`adyenConfigs.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenConfigs.js).

### Why is the donation component not appearing on the order confirmation page?

The component only renders if `AdyenHelper.isAdyenGivingAvailable(order)` returns `true`. This requires both the `AdyenGiving_enabled` preference to be `true` and the order's payment instrument to contain a valid `Adyen_donationToken` custom attribute. Verify that the payment response successfully populated this token and that the feature is enabled in Business Manager.

### How does the integration handle round-up donations?

When the campaign type is `roundup`, the client-side script in [`adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenGiving.js) passes the original order total as `commercialTxAmount` in the donation configuration. The Adyen Web Components donation component uses this value to calculate the difference between the order total and the next whole number, presenting that amount as the suggested donation to the shopper.

### Where is the donation amount stored after a successful donation?

After the server-side `donate()` function in [`adyenGiving.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenGiving.js) receives a successful response from the Adyen Giving API, it stores the donation amount in the order's custom attribute `Adyen_donationAmount` as a JSON string. Additionally, if the donation status is `COMPLETED`, the `Adyen_donationToken` on the payment instrument is cleared to prevent duplicate donations.