Default icon

Giving Component

Add Giving to an existing Components integration.

Try it out!

      API Explorer
  Postman collection

Implementation examples
  Java Spring

Our Giving Component shows the Giving donation form to the shopper after finishing their original payment.

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

The Giving Component is only available for the Advanced flow integration.

This page assumes you have already:

Before starting your Giving integration:

  1. Enable and integrate a supported payment method.
  2. Enable Giving in your test Customer Area.
  3. Set up the Adyen Giving merchant webhook in your Customer Area.

How it works

The following diagram shows the Giving flow after the shopper pays for their original transaction.

Step 1: 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>

  1. Configure the Giving Component with the following parameters:

    Parameter name Required Description
    amounts -white_check_mark- Object containing suggested donation amounts.
    backgroundUrl -white_check_mark- Background image that appears in the donation form.
    Required aspect ratio: 2:3:1. More guidelines and recommendations.
    description -white_check_mark- Description of your chosen nonprofit.
    logoUrl -white_check_mark- Logo of your chosen nonprofit.
    name -white_check_mark- The name of your chosen nonprofit.
    onDonate -white_check_mark- 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 nonprofit. If passed, the Component renders a link to your chosen nonprofit.
    disclaimerMessage - message: This is the message you want to show your shoppers.
    - linkText: The text you want to show for your link.
    - link: The URL for your Terms and Conditions.

  2. If you didn't persist a previous instance of the AdyenCheckout object, create a new checkout object.

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

    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.

Step 2: 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 to either:
    • Use the same payment method as the original transaction. Include the unique donation token that you get after a payment.
    • Use a stored payment method, for example, the shopper's stored card details for subscription payments.

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

Field name Required Description
paymentMethod -white_check_mark- For cards, type: scheme.
For iDeal, type: sepadirectdebit.
amount -white_check_mark- The currency and value of the donation.
donationAccount -white_check_mark- The Adyen account name of your nonprofit.
For testing, use MyCharity_Giving_TEST.
For accepting live donations, use the account name that we give you after choosing your nonprofit.
donationOriginalPspReference -white_check_mark- The PSP reference of the original payment.
donationToken -white_check_mark- For cards, the donationToken from the /payments response.
For iDeal, the donationToken from the /payments/details response.
amount -white_check_mark- The currency and value of the donation.

Step 3: Get the donation outcome

To get the outcome of each donation asynchronously, enable the Adyen Giving merchant webhook. The webhook includes eventCode: DONATION.

For a successful donation, the event contains success: true.

Use the originalReference to associate the donation to the shopper's original transaction.

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

Test and go live

Before going live with your integration, use our test cards to test your integration.

See also