--- title: "Online donations using Adyen Giving" description: "Enable your users to accept online donations from shoppers using Adyen Giving." url: "https://docs.adyen.com/platforms/online-payments/donations-online" source_url: "https://docs.adyen.com/platforms/online-payments/donations-online.md" canonical: "https://docs.adyen.com/platforms/online-payments/donations-online" last_modified: "2026-05-26T13:48:55+02:00" language: "en" --- # Online donations using Adyen Giving Enable your users to accept online donations from shoppers using Adyen Giving. [View source](/platforms/online-payments/donations-online.md) ##### Read more ![Giving logo](/user/pages/docs/05.platforms/27.online-payments/06.donations-online/giving.svg?decoding=auto\&fetchpriority=auto) Learn about Adyen Giving [on your payment terminals](/platforms/in-person-payments/donations-in-person). With Adyen Giving, your users can give shoppers the option to donate to a nonprofit organization when shoppers make an online purchase. To enable this, you set up donation campaigns for [account holder resources](/platforms/account-structure-resources#balance-platform-resources). When a campaign has been started and a shopper chooses to donate, the donation is processed as a separate transaction. Adyen covers all fees and the donation amount is transferred to the nonprofit in full. This means you can split amounts and fees on the original transaction, but not on the donation transaction. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | Adyen for Platforms with a platform model, with an [API only](/online-payments/donations/api-only) online payments integration using Checkout API v67 or later. | | **[Customer Area roles](/account/user-roles)** | Make sure that you have the following roles:- **Donation campaigns viewer**: to view donation campaigns and access campaign insights. - **Donation campaigns manager**: to create, start, edit, and end donation campaigns and access campaign insights. | | **[Webhooks](/development-resources/webhooks)** | Subscribe to the **[Adyen Giving merchant webhook](/development-resources/webhooks/webhook-types#other-webhooks)**. | | **Limitations** | Note the following limitations:- The maximum number of account holders that you can assign to a donation campaign is 400. - A store can only be part of one active campaign at the same time. - Make sure that you are using [supported payment methods](/platforms/donations#supported-payment-methods) and [supported regions and currencies](/platforms/donations#supported-currencies). | | **Setup steps** | Before you begin, make sure that the nonprofit you choose has been onboarded to Adyen, or pick one of our [pre-approved nonprofits](https://www.adyen.com/giving/nonprofit) that have already been onboarded. | ## How it works To enable your users to accept donations at checkout: 1. [Choose a nonprofit](/platforms/donations#nonprofit-organizations). 2. [Set up an account holder donation campaign](#set-up-a-donation-campaign) in your Customer Area, under **Giving** > **Campaigns**.\ You need to select: * The account holders that you want to make the campaign available to. * The nonprofit. * The stores and [donation settings](#donation-settings). 3. Make sure that your integration can show the active campaign in your checkout, and make a request for the amount that the shopper wants to donate. See [Online payments flow](#online-payments-flow). 4. Make sure you have a way to [show the nonprofit's terms and conditions](/online-payments/donations/terms-and-conditions). 5. To inform shoppers about their donation, make sure that you can process [Giving webhook messages](#giving-webhook). 6. Start the campaign from the **Campaigns** overview in your Customer Area. ## Donation settings With our Giving integration, you have the flexibility to choose a combination of donation type and donation moment. However, there are limitations to the supported choices, depending on [region and currency](/platforms/donations#supported-currencies) and [payment method](/platforms/donations#supported-payment-methods). ### Donation type In your [donation campaign](#set-up-a-donation-campaign) you can configure the following donation types: * **Fixed amounts**: up to three fixed amounts to present to shoppers when they make a payment. Your checkout should provide a selection mechanism, such as donation buttons for these amounts. * **Round up**: allow shoppers to donate by rounding up the transaction amount of their purchase. Your checkout should show a round-up checkbox. We recommend rounding up to the nearest whole amount. ### Donation moment Your integration can present the option to donate at different moments in your checkout flow: * **Pre-checkout**: the shopper can review the total transaction amount that includes the donation before completing their payment. * **Post-checkout**: the shopper can contribute to your donation campaign after completing their payment. This gives you flexibility to align Giving with your existing checkout process. ## Set up a donation campaign for account holders The Campaigns user interface in the Customer Area guides you through setting up a donation campaign, and shows example screens. The main steps to create an Adyen Giving donation campaign for your account holders are as follows: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Giving** > **Campaigns**. 2. Select **Create new campaign** > **For account holders**. 3. Add the account holders to the campaign, one by one or as a group: * One by one: select **Search accounts**, select your balance platform, and search by account holder ID or reference, legal entity ID or name, or email address. Then select **Add** in the tile of the individual account holder. * Group: select **Submit a list of accounts**, select your balance platform, enter a comma-separated list of account holder IDs, and select **Add**. The UI will inform you if an account holder has already been added or cannot be found on the selected balance platform. 4. Select the campaign details: * The nonprofit. * Either a specific cause, or "General fundraising". * The sales channel: online payments (ecommerce), in-person payments (point of sale), or both. 5. If you selected online payments, first select the stores that the campaign applies to.\ Then select the donation type. When you choose fixed amounts and enter the amounts in your default currency, we automatically add equivalent amounts in other currencies if necessary for the selected stores. 6. If you selected in-person payments, first select the stores that the campaign applies to.\ Then refer to [in-person donation settings](/platforms/in-person-payments/donations-in-person#donation-settings), and select: * The one-step or two-step interaction flow. * Timeouts for the donation prompt and the payment screen. * The text to show on the donation screen on the terminal: the name of the nonprofit or the cause you selected. * The donation type. When you choose fixed amounts and enter the amounts in your default currency, we automatically add equivalent amounts in other currencies if necessary for the selected stores. 7. Review the summary. When everything is correct, select **Create campaign**. The campaign is now set up, but not active yet. When you are ready to activate the campaign: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Giving** > **Campaigns**. 2. Find the tile for the campaign, and select **Start**. ## Online payments flow The donation flow depends on the [donation moment](/online-payments/donations#donation-moment): ### Tab: Pre-checkout donations When your shopper goes to the checkout page and proceeds to pay with a [payment method that supports donations](/online-payments/donations#supported-payment-methods): 1. From your server, make a [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) request to [get the details of your active donation campaigns](#get-details-of-donation-campaigns). 2. Depending on the [donation type](#donation-type) of the campaign, [present the option to donate](#present-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. 3. From your server, make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to make the payment for the original transaction. 4. After you get the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response, make a [/donations](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations) request to [make a donation](#make-a-donation). 5. [Get the outcome](#giving-webhook) from a webhook and show it to the shopper. The following diagram shows the donation flow for a round-up amount before the shopper pays for their original transaction: ![Flow diagram for pre-checkout donations](/user/pages/reuse/online-payments/donations/online-process/api-pre-flow.svg?decoding=auto\&fetchpriority=auto) ### Tab: Post-checkout donations When your shopper completes their payment with a [payment method that supports donations](/platforms/donations#supported-payment-methods) : 1. From your server, make a [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) request to [get the details of your active donation campaigns](#get-details-of-donation-campaigns). 2. Depending on the [donation type](/platforms/online-payments/donations-online#donation-type) of the campaign, [present the option to donate](#present-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. 3. From your server, make a [/donations](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations) request to [make a donation](#make-a-donation). 4. [Get the outcome](#giving-webhook) from a webhook and show it to the shopper. The following diagram shows the donation flow for a fixed amount donation before the shopper pays for their original transaction. ![Flow diagram for post-checkout donations](/user/pages/reuse/online-payments/donations/online-process/campaign-manager-api.svg?decoding=auto\&fetchpriority=auto) ## Get details of your active donation campaigns Depending on the [donation moment](#donation-moment) that you choose, get the details of your active donation campaigns at either moment: * When a shopper proceeds to pay for their original transaction with a payment method that supports donations. * When a shopper completes their original transaction with a payment method that supports donations, and the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) (for iDEAL payments) response includes the [donationToken](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-donationToken) field. When you make a request to get your active donation campaigns, the response you receive depends on your [donation type](#donation-type): ### Tab: Fixed amount donations 1. From your server, make a POST [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) request, specifying: | Field name | Required | Description | | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | `merchantAccount` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name. | | | `currency` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | | `store` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the user's store. Use this to get the donation campaigns that are available for a specific store. | | | `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 on a platform** #### curl ```bash curl https://checkout-test.adyen.com/v72/donationCampaigns \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "currency": "EUR", "locale": "en-US", "store": "USER_STORE_REFERENCE" }' ``` #### Java ```java // Adyen Java API Library v41.1.1 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) DonationCampaignsRequest donationCampaignsRequest = new DonationCampaignsRequest() .merchantAccount("YOUR_MERCHANT_ACCOUNT") .currency("EUR") .locale("en-US") .store("USER_STORE_REFERENCE"); // Send the request DonationsApi service = new DonationsApi(client); DonationCampaignsResponse response = service.donationCampaigns(donationCampaignsRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $donationCampaignsRequest = new DonationCampaignsRequest(); $donationCampaignsRequest ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setCurrency("EUR") ->setLocale("en-US") ->setStore("USER_STORE_REFERENCE"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new DonationsApi($client); $response = $service->donationCampaigns($donationCampaignsRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v34.0.3 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) DonationCampaignsRequest donationCampaignsRequest = new DonationCampaignsRequest { MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Currency = "EUR", Locale = "en-US", Store = "USER_STORE_REFERENCE" }; // Send the request var service = new DonationsService(client); var response = service.DonationCampaigns(donationCampaignsRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) donationCampaignsRequest := checkout.DonationCampaignsRequest{ MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Currency: "EUR", Locale: common.PtrString("en-US"), Store: common.PtrString("USER_STORE_REFERENCE"), } // Send the request service := client.Checkout() req := service.DonationsApi.DonationCampaignsInput().IdempotencyKey("UUID").DonationCampaignsRequest(donationCampaignsRequest) res, httpRes, err := service.DonationsApi.DonationCampaigns(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.1 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "currency": "EUR", "locale": "en-US", "store": "USER_STORE_REFERENCE" } # Send the request result = adyen.checkout.donations_api.donation_campaigns(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.3.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :currency => 'EUR', :locale => 'en-US', :store => 'USER_STORE_REFERENCE' } # Send the request result = adyen.checkout.donations_api.donation_campaigns(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const donationCampaignsRequest: Types.checkout.DonationCampaignsRequest = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", currency: "EUR", locale: "en-US", store: "USER_STORE_REFERENCE" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.DonationsApi.donationCampaigns(donationCampaignsRequest, { idempotencyKey: "UUID" }); ``` 2. From the response, get the details of your active donation campaign(s). You need these details [to create the donation form that you show to the shopper](#present-option-to-donate). | Field name | Description | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The unique campaign ID of the donation campaign. | | `campaignName` | The name of the donation campaign. | | `donation` | Specifies the details of the donation. This object has:- `type`: **fixedAmounts**. - `currency`: The three-character [ISO currency code](/development-resources/currency-codes/). - `values`: Specifies the fixed donation amounts the shopper can choose from. | | `causeName` | The cause of the nonprofit. | | `logoUrl` | The URL for the logo of the nonprofit. | | `bannerUrl` | The URL for the banner of the nonprofit or campaign. | | `nonprofitName` | The name of the nonprofit. | | `nonprofitDescription` | The description of the nonprofit. | | `nonprofitUrl` | The website URL of the nonprofit. | | `termsAndConditionsUrl` | The URL of the terms and conditions page of the nonprofit. | **Example POST /donationCampaigns response for a fixed amount donation** ```bash { "donationCampaigns": [ { "id": "DONATION_CAMPAIGN_ID", "campaignName": "DONATION_CAMPAIGN_NAME", "donation": { "currency": "EUR", "type": "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" } ] } ``` ### Tab: Round-up donations 1. From your server, make a POST [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) request, specifying: | Field name | Required | Description | | | ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | `merchantAccount` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your merchant account name. | | | `currency` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The three-character [ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). | | | `store` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the user's store. Use this to get the donation campaigns that are available for a specific store. | | | `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 on a platform** #### curl ```bash curl https://checkout-test.adyen.com/v72/donationCampaigns \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "currency": "EUR", "locale": "en-US", "store": "USER_STORE_REFERENCE" }' ``` #### Java ```java // Adyen Java API Library v41.1.1 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) DonationCampaignsRequest donationCampaignsRequest = new DonationCampaignsRequest() .merchantAccount("YOUR_MERCHANT_ACCOUNT") .currency("EUR") .locale("en-US") .store("USER_STORE_REFERENCE"); // Send the request DonationsApi service = new DonationsApi(client); DonationCampaignsResponse response = service.donationCampaigns(donationCampaignsRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $donationCampaignsRequest = new DonationCampaignsRequest(); $donationCampaignsRequest ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT") ->setCurrency("EUR") ->setLocale("en-US") ->setStore("USER_STORE_REFERENCE"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new DonationsApi($client); $response = $service->donationCampaigns($donationCampaignsRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v34.0.3 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) DonationCampaignsRequest donationCampaignsRequest = new DonationCampaignsRequest { MerchantAccount = "YOUR_MERCHANT_ACCOUNT", Currency = "EUR", Locale = "en-US", Store = "USER_STORE_REFERENCE" }; // Send the request var service = new DonationsService(client); var response = service.DonationCampaigns(donationCampaignsRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### Go ```go // Adyen Go API Library v21.2.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) donationCampaignsRequest := checkout.DonationCampaignsRequest{ MerchantAccount: "YOUR_MERCHANT_ACCOUNT", Currency: "EUR", Locale: common.PtrString("en-US"), Store: common.PtrString("USER_STORE_REFERENCE"), } // Send the request service := client.Checkout() req := service.DonationsApi.DonationCampaignsInput().IdempotencyKey("UUID").DonationCampaignsRequest(donationCampaignsRequest) res, httpRes, err := service.DonationsApi.DonationCampaigns(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v15.0.1 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "currency": "EUR", "locale": "en-US", "store": "USER_STORE_REFERENCE" } # Send the request result = adyen.checkout.donations_api.donation_campaigns(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.3.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :currency => 'EUR', :locale => 'en-US', :store => 'USER_STORE_REFERENCE' } # Send the request result = adyen.checkout.donations_api.donation_campaigns(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.1.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const donationCampaignsRequest: Types.checkout.DonationCampaignsRequest = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", currency: "EUR", locale: "en-US", store: "USER_STORE_REFERENCE" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.DonationsApi.donationCampaigns(donationCampaignsRequest, { idempotencyKey: "UUID" }); ``` 2. From the response, get the details of your active donation campaign(s). You need these details [to display a checkbox suggesting to round up the order amount as a donation](#present-option-to-donate). | Field name | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | The unique campaign ID of the donation campaign. | | `campaignName` | The name of the donation campaign. | | `donation` | Specifies the details of the donation. This object has:- `type`: **roundup**. - `currency`: The three-character [ISO currency code](/development-resources/currency-codes/). - `maxRoundupAmount`: Specifies the maximum amount a transaction can be rounded up to make a donation. | | `causeName` | The cause of the nonprofit. | | `logoUrl` | The URL for the logo of the nonprofit. | | `bannerUrl` | The URL for the banner of the nonprofit or campaign. | | `nonprofitName` | The name of the nonprofit. | | `nonprofitDescription` | The description of the nonprofit. | | `nonprofitUrl` | The website URL of the nonprofit. | | `termsAndConditionsUrl` | The URL of the terms and conditions page of the nonprofit. | **Example POST /donationCampaigns response for a round-up donation** ```bash { "donationCampaigns": [ { "id": "DONATION_CAMPAIGN_ID", "campaignName": "DONATION_CAMPAIGN_NAME", "donation": { "currency": "EUR", "type": "roundup", "maxRoundupAmount": 100 }, "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" } ] } ``` ## Present the option to donate ### Tab: Fixed amount donations Use the values you received in the [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) response to show a donation form with one or more buttons for the shopper to select a donation amount. For example, **Donate EUR 3**, **Donate EUR 5**, and **Donate EUR 10**. The donation form must: * Show the name and description of the nonprofit. * Link to the nonprofit's [Terms & Conditions](/online-payments/donations/terms-and-conditions). * Show the campaign banner and logo. * Have the option for the shopper to decline to donate. For example, a **Not now** button. The donation form can optionally include the cause of the nonprofit. If the shopper paid with iDEAL, tell the shopper that the donation transaction will show up in their bank statement a day or more later. ### Tab: Round-up donations Use the values you received in the [/donationCampaigns](https://docs.adyen.com/api-explorer/Checkout/latest/post/donationCampaigns) response to show a checkbox that suggests to round up the shopper's payment amount as a donation. Use the following formula to calculate the round-up amount: ```text roundupAmount = maxRoundupAmount - (commercialTxAmount % maxRoundupAmount) ``` * `maxRoundupAmount`: The maximum amount the transaction can be rounded up, received in the `/donationCampaigns` response. * `commercialTxAmount`: The original transaction amount for the shopper's order. This excludes the donation amount. The checkout page must: * Show the name of the nonprofit. * Link to the nonprofit's website. * Link to the nonprofit's [Terms & Conditions](/online-payments/donations/terms-and-conditions). If the shopper is paying with iDEAL, tell the shopper that the donation transaction will show up in their bank statement a day or more later. ## Make a donation Depending on the [donation moment](/platforms/online-payments/donations-online#donation-moment) for the campaign, you make a donation request at either time: * **Pre-checkout donation**: you first make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request. If the payment is authorized, and the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) (for iDEAL payments) response includes the [donationToken](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-donationToken) field, you make a donation request. * **Post-checkout donation**: you present the option to donate after the shopper completes the payment for their original transaction, you make a donation request and use the [donationToken](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#responses-200-donationToken) you received in the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) (for iDEAL payments) response. ### Tab: Fixed amount donations 1. Make a POST [/donations](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations) request, specifying the following fields: | Field name | Required | Description | | | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | | [amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-amount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the donation. | | | [donationCampaignId](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationCampaignId) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique campaign ID from the `/donationCampaigns` response `id` field. | | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | For cards, Apple Pay, or Google Pay: `type`: **scheme** For iDEAL: `type`: **sepadirectdebit** | | | [donationOriginalPspReference](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationOriginalPspReference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The PSP reference of the original payment. | | | [donationToken](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationOriginalPspReference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | For cards, the `donationToken` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments), or [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response. For iDEAL, the `donationToken` from the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response. | | | [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-reference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-merchantAccount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The merchant account identifier, with which you want to process the transaction. | | | [store](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-store) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the user's store. | | **Example POST /donations request on a platform** ```bash curl https://checkout-test.adyen.com/v72/donations \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -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", "store": "USER_STORE_REFERENCE" }' ``` 2. In the response, note the following: * `id`: a unique resource identifier. * `status`: the status of the donation. Possible values: **completed**, **pending**, or **refused**. * `payment`: object that contains the [result code](/online-payments/build-your-integration/payment-result-codes/#final-payment-status), and the `pspReference` for the donation transaction. ### Tab: Round-up donations 1. Make a POST [/donations](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations) request, specifying the following fields: | Field name | Required | Description | | | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | [amount](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-amount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The `currency` and `value` of the donation. | | | [donationCampaignId](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationCampaignId) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique campaign ID from the `/donationCampaigns` response `id` field. | | | [paymentMethod](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-paymentMethod) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | For cards, Apple Pay, or Google Pay: `type`: **scheme** For iDeal: `type`: **sepadirectdebit** | | | [donationOriginalPspReference](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationOriginalPspReference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The PSP reference of the original payment. | | | [donationToken](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-donationOriginalPspReference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | For cards, the `donationToken` from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response. For iDeal, the `donationToken` from the [/payments/details](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/details) response. | | | [reference](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-reference) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-merchantAccount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The merchant account identifier, with which you want to process the transaction. | | | [store](https://docs.adyen.com/api-explorer/Checkout/latest/post/donations#request-store) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Your reference for the user's store. | | **Example POST /donations request on a platform** ```bash curl https://checkout-test.adyen.com/v72/donations \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "amount": { "currency": "EUR", "value": 99 }, "donationCampaignId": "DONATION_CAMPAIGN_ID", "paymentMethod": { "type": "scheme" }, "donationOriginalPspReference": "ORIGINAL_PAYMENT_PSP_REFERENCE", "donationToken": "DONATION_TOKEN", "reference": "YOUR_DONATION_REFERENCE" "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "store": "USER_STORE_REFERENCE" }' ``` 2. In the response, note the following: * `id`: a unique resource identifier. * `status`: the status of the donation. Possible values: **completed**, **pending**, or **refused**. * `payment`: object that contains the [result code](/online-payments/build-your-integration/payment-result-codes/#final-payment-status), and the `pspReference` for the donation transaction. ## Get the donation outcome You get the outcome of each donation in a webhook message. For cards, you can show the shopper if their donation is successful after you get the webhook message. 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. To receive these webhook messages, enable the [Adyen Giving merchant webhook](/development-resources/webhooks/webhook-types#other-webhooks), which includes `eventCode`: **DONATION**. For a successful donation, the event contains: * `success`: **true**. * `originalReference`: use this value to associate the donation with the shopper's original transaction. **Successful donation webhook event** ```json { "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" } } ] } ``` ## Test and go live Before going live with your integration, [use our test cards to test your integration](/online-payments/donations/testing). ## See also * [Campaign lifecycle management](/platforms/donations#campaign-lifecycle-management) * [Giving for in-person platform payments](/platforms/in-person-payments/donations) * [API-only integration](/online-payments/donations/api-only) * [Reports and dashboard](/reporting/donation-campaigns)