Giving for Web 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.

You can accept donations for fixed amounts, or allow the shopper to round up their transaction amount as a donation.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement	Description
Integration type	Make sure that you have integrated with: Web Components v5.0.0 or later using the Advanced flow Checkout API v67 or later
Customer Area roles	Make sure that you have Donation campaigns manager role.
Webhooks	Subscribe to the following webhook(s): Standard webhooks Adyen Giving merchant webhook
Setup steps	Before you begin: Check if your Customer Area user has the required roles, go to your Customer Area > Settings > Users. If you need additional roles, contact your admin user. Set up components integrations for the payment methods that you want to support. Create and activate a donation campaign.

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.
Depending on the donation type of the campaign, you present the option to donate by either:
- Show the shopper a donation form with fixed amounts.
- Show the shopper a round-up checkbox that suggests to round up their payment amount as a donation.
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.

Get details of your active donation campaigns

If the shopper's payment is authorized, and the /payments or /payments/details (for iDEAL payments) response includes the donationToken field, get the details of your active donation campaigns.

From your server, make a POST /donationCampaigns request, specifying:

Field name	Required	Description
`merchantAccount`		Your merchant account name.
`currency`		The three-character ISO currency code.
`locale`		The language in which you want to receive the donation campaign details in the response. The default is configured by the nonprofit. Set it to the shopper's language and country code, for example, `en-US`.

Example POST /donationCampaigns request

 curl https://checkout-test.adyen.com/checkout/v71/donationCampaigns \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
   "currency":"EUR",
   "locale":"en-US"
}'

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

When you make a request to get your active donation campaigns, the response you receive depends on your donation type:

Example POST /donationCampaigns response for a fixed amount donation

 {
    "donationCampaigns": [
        {
            "id": "DONATION_CAMPAIGN_ID",
            "campaignName": "DONATION_CAMPAIGN_NAME",
            "donation": {
                "currency": "EUR",
                "donationType": "fixedAmounts",
                "values": [100, 200, 300]
            },
            "nonprofitName": "NONPROFIT_NAME",
            "causeName": "NONPROFIT_CAUSE",
            "nonprofitDescription": "NONPROFIT_DESCRIPTION.",
            "nonprofitUrl": "NONPROFIT_WEBSITE_URL",
            "logoUrl": "NONPROFIT_LOGO_URL",
            "bannerUrl": "NONPROFIT_BANNER_URL",
            "termsAndConditionsUrl": "NONPROFIT_TERMS_AND_CONDITIONS_URL"
        }
    ]
}

Show Giving in your payment form

To show the Giving Component in your payment form:

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


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

Use the values you received in the /donationCampaigns response to configure the Giving Component. The parameters you need to use depend on your Web Component version:

Parameter name	Required	Description
`donation.donationType`		Defines the donation type. Possible values: - roundup - fixedAmounts
`donation.currency`		The three-character ISO currency code.
`donation.maxRoundupAmount`	Round-up donations	The maximum amount a transaction can be rounded up to make a donation.
`donation.values`	Fixed amount donations	The object containing suggested donation amounts.
`commercialTxAmount`	Round-up donations	The original transaction amount for the shopper's order, excluding the donation amount. The component uses this value to calculate the round-up donation amount.
`nonprofitName`		The name of the nonprofit.
`nonprofitDescription`		The description of the nonprofit.
`nonprofitUrl`		The website URL of the nonprofit.
`logoUrl`		The URL for the nonprofit logo.
`bannerUrl`		The URL for the banner for the campaign.
`termsAndConditionsUrl`		The URL for the terms and conditions page 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`.
`causeName`		The cause 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.

Example Giving Component configuration for a fixed amount donation

 // 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 `/donations` 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 donationCampaign = {
     campaignName: "CAMPAIGN_NAME",
     donation: {
          currency: "EUR",
          donationType: "fixedAmounts",
          values: [100, 200, 300]
     },
     nonprofitName: "NONPROFIT_NAME",
     causeName: "CAUSE_NAME",
     nonprofitDescription: "NONPROFIT_DESCRIPTION",
     nonprofitUrl: "NONPROFIT_WEBSITE_URL",
     logoUrl: "NONPROFIT_LOGO_URL",
     bannerUrl: "NONPROFIT_BANNER_URL",
     termsAndConditionsUrl: "NONPROFIT_TERMS_AND_CONDITIONS_URL"
};
 
const donationConfig = {
     ...donationCampaign,
     showCancelButton: true,
     onDonate: handleOnDonate,
     onCancel: handleOnCancel
};

If you didn't persist a previous instance of the AdyenCheckout object, create a new checkout object.
Create a new AdyenCheckout object
Expand view
Copy link to code block
Copy code
Copy code
const checkout= await AdyenCheckout( { clientKey, environment: "test", } );
Use the checkout.create method to create and mount an instance of the Giving Component.
Create and mount the Giving Component
Expand view
Copy link to code block
Copy code
Copy code
const donation = new Donation(checkout, 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.
Pass the state.data to your server.

Make a donation

From your server, make a donation request, using the same payment method as the original transaction.

Make a POST /donations request, specifying 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, or /payments/details 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.

Example POST /donations request

 curl https://checkout-test.adyen.com/checkout/v71/donations \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
    "amount": {
        "currency": "EUR",
        "value": 500
    },
    "donationCampaignId": "DONATION_CAMPAIGN_ID",
    "paymentMethod": {
        "type": "scheme"
    },
    "donationOriginalPspReference": "ORIGINAL_PAYMENT_PSP_REFERENCE",
    "donationToken": "DONATION_TOKEN",
    "reference": "YOUR_DONATION_REFERENCE"
    "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

The response contains:

id: a unique resource identifier.
status: the status of the donation. Possible values: completed, pending, or refused.
payment: object that contains the result code, and the pspReference for the donation transaction.
The request body.

Get the donation outcome

You get the donation outcome of each donation in a webhook. To receive these webhooks, enable the Adyen Giving merchant webhook, which includes eventCode: DONATION.

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

Successful donation webhook event

 {
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "additionalData": {
          "originalMerchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
        },
        "amount": {
          "currency": "EUR",
          "value": 500
        },
        "originalReference": "V4HZ4RBFJGXXGN82",
        "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"
      }
    }
  ]
}

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.

	const checkout= await AdyenCheckout(
	{
	clientKey,
	environment: "test",
	}
	);