Adyen Giving Component

Our Adyen Giving Component renders Adyen Giving in your payment form. You can present this to your shopper after a payment has been completed, to give them the option to make a donation to a charity of your choice.

If your shopper chooses to make a donation, this is charged to the same payment method they used to make the payment.

Before you begin

This page explains how to add Adyen Giving to your existing Web Components integration. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your Adyen Giving integration:

1. Make sure that you have set up your back end implementation, and created an instance of AdyenCheckout.
2. Enable and integrate a payment method that supports Adyen Giving.
3. Ensure the onboarding process Adyen Giving has been completed. You can confirm by contacting either your Adyen Account Manager or our Support Team.

Show Adyen Giving in your payment form

Before giving your shopper the option to donate, you will need to make a payment with a payment method that supports donations. If this payment is successful (the payment result is either Authorised, Received, or Pending Received), present the Adyen Giving Component in your payment form. This will ask your shopper whether they want to make a donation.

To present the Adyen Giving Component:

1. Create a DOM element for Adyen Giving, placing it where you want the form to be rendered:

   <div id='donation-container'></div>

2. Create an instance of the Adyen Giving Component with the following parameters:

   Parameter name	Required	Description
   amounts		Object containing suggested donations.
   backgroundUrl		Background image that will appear in the Component.
   description		Description of your chosen charity.
   logoUrl		Logo of your chosen charity.
   name		The name of your chosen charity.
   onDonate		Create an event handler for onDonate. This is called when the shopper selects the amount they want to donate. In the example below, we use handleOnDonate.
   onCancel		Create an event handler for onCancel. This is called when the shopper selects that they do not want to donate. In the example below, we use handleOnCancel.
   showCancelButton		By default, the Component shows a Not now button. Your shopper can click this button if they choose not to donate. Provide showCancelButton, set to false, to remove this button.
   url		The URL of the charity. If passed, the Component renders a link to your chosen charity.

   function handleOnDonate(state, component) {
       state.isValid // True or false. Specifies whether the shopper has selected a donation amount.
       state.data // Provides the data that you need to pass in the `/donate` call.
       component // Provides the active component instance that called this event.
   }
   
   function handleOnCancel(state, component) {
       // Show a message, unmount the component, or redirect to another page.
   }
   
   const donationConfig = {
       amounts: {
           currency: "EUR",
           values: [300, 500, 1000]
       },
       backgroundUrl: "https://example.org/background.png",
       description: "The Charitable Foundation is...",
       logoUrl: "https://example.org/logo.png",
       name: "The Charitable Foundation",
       url: "https://example.org",
       showCancelButton: true,
       onDonate: handleOnDonate,
       onCancel: handleOnCancel
   };

3. Use the checkout.create method to create and mount an instance of the Adyen Giving Component.

   const donation = checkout.create('donation', donationConfig).mount('#donation-container');

   When the shopper selects a donation amount, the Component will call the onDonate event. If state.isValid is true, collect the values passed in state.data. These specify the amount that the shopper selected, that you will use to make the donation.

4. Pass the state.data to your server.

Make a donation

When the shopper chooses to donate, the Component calls the onDonate event, which contains a state.data object.

1. If state.isValid is true, collect the state.data and pass this to your server.

2. From your server, make a POST request to /donate , specifying:

   • donationAccount: The Adyen account name of your charity. We will provide you with this account name once your chosen charity has been onboarded.
   • reference: Your unique reference for this donation.
   • modificationAmount: The state.data.amount from the onDonate event from your front end.
   • originalReference: The PSP reference of the payment.

   The example below is for a donation of 5 EUR, made after a payment that the PSP reference 991559660454805J.

   {
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "donationAccount":"CHARITY_ACCOUNT",
     "reference":"YOUR_DONATION_REFERENCE",
     "modificationAmount":{
       "currency":"EUR",
       "value":500
     },
     "{hint:The pspReference of the payment}originalReference{/hint}":"991559660454805J"
   }

   The /donate response contains:

   • additionalData.merchantReference: Echoes the reference you provided in the /donate request.
   • pspReference: Adyen's unique reference for the donation.
   • response: [donation-received]
   https://docs.adyen.com/online-payments/donate/web-component#-donate-response

   /donate response

   {
       "additionalData":{
           "merchantReference":"YOUR_DONATION_REFERENCE"
       },
       "pspReference":"852561121120573B",
       "response":"[donation-received]"
   }

Present the donation result

If the donation is successfully received (the response is [donation-received]), present the shopper with a message thanking them for their donation.

You could do this by either presenting a confirmation message in your payment form, or by using component.setStatus to render the message Thanks for your support! in the Component:

component.setStatus("success");

Test and go live

When you onboard with Adyen Giving, we create a test charity account that you can use for testing purposes. You will get a separate Customer Area login for this account and a corresponding donationAccount.

To test whether your donation flow is working correctly:

1. Make a /donate request, providing the donationAccount of your test charity.

2. Log in to the Customer Area account for your test charity, and navigate to Transactions > Payments.

   If the donation is successful it appears in this transaction list.

When you are live with Adyen Giving, you can confirm whether your chosen charity is receiving donations by contacting either your Adyen Account Manager or our Support Team.

See also