Giving Component

Our Giving Component renders the Giving feature 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 Giving to your existing Web Components integration. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your 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 Giving.
3. Ensure the Giving onboarding process has been completed. You can confirm by contacting your Adyen Account Manager or our Support Team.
4. Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments response.

Show Giving in your payment form

Before presenting your shopper with the option to donate, you 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 Giving Component in your payment form. This will ask your shopper whether they want to make a donation.

The /payments response also contains a donationToken that is required if the shopper chooses to donate.

To present the Giving Component:

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

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

2. Create an instance of the 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 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 /donations, specifying:

   • amount: The currency and value of the donation. The example is for a donation of 10 EUR.
   • donationToken: The donationToken from the /payments response of the payment.
   • donationOriginalPspReference: The PSP reference of the payment. For example, V4HZ4RBFJGXXGN82.
   • donationAccount: The Adyen account name of your charity. For testing, use MyCharity_Giving_TEST. For accepting live donations, change this to the account name that we give you after onboarding your charity.
   /donations request

   curl https://checkout-test.adyen.com/v68/donations \
   -H "x-API-key: YOUR_X-API-KEY" \
   -H "content-type: application/json" \
   -d '{
     "amount":{
       "currency":"EUR",
       "value":1000
     },
     "reference":"YOUR_DONATION_REFERENCE",
     "paymentMethod":{
       "type":"scheme"
     },
     "donationToken":"YOUR_DONATION_TOKEN",
     "donationOriginalPspReference":"V4HZ4RBFJGXXGN82",
     "donationAccount":"{hint:Use this for testing donations.}MyCharity_Giving_TEST{/hint}",
     "returnUrl":"https://your-company.com/...",
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "shopperInteraction":"ContAuth"
   }'

   https://docs.adyen.com/pt/pt/online-payments/donations/web-component#-donations-request

   The /donations response contains:

   • additionalData.merchantReference: Echoes the reference you provided in the /donations request.
   • pspReference: Adyen's unique reference for the donation.
   • resultCode: The result of the donation.
   /donations response

   {
    "id":"UNIQUE_RESOURCE_ID",
    "status":"completed",
    "donationAccount":"MyCharity_Giving_TEST",
    "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
    "amount":{
       "currency":"EUR",
       "value":1000
    },
    "reference":"YOUR_DONATION_REFERENCE",
    "payment":{
       "pspReference":"FKSPNCQ8HXSKGK82",
       "resultCode":"Authorised",
       "amount":{
          "currency":"EUR",
          "value":1000
       },
       "merchantReference":"YOUR_DONATION_REFERENCE"
    }
   }

   https://docs.adyen.com/pt/pt/online-payments/donations/web-component#-donations-response

Present the donation result

If the donation is successfully received, you receive an Authorised resultCode. 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

To test for your Giving integration:

1. Contact either your Adyen Account Manager or our Support Team and ask them to set up your account for Giving.
2. Make a /donations request using the donationAccount MyCharity_Giving_TEST.

See also