Giving Component

Add Giving to an existing Components integration.

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:

Enable and integrate a supported payment method.
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.
Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments or /payments/details response.
Set up the webhook for Giving in your Customer Area.

To make a donation for with stored payment details for recurring payments, for example, if the shopper pays for your subscription-based service, follow the instructions on the API-only integration page.

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:

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 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.
`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.


//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,
    disclaimerMessage: {
       message: "By donating you agree to the linkText",
       linkText: "terms and conditions",
       link: "https://www.yourcompany.com/terms-and-conditions"
    }
};

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.
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.

If state.isValid is true, collect the state.data and pass this to your server.
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"
}'

https://docs.adyen.com/online-payments/donations/donation-at-purchase/web-component#-donations-request-with-a-donation-token

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.
recurringProcessingModel		The type of the recurring payment.

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"
}'

Step 3: Get the donation outcome

You get the outcome of each donation asynchronously, in a webhook event with eventCode: DONATION.

For a successful payment, the event 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"
      }
    }
  ]
}

https://docs.adyen.com/online-payments/donations/donation-at-purchase/web-component#successful-donation-webhook-event

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

To test your Giving integration:

Contact either your Adyen Account Manager or our Support Team and ask them to set up your account for Giving.
Make a /donations request using the donationAccount MyCharity_Giving_TEST. For live payments, use the donationAccount of the charity you chose.
Verify that your test donations are successful when you receive webhook events with the eventCode: DONATION.

Are you looking for test card numbers?

Would you like to contact support?