Are you looking for test card numbers?

Would you like to contact support?

Default icon

Giving Component

Add Giving to an existing Components integration.

Our Giving Component renders the Giving feature in your payment form. You can present this to your shopper after a payment has been completed, to give them the option to make a donation to a charity of your choice.

If your shopper chooses to make a donation, this is charged to the same payment method they used to make the payment.

Before you begin

This page explains how to add Giving to your existing Web Components integration. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your Giving integration:

  1. Make sure that you have set up your back end implementation and created an instance of AdyenCheckout.
  2. Enable and integrate a payment method that supports Giving.
  3. Ensure the Giving onboarding process has been completed. You can confirm by contacting your Adyen Account Manager or our Support Team.
  4. Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments response.

Show Giving in your payment form

Before presenting your shopper with the option to donate, you need to make a payment with a payment method that supports donations. If this payment is successful (the payment result is either Authorised, Received, or Pending Received), present the Giving Component in your payment form. This will ask your shopper whether they want to make a donation.

The /payments response also contains a donationToken that is required if the shopper chooses to donate.

To present the Giving Component:

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

    <div id='donation-container'></div>
  1. Create an instance of the Giving Component with the following parameters:

    Parameter name Required Description
    amounts -white_check_mark- Object containing suggested donations.
    backgroundUrl -white_check_mark- Background image that will appear in the Component.
    description -white_check_mark- Description of your chosen charity.
    logoUrl -white_check_mark- Logo of your chosen charity.
    name -white_check_mark- The name of your chosen charity.
    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 selects that they do not want to donate. In the example below, we use handleOnCancel.
    showCancelButton By default, the Component shows a Not now button. Your shopper can click this button if they choose not to donate. Provide showCancelButton, set to false, to remove this button.
    url The URL of the charity. If passed, the Component renders a link to your chosen charity.
    function handleOnDonate(state, component) {
        state.isValid // True or false. Specifies whether 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.
    }
    
    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
    };
  2. 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 will call the onDonate event. If state.isValid is true, collect the values passed in state.data. These specify the amount that the shopper selected, that you will use to make the donation.

  3. 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 POST request to /donations, specifying:

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

    The /donations response contains:

    • additionalData.merchantReference: Echoes the reference you provided in the /donations request.
    • pspReference: Adyen's unique reference for the donation.
    • resultCode: The result of the donation.
    /donations response
    {
     "id":"UNIQUE_RESOURCE_ID",
     "status":"completed",
     "donationAccount":"MyCharity_Giving_TEST",
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "amount":{
        "currency":"EUR",
        "value":1000
     },
     "reference":"YOUR_DONATION_REFERENCE",
     "payment":{
        "pspReference":"FKSPNCQ8HXSKGK82",
        "resultCode":"Authorised",
        "amount":{
           "currency":"EUR",
           "value":1000
        },
        "merchantReference":"YOUR_DONATION_REFERENCE"
     }
    }

Present the donation result

If the donation is successfully received, you receive an Authorised resultCode. Present the shopper with a message thanking them for their donation.

You could do this by either presenting a confirmation message in your payment form, or by using component.setStatus to render the message Thanks for your support! in the Component:

component.setStatus("success");

Test and go live

To test for 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.

See also