Giving Component

Our Giving Component renders the Giving feature in your payment form. You can show this to the shopper, after their payment has been completed, to let them donate to a charity.

If the shopper chooses to make a donation, the donation transaction uses same payment method that the shopper used to make the original payment.

Before you begin

This page assumes you've already:

• Built a Components integration.

Before starting your Giving integration:

1. Enable and integrate a supported payment method.
2. If you chose a charity that isn't one our one of our pre-approved charities, confirm that they completed the Giving onboarding process by contacting your Adyen Account Manager or our Support Team.
3. Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments or /payments/details response.
4. Set up the notification webhook for Giving in your Customer Area.

Show Giving in your payment form

Before you show the option to donate, the shopper must make a payment with a payment method that supports donations. If their payment is successful, show the Giving Component in your payment form:

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

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

2. Configure the Giving Component with the following parameters:

   Parameter name	Required	Description
   amounts		Object containing suggested donation amounts.
   backgroundUrl		Background image that appears 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 declines to donate. In the example below, we use handleOnCancel.
   showCancelButton		By default, the Component shows a Not now button. Your shopper can select this button to decline to donate. Set to false to remove this button.
   url		The URL of the charity. If passed, the Component renders a link to your chosen charity.

   
   //Implement the event handlers.
   
   function handleOnDonate(state, component) {
       state.isValid // True or false. Specifies if 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.
   }
   
   //Create the configuration object.
   
   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 calls the onDonate event. If state.isValid is true, collect the values passed in state.data which contains the donation amount that the shopper selected.

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 /donations request with either:
   • a unique donation token that you get after a payment.
   • a tokenized payment method, for example, the shopper's stored card details for subscription payments.

Make a donation request with a unique donation token

From your server, make a POST request to /donations specifying:

Field name	Required	Description
donationToken		For cards, the donationToken from the /payments response. For iDeal, the donationToken from the /payments/details response.
paymentMethod		For cards, type: scheme. For iDeal, type: sepadirectdebit.
amount		The currency and value of the donation.
donationOriginalPspReference		The PSP reference of the payment.
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 choosing your charity
shopperInteraction		ContAuth.

curl https://checkout-test.adyen.com/v69/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"
}'

Make a donation request with a tokenized payment method

From your server, make a POST request to /donations specifying:

Field name	Required	Description
paymentMethod.storedPaymentMethodId		Your reference for the shopper's stored payment method.
amount		The currency and value of the donation.
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 choosing your charity
shopperInteraction		ContAuth.

curl https://checkout-test.adyen.com/v69/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",
      "storedPaymentMethodId":"8415718415172200"
   },
   "returnUrl":"https://your-company.com/...",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "donationAccount":"{hint:Use this for testing donations.}MyCharity_Giving_TEST{/hint}",
   "shopperInteraction":"ContAuth",
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID",
   "recurringProcessingModel":"CardOnFile"
}'

Get the donation outcome

You get the outcome of each donation asynchronously, in a webhook with eventCode: DONATION.
For a successful payment, the notification contains success: true.

{
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "amount": {
          "currency": "EUR",
          "value": 500
        },
        "eventCode": "DONATION",
        "eventDate": "2022-07-07T13:18:13+02:00",
        "merchantAccountCode": "CHARITY_DONATION_ACCOUNT",
        "merchantReference": "YOUR_DONATION_REFERENCE",
        "paymentMethod": "visa",
        "pspReference": "Z58FGTKBRCQ2WN27",
        "reason": "033899:1111:03/2030",
        "success": "true"
      }
    }
  ]
}

For cards, you can show the shopper if their donation is successful after you get the webhook. For iDeal, you get the notification webhook a day or more later. You can send the outcome to the shopper using email or mobile messaging.

Test and go live

To test 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. For live payments, use the donationAccount of the charity you chose.
3. Verify that your test donations are successful when you receive notification webhooks with the eventCode: DONATION.

See also