--- title: "Create and manage donation campaigns" description: "Set up donation campaigns and manage the campaign life cycle in the Customer Area or using API calls." url: "https://docs.adyen.com/platforms/donations/create-manage-campaigns" source_url: "https://docs.adyen.com/platforms/donations/create-manage-campaigns.md" canonical: "https://docs.adyen.com/platforms/donations/create-manage-campaigns" last_modified: "2026-07-13T16:23:00+02:00" language: "en" --- # Create and manage donation campaigns Set up donation campaigns and manage the campaign life cycle in the Customer Area or using API calls. [View source](/platforms/donations/create-manage-campaigns.md) With Adyen Giving, your users can give shoppers the option to donate to a nonprofit organization when shoppers make a purchase, either online or at the point of sale. To enable this, you set up donation campaigns for [account holders](/platforms/account-structure-resources#balance-platform-resources), or you build your own UI to let your users self-serve their donation campaigns. This page describes how to set up and manage donation campaigns. A campaign can be for online payments, for in-person payments, or for both online and in-person payments. To learn how to handle payments with donations after a donation campaign is set up and has started, refer to [Online donations](/platforms/online-payments/donations-online) or [In-person donations](/platforms/in-person-payments/donations-in-person). ## 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, and/or a Terminal API integration with payment terminals or a Standalone solution. The terminals must use terminal software version 1.109 or later. Some terminals or features require software version 1.110 or later. | | **[API credentials](/development-resources/api-credentials/)** | To create and manage donation campaigns using API requests, your API credential must have the following role:- **Management API - Campaign Management read and write** | | **[Customer Area roles](/account/user-roles)** | To create and manage donation campaigns using the Customer Area, you must 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. | | **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. You can also pick one of our [pre-approved nonprofits](https://www.adyen.com/giving/nonprofit) that have already been onboarded. | ## Donation options With our Giving integration, you have the flexibility to choose a combination of interaction flow and donation type. 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). With in-person payments, there are also limitations with regard to [terminal model](/platforms/donations#terminals). ### Interaction flow ### Tab: Online Your integration can present the option to donate at different moments in the checkout flow: * **Pre-checkout**: the shopper can review the total transaction amount that includes the donation before completing the payment. Pre-checkout donations are only possible with an [API only](/online-payments/donations/api-only) integration. * **Post-checkout**: the shopper can contribute to the donation campaign after completing the payment. This gives you flexibility to align Giving with your existing checkout process. Presenting the donation option pre-checkout or post-checkout is not configured as a setting during campaign setup. Instead, you need to implement this in your [online payments flow](/platforms/online-payments/donations-online#online-payments-flow). ### Tab: In-person In your donation campaign, you can configure to use a **one-step flow** or a **two-step flow**. Technically, there are two transactions: one for the payment and one for the donation. But in the one-step flow, the payment and the donation are shown as a single transaction, and shoppers need to present their card only once. In the two-step flow, shoppers need to present their card twice. With a Terminal API integration, this enables you to provide the shopper with a receipt for their donation. The two-step flow also supports more payment methods than the one-step flow. The effect on your payment terminals is as follows: 1. After you have set up and activated your donation campaign, both flows start in the same way: 1. You initiate a payment for the goods your shopper is purchasing. 2. The shopper presents their card on the payment terminal. 2. From this moment, the flows are different: | One-step flow | Two-step flow | | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | | The terminal screen shows that the payment is approved, and... | | The terminal presents the [options to donate](#donation-type) to the nonprofit. | ... the terminal also presents the [options to donate](#donation-type) to the nonprofit. | | If the shopper chooses to donate, the terminal processes the donation. | If the shopper chooses to donate, the terminal starts the donation transaction for the amount the shopper specified and asks for the card. | | | The shopper presents their card on the terminal to complete the donation transaction. | | The terminal shows a confirmation to thank the shopper. | The terminal shows a confirmation to thank the shopper. | | The terminal shows that the payment is approved. | | In both flows: * If the shopper selects the donation option *Not now*, the terminal shows a confirmation screen with a message that no donation was made. * The terminal does not prompt for a donation after a gift card payment. * Donations are currently not possible while the internet connection is down, even if you enabled [offline payments](/point-of-sale/offline-payment). The terminal still prompts for a donation. But when the shopper chooses to donate, the terminal shows "Declined". The offline payment itself will be processed as expected. ### Donation type ### Tab: Online In your donation campaign, you can configure the following donation types: * **Fixed amounts**: up to three fixed donation amounts that shoppers can choose from when they make a payment. Your checkout needs to provide a selection mechanism, such as donation buttons for these amounts. * **Round up**: let shoppers donate by rounding up the transaction amount of their purchase to the nearest full amount. Your checkout needs to show a round-up option. ### Tab: In-person In your donation campaign, you can configure the following donation types to present on the payment terminal screen: * **Fixed amounts**: configure up to three fixed amounts to let shoppers choose from. * **Round up**: allow shoppers to donate by rounding up the transaction amount of their purchase to the nearest full amount. * **Round up and one fixed amount**: let shoppers choose between rounding up the transaction amount or donating a fixed amount. The terminal always shows a *"Not now"* option that the shopper can select to skip donating. The following example screens are for the two-step flow, showing that the payment was approved. | Fixed amounts | Round up | Round up and one fixed amount | | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![Screen with fixed amounts](/images/7/e/4/3/b/7e43bfa867661f1e3e2bd1f759e32d933b87e5c1-screen-enfixed-amounts.png "Fixed amount options") | ![Round-up screen](/images/1/f/a/d/9/1fad995f1295ac728a0a8954bed6b63647ec10e3-screen-enround-up.png "Round-up option") | ![Screen with round-up and one fixed amount](/images/8/f/3/8/7/8f387d18e1654c9626cad2f00e67a14e7381faad-screen-enround-up-and-fixed.png "Round-up option and one fixed amount option") | ## Set up a donation campaign for account holders To create a donation campaign, you can use your Customer Area or make API calls. Select the tab for the method you want to use. ### Tab: Customer Area 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 where the campaign will run: * **Online** (ecommerce) * **In-person** (point of sale) * Or select both **Online** and **In-person** if you support both ecommerce and point-of-sale payments 5. For online payments, first select the stores that the campaign applies to.\ Then select the donation type. If 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. For in-person payments, first select the stores that the campaign applies to.\ Then 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. To start the campaign, see the instructions under [Manage donation campaigns](#manage-campaigns). ### Tab: API To set up an Adyen Giving donation campaign for your account holders using API calls: 1. To get a paginated list of available nonprofit organizations to choose from, make a POST `/companies/{companyId}/nonprofits` request, specifying: | Query parameter | Required | Description | | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `searchTerm` | | A query of max. 100 characters to return nonprofit organizations for. For example, `&searchTerm=clean%20water`. | | `goal` | | One or more United Nations Sustainable Development Goals to return nonprofit organizations for. Format: `unsdg_`, for example, `&goal=unsdg_6&sgoal=unsdg_2`. | | Request parameter | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `accountHolderIds` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An array with the unique identifiers of the account holders for which you want to retrieve available nonprofits. | **Get nonprofits for specified account holders** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/nonprofits \ -H 'X-API-Key: ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "accountHolderIds": ["AH00000000000000000000001","AH00000000000000000000002"] }' ``` 2. When you receive the response: 1. Choose one of the available nonprofits returned in the response. 2. In the `causes` array for the chosen nonprofit, choose a cause and save its `id`. You need this ID later, when you create the donation campaign. **Response showing two available nonprofits with one cause each** ```json { "nonprofits": [ { "name": "Environmental Protection", "description": "Protecting our planet.", "logoUrl": "https://example.com/logo3.png", "termsAndConditionsUrl": "https://example.com/terms", "website": "https://example.com", "regions": [ "NL", "DE", "US" ], "locales": [ "en-US", "nl-NL", "de-DE" ], "goals": [ "unsdg_13", "unsdg_14", "unsdg_15" ], "causes": [ { "id": "NOCA00000000000000000000000001", "name": "Reforestation", "description": "Planting trees to restore forests.", "bannerUrl": "https://example.com/banner3.png", "locales": [ "en-US", "nl-NL", "de-DE" ] } ] }, { "name": "Food Banks United", "description": "Providing those in need with nutricious food.", "logoUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/e6efc507-6774-42e4-8fee-57b0e4f77574.jpg", "termsAndConditionsUrl": "http://termsandconditions.com", "website": "http://adyengivingcharity.com", "regions": [ "NL", "US" ], "locales": [ "en-US", "nl-NL" ], "goals": [ "unsdg_1", "unsdg_2" ], "causes": [ { "id": "NOCA00000000000000000000000002", "name": "Kids Summer Meals", "description": "Provide children with healthy meals during summer months when school is out.", "bannerUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/95af3373-62e1-4745-88da-c88dd1619784.png", "locales": [ "en-US", "nl-NL" ] } ] } ] } ``` 3. To create the donation campaign, make a POST `/companies/{companyId}/campaignManagement` request, specifying: | Parameter | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The name of the donation campaign. | | `nonprofitCauseId` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The unique identifier of the nonprofit cause that you want to support. You received this ID in the `/companies/{companyId}/nonprofits` response. | | `accountHolderIds` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required for platforms. An array with the unique identifiers of the account holders that participate in the campaign, with a maximum of 400 IDs. | | `online` | | Include this object to set up donations for ecommerce payments. See the next table for the available settings. | | `inPerson` | | Include this object to set up donations for point-of-sale payments. See the next table for the available settings. | For the `online` and `inPerson` objects, you can specify the following settings. You can include both these objects if you support both ecommerce and point-of-sale payments. | Parameter | `online` | `inPerson` | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `storeIds` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | An array with the unique identifiers of the stores that participate in the campaign. The stores must be associated with the sales channel (ecommerce or point of sale) and with at least one of the specified account holders. You cannot add a store that processes payments for an account holder that is not included in the `accountHolderIds` list. | | `donationType` | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | Defines how you want to let shoppers donate. Allowed values:- **roundup**: round up the transaction amount. - **fixedAmounts**: choose a fixed amount. You must specify at least one amount in the `defaultAmount` object. The maximum number of amounts for this setting is three. - **fixedAmountsRoundup**: Only allowed for in-person donations. Round up the transaction amount, or choose a fixed amount. You must specify at least one amount in the `defaultAmount` object. The maximum number of amounts for this setting is two. | | `defaultAmount` | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if you set `donationType` to **fixedAmounts** or **fixedAmountsRoundup**. This object has the following parameters:- `currencyCode`: a three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes). Use the currency that you are most familiar with. - `amounts`: an array of fixed donation amounts in minor units. Must contain a minimum of one amount, and a maximum of three amounts for **fixedAmounts** or two amounts for **fixedAmountsRoundup**. | | `donationFlow` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The [interaction flow](/platforms/in-person-payments/donations-in-person#interaction-flow) for in-person payments. Allowed values:- **oneStep**: even though the payment and the donation are separate transactions, the shopper needs to present their payment method (card or NFC wallet) only once, after the donation prompt. - **twoStep**: the shopper needs to present their payment method (card or NFC wallet) twice, once for the payment and once for the donation. | | `displayTextField` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The text to show on the donation screen on the payment terminal. Allowed values:- **causeName**: shows the cause that the campaign supports. - **nonprofitName**: shows the name of the nonprofit organization that the campaign supports. | | `presentCardTimeoutMs` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![Recommended](/user/pages/reuse/image-library/01.icons/recommended/recommended.svg?decoding=auto\&fetchpriority=auto) | The time, in milliseconds, that the payment terminal waits for the shopper to present their payment method (card or NFC wallet) before a time-out occurs. Defaults to **10000** (10 seconds) and ranges from 5 to 15 seconds. | | `promptTimeoutMs` | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | Required if `donationFlow` is set to **twoStep**. The time, in milliseconds, that the payment terminal waits for the shopper to make a selection on the donation screen. Defaults to **10000** (10 seconds) and ranges from 5 to 15 seconds. | ![This is the required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend-lean/required.svg?decoding=auto\&fetchpriority=auto) Required.\ ![This is the conditionally required icon.](/user/pages/reuse/image-library/01.icons/requirements-legend-lean/conditionally-required.svg?decoding=auto\&fetchpriority=auto) Required in particular cases.\ ![This is the recommended icon.](/user/pages/reuse/image-library/01.icons/requirements-legend-lean/recommended.svg?decoding=auto\&fetchpriority=auto) Recommended. **Specify campaign settings** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement \ -H 'X-API-Key: ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -X POST \ -d '{ "name": "Summer Charity Drive", "nonprofitCauseId": "NOCA00000000000000000000000002", "accountHolderIds": ["AH00000000000000000000001","AH00000000000000000000002"], "online": { "storeIds": ["ST00000000000000000000001","ST00000000000000000000002"], "donationType": "fixedAmounts", "defaultAmount": { "currencyCode": "EUR", "amounts": [100, 200, 500] } }, "inPerson": { "storeIds": ["ST00000000000000000000003","ST00000000000000000000004"], "donationType": "fixedAmounts", "donationFlow": "oneStep", "defaultAmount": { "currencyCode": "EUR", "amounts": [100, 200, 500] }, "displayTextField": "causeName", "presentCardTimeoutMs": 10000, "promptTimeoutMs": 10000 } }' ``` 4. When you receive the response, save the `id` of the campaign. You need this later for campaign management operations such as activating the campaign.\ Also note the following: * The response includes the details of both the campaign and the nonprofit cause. * If you specified a currency with fixed donation amounts and if the participating stores use different currencies, equivalent amounts in other currencies are added automatically. * The initial `status` of the campaign you just created, is **inactive**. **Donation campaign created** ```json { "id": "DOCA00000000000000000000000001", "name": "Summer Charity Drive", "nonprofitCause": { "bannerUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/95af3373-62e1-4745-88da-c88dd1619784.png", "causeId": "NOCA00000000000000000000000002", "description": "Provide children with healthy meals during summer months when school is out.", "globalWebsiteUrl": "http://adyengivingcharity.com", "goals": [ "unsdg_1", "unsdg_2" ], "logoUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/e6efc507-6774-42e4-8fee-57b0e4f77574.jpg", "nonprofitName": "Food Banks United", "termsAndConditionsUrl": "http://termsandconditions.com" }, "accountHolderIds": ["AH00000000000000000000001","AH00000000000000000000002"], "online": { "storeIds": ["ST00000000000000000000001","ST00000000000000000000002"], "donationType": "fixedAmounts", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ] }, "inPerson": { "storeIds": ["ST00000000000000000000003","ST00000000000000000000004"], "donationType": "fixedAmounts", "donationFlow": "oneStep", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "EUR", "amounts": [100, 200, 500] }, { "currencyCode": "USD", "amounts": [100, 200, 500] } ], "displayTextField": "causeName", "presentCardTimeoutMs": 10000, "promptTimeoutMs": 10000 }, "status": "inactive" } ``` The campaign is now set up, but not active yet. To start the campaign, see the instructions under [Manage donation campaigns](#manage-campaigns). ## Manage donation campaigns To manage the life cycle of account holder donation campaigns, you can use your Customer Area or make API calls. Select the tab for the method you want to use. ### Tab: Customer Area You can start, stop, edit, and delete campaigns: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Giving** > **Campaigns**. 2. Find the tile for the campaign and perform the desired operation. | Operation | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Start (activate) a campaign. | On the tile, select the **Start** button. The status changes from inactive to active.It is not possible to change the status from active back to inactive. | | Stop (end) a campaign. | On the tile, select the **End campaign** button. The status changes from active to ended.It is not possible to re-activate a campaign after it has been ended. | | Edit a campaign. | Only possible if the campaign has the status inactive or active. On the tile, select the **Edit** button. Make the desired changes, and select **Save campaign**. Updates happen right away for online payments. For in-person payments, the terminals pick up the updates with their next [maintenance call](/point-of-sale/managing-terminals/maintain-performance#maintenance-calls). This usually happens overnight. | | Delete a campaign. | You can only remove campaigns that did not start yet. | ### Tab: API Using API calls, you can: * [Get a list of donation campaigns for a specific account holder](#get-campaigns-account-holder) * [Edit a donation campaign](#update) * [Start or stop a donation campaign](#start-or-stop) * [Delete a donation campaign](#delete) ### Get the campaigns for an account holder With a list of campaigns for an account holder, you can: * Show an overview in your own UI of the account holder's donation campaigns. * Find the campaign `id` and `status`. You will need to specify the campaign ID as a path parameter in API requests to edit, start, stop, or delete a campaign, and these requests are only possible if the campaign has a specific status. To retrieve a list of campaigns for a specific account holder: 1. Make a GET `/companies/{companyId}/campaignManagement/accountHolders/{accountHolderId}` request. The response returns a paginated list with all the details of all donation campaigns associated with the account holder. You can filter the list on current status, using the `status` query parameter with a value of **inactive**, **active**, or **ended**. **Get inactive campaigns for an account holder** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/accountHolders/AH00000000000000000000001?status=inactive \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' -X GET \ ``` 2. In the response, note the `id` and `status` of the campaigns. These fields are relevant for other campaign management requests. **List of inactive campaigns** ```json { "campaigns": [ { "id": "DOCA00000000000000000000000002", "name": "Summer Charity Drive", "nonprofitCause": { "bannerUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/95af3373-62e1-4745-88da-c88dd1619784.png", "causeId": "NOCA00000000000000000000000002", "description": "Provide children with healthy meals during summer months when school is out.", "globalWebsiteUrl": "http://adyengivingcharity.com", "goals": [ "unsdg_1", "unsdg_2" ], "logoUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/e6efc507-6774-42e4-8fee-57b0e4f77574.jpg", "nonprofitName": "Food Banks United", "termsAndConditionsUrl": "http://termsandconditions.com" }, "accountHolderIds": [ "AH00000000000000000000001", "AH00000000000000000000002" ], "online": { "storeIds": [ "ST00000000000000000000001", "ST00000000000000000000002" ], "donationType": "fixedAmounts", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ] }, "inPerson": { "storeIds": [ "ST00000000000000000000003", "ST00000000000000000000004" ], "donationType": "fixedAmounts", "donationFlow": "oneStep", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ], "displayTextField": "causeName", "presentCardTimeoutMs": 60000, "promptTimeoutMs": 60000 }, "status": "inactive" }, { "id": "DOCA00000000000000000000000001", "name": "TEST Summer Charity Drive", "nonprofitCause": { "bannerUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/95af3373-62e1-4745-88da-c88dd1619784.png", "causeId": "NOCA00000000000000000000000002", "description": "Provide children with healthy meals during summer months when school is out.", "globalWebsiteUrl": "http://adyengivingcharity.com", "goals": [ "unsdg_1", "unsdg_2" ], "logoUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/e6efc507-6774-42e4-8fee-57b0e4f77574.jpg", "nonprofitName": "Food Banks United", "termsAndConditionsUrl": "http://termsandconditions.com" }, "accountHolderIds": ["AH00000000000000000000001"], "online": { "storeIds": ["ST00000000000000000000001"], "donationType": "roundUp", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ] }, "status": "inactive" } ], "itemsTotal": 2, "pagesTotal": 1, "_links": { "self": { "href": "https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/accountHolder/ACCOUNT_HOLDER_ID_1?pageNumber=1&pageSize=10" }, "first": { "href": "https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/accountHolder/ACCOUNT_HOLDER_ID_1?pageNumber=1&pageSize=10" }, "last": { "href": "https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/accountHolder/ACCOUNT_HOLDER_ID_1?pageNumber=1&pageSize=10" } } } ``` ### Edit a campaign You can update settings for inactive as well as active campaigns, but there are a few restrictions: * You get a validation error if you try to add an account holder with a legal entity country or an industry that is not compatible with the nonprofit. * You cannot update the campaign `status` field directly. Instead, you can [start or stop a campaign](#start-or-stop) using a POST request to the `/campaignManagement/{campaignId}/status/{status}` endpoint. 1. If you want to add an account holder to an existing donation campaign, first check if the account holder is compatible with the nonprofit cause: 1. Make a POST `/companies/{companyId}/nonprofits` request, specifying the account holder ID in the `accountHolderIds` array. 2. Check if the response contains the `id` of the cause that the campaign supports. If the cause ID is included, the account holder is compatible. 2. To edit a donation campaign, make a PATCH `/companies/{companyId}/campaignManagement/{donationCampaignId}` request, specifying only the parameters that you want to update including, if applicable, the object they are in.\ If you update an array, this must include all array items that are needed, not just a new item that you want to add. The following example changes the transaction flow for in-person payments, and adds an account holder to the two that were already participating in the campaign. **Update account holders and donation flow** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/DOCA00000000000000000000000002 \ -H 'X-API-Key: ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -X PATCH \ -d '{ "accountHolderIds": ["AH00000000000000000000001","AH00000000000000000000002", "AH00000000000000000000003"], "inPerson": { "donationFlow": "twoStep" } } }' ``` 3. When you receive the response, note that this includes all the details of both the campaign and the nonprofit cause. **Campaign updated** ```json { "id": "DOCA00000000000000000000000002", "name": "Summer Charity Drive", "nonprofitCause": { "bannerUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/95af3373-62e1-4745-88da-c88dd1619784.png", "causeId": "NOCA00000000000000000000000002", "description": "Provide children with healthy meals during summer months when school is out.", "globalWebsiteUrl": "http://adyengivingcharity.com", "goals": [ "unsdg_1", "unsdg_2" ], "logoUrl": "https://2e3626b0dd.is.adyen.com/adyen-giving/causes/e6efc507-6774-42e4-8fee-57b0e4f77574.jpg", "nonprofitName": "Food Banks United", "termsAndConditionsUrl": "http://termsandconditions.com" }, "accountHolderIds": ["AH00000000000000000000001","AH00000000000000000000002", "AH00000000000000000000003"], "online": { "storeIds": ["ST00000000000000000000001","ST00000000000000000000002"], "donationType": "fixedAmounts", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ] }, "inPerson": { "storeIds": ["ST00000000000000000000003","ST00000000000000000000004"], "donationType": "fixedAmounts", "donationFlow": "twoStep", "defaultCurrency": "USD", "amounts": [ { "currencyCode": "USD", "amounts": [100, 200, 500] }, { "currencyCode": "EUR", "amounts": [100, 200, 500] } ], "displayTextField": "causeName", "presentCardTimeoutMs": 10000, "promptTimeoutMs": 10000 }, "status": "inactive" } ``` ### Start or stop a campaign To start or stop a donation campaign, you make a request to change the campaign status. You can activate an inactive campaign, or end an active campaign. It is not possible to make an active campaign inactive again, or to re-activate a campaign that has ended. Proceed as follows: 1. Make one of the following requests, specifying the `id` of the donation campaign in the path: * To start a campaign that is still inactive, make a POST request to the endpoint `/companies/{companyId}/campaignManagement/{donationCampaignId}/status/activate`. This changes the campaign status from **inactive** to **active**. * To stop a campaign after it has started, make a POST request to the endpoint `/companies/{companyId}/campaignManagement/{donationCampaignId}/status/end`. This changes the campaign status from **active** to **ended**. **Start a campaign** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/DOCA00000000000000000000000002/status/activate \ -H 'X-API-Key: ADYEN_API_KEY' \ -H 'Content-Type: application/json' \ -X POST \ ``` 2. Check the response: * If the request succeeds, the response returns the campaign details including the new campaign status, and the nonprofit cause details. This also happens if you try to set a status that the campaign already has, for example, if you send a `/companies/{companyId}/campaignManagement/{donationCampaignId}/status/activate` request for a campaign that already has the status **active**. * An HTTP 422 status code with an error message indicates you tried a status change that is not allowed. You can only activate an inactive campaign, or end an active campaign. ### Delete a campaign Donation campaigns can only be permanently removed if they are still inactive. To delete a campaign: 1. Make a DELETE `/companies/{companyId}/campaignManagement/{donationCampaignId}` request, specifying the ID of the donation campaign in the path. **Remove a campaign** ```bash curl https://management-test.adyen.com/v3/companies/YOUR_COMPANY_ACCOUNT/campaignManagement/DOCA00000000000000000000000001 \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' -X DELETE \ ``` 2. Check the response: * If the request succeeds, you receive the HTTP response code **204 No Content**. * If you tried to delete a campaign that was already activated or ended, you get an error response. ## Next steps [Implement online donations](/platforms/online-payments/donations-online) [Integrate Adyen Giving to let shoppers donate during online payments.](/platforms/online-payments/donations-online) [Implement in-person donations](/platforms/in-person-payments/donations-in-person) [Integrate Adyen Giving to let shoppers donate at the point of sale.](/platforms/in-person-payments/donations-in-person)