Giving Campaign Manager Component

Add Giving Campaign Manager to an existing Components integration.

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

Built a Components integration.

Before starting your Giving integration:

Enable and integrate a supported payment method.
Set up the Adyen Giving merchant webhook in your Customer Area.
Contact Adyen to create a donation campaign for you.
After we create the campaign, you can start, edit, and end the campaign from your Customer Area.

How it works

After a shopper completes their payment for the original transaction with a payment method that supports donations:

From your server, make a /donationCampaigns request to get the details of your active donation campaigns.
Show Giving in your payment form.
From your server, make a /donations request to make a donation.
Get the outcome from a webhook.

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

Step 1: Get details of your active donation campaigns

Before you get the details of your active donation campaigns, and show the option to donate, the shopper must make a payment with a payment method that supports donations.

If the payment is authorized, and the /payments or /payments/details (for iDeal payments) response includes the donationToken field, make a POST request to /donationCampaigns to get the details of your active donation campaigns.

In your request, specify:

Field name	Required	Description
`merchantAccount`		Your merchant account name.
`currency`		The three-character ISO currency code.

The response contains the details of your active donation campaign(s). If there is at least one campaign in the response, show Giving in your payment form.

Step 2: Show Giving in your payment form

After you have received the /donationCampaigns response, including at least one donation campaign, show the Giving component in your payment form.

Create a DOM element for Giving, placing it where you want the form to be rendered:
```
<div id='donation-container'></div>
```

Configure the Giving Component. The parameters you need to use depend on your Web Component version.

When configuring the component, you need to use the values you received in the /donationCampaigns response for some of the parameters.

Parameter name	Required	Description
`amounts`		Object containing suggested donation amounts.
`bannerUrl`		The URL for the banner for the campaign.
`logoUrl`		The URL for the nonprofit logo.
`nonprofitDescription`		The description of the nonprofit.
`nonprofitName`		The name of the nonprofit.
`nonprofitUrl`		The website URL of the nonprofit.
`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`.
`termsAndConditionsUrl`		The URL for the terms and conditions page of the nonprofit.
`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.
`causeName`		The cause of the nonprofit.

If you didn't persist a previous instance of the AdyenCheckout object, create a new checkout object.
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.
Pass the state.data to your server.

Step 3: Make a donation

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

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

From your server, make a POST request to /donations, using the same payment method as the original transaction. Specify the following fields:

Field name	Required	Description
amount		The `currency` and `value` of the donation.
`donationCampaignId`		The unique campaign ID from the `/donationCampaigns` response `id` field.
paymentMethod		For cards, `type`: scheme. For iDeal, `type`: sepadirectdebit.
donationOriginalPspReference		The PSP reference of the original payment.
donationToken		For cards, the `donationToken` from the /payments response. For iDeal, the `donationToken` from the /payments/details response.
reference		The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement. If you need to provide multiple references for a transaction, separate them with hyphens ("-"). Maximum length: 80 characters.
merchantAccount		The merchant account identifier, with which you want to process the transaction.

Step 4: 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.