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:
- Make sure that you have set up your back end implementation and created an instance of
AdyenCheckout
. - Enable and integrate a payment method that supports Giving.
- Ensure the Giving onboarding process has been completed. You can confirm 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 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:
-
Create a DOM element for Giving, placing it where you want the form to be rendered:
<div id='donation-container'></div>
-
Create an instance of the Giving Component with the following parameters:
Parameter name Required Description amounts
Object containing suggested donations. backgroundUrl
Background image that will appear 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 usehandleOnDonate
.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 usehandleOnCancel
.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 };
-
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. Ifstate.isValid
is true, collect the values passed instate.data
. These specify the amount that the shopper selected, that you will use to make the donation. - 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.
- If
state.isValid
is true, collect thestate.data
and pass this to your server. -
From your server, make a POST request to /donations, specifying:
- amount: The
currency
andvalue
of the donation. The example is for a donation of 10 EUR. - donationToken: The
donationToken
from the /payments response of the payment. - donationOriginalPspReference: The PSP reference of the payment. For example, V4HZ4RBFJGXXGN82.
- 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 onboarding your charity.
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 thereference
you provided in the/donations
request.pspReference
: Adyen's unique reference for the donation.resultCode
: The result of the donation.
{ "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" } }
- amount: The
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:
- 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 thedonationAccount
MyCharity_Giving_TEST.