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

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:

// 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, the isAdyenGivingAvailable function validates whether the donation flow should trigger:

// 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 checks availability and injects donation data:

// 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 mounts the donation UI.

Initializing the Donation UI

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

// 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:

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. The donate function validates the order, builds the Adyen Giving request, and executes the API call:

// 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 middleware to expose configuration to the front-end through window.givingConfig.
• Render the UI using the client-side adyenGiving.js script that mounts the Adyen Web Components donation component.
• Process donations through the server-side donate() function in 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.

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}