Giving for API only

Accept donations for a nonprofit with the Giving API-only integration that gives you the flexibility to customize the donation flow. You build your own donation form to accept donations, and have full control of the style, visual elements, and user interface.

If the shopper chooses to make a donation, the donation transaction uses the same payment method that the shopper used to make the original payment.

With an API-only integration, you can accept donations for fixed amounts, or allow the shopper to round up their transaction amount as a donation. You can present the option to donate before or after the shopper completes the payment for the original transaction.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

The donation flow depends on the donation moment:

Get details of your active donation campaigns

Depending on the 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 or /payments/details (for iDeal payments) response includes the donationToken field.

When you make a request to get your active donation campaigns, the response you receive depends on your donation type:

Fixed amount donationsRound-up donationsFixed amount donationsRound-up donations

From your server, make a POST /donationCampaigns request, specifying:

Field name	Required	Description
merchantAccount		Your merchant account name.
currency		The three-character ISO currency code.
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

Expand view

Copy link to code block

Copy code

Copy code

curl https://checkout-test.adyen.com/checkout/v71/donationCampaigns \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
   "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
   "currency":"EUR",
   "locale":"en-US"
}'

The response contains the details of your active donation campaign(s). Use the fields from the response to create the donation form that you show to the shopper.

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

Expand view

Copy link to code block

Copy code

Copy code

{
    "donationCampaigns": [
        {
            "id": "DONATION_CAMPAIGN_ID",
            "campaignName": "DONATION_CAMPAIGN_NAME",
            "donation": {
                "currency": "EUR",
                "donationType": "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"
        }
    ]
}

Present the option to donate

Make a donation

Depending on the donation moment for the campaign, you make a donation request at either time:

• Pre-checkout donation: you first make a /payments request. If the payment is authorized, and the /payments or /payments/details (for iDeal payments) response includes the 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 you received in the /payments or /payments/details (for iDeal payments) response.

Fixed amount donationsRound-up donationsFixed amount donationsRound-up donations

Make a POST /donations request, specifying the following fields:

Field name	Required	Description
amount		The currency and value of the donation.
donationCampaignId		The unique campaign ID from the /donationCampaigns response id field.
paymentMethod		For cards, type: scheme. For iDEAL, type: sepadirectdebit.
donationOriginalPspReference		The PSP reference of the original payment.
donationToken		For cards, the donationToken from the /payments, or /payments/details response. For iDEAL, the donationToken from the /payments/details response.
reference		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		The merchant account identifier, with which you want to process the transaction.

Example POST /donations request

Expand view

Copy link to code block

Copy code

Copy code

curl https://checkout-test.adyen.com/checkout/v71/donations \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-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"
}'

The response contains:

• id: a unique resource identifier.
• status: the status of the donation. Possible values: completed, pending, or refused.
• payment: object that contains the result code, and the pspReference for the donation transaction.
• The request body.

Get the donation outcome

You get the donation outcome for fixed amount and round-up donations in a webhook.

You get the donation outcome of each donation in a webhook. To receive these webhooks, enable the Adyen Giving merchant webhook, which includes eventCode: DONATION.

For a successful donation, the event contains success: true.

{
  "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"
      }
    }
  ]
}

Use the originalReference to associate the donation to the shopper's original transaction.

Test and go live

Before going live with your integration, use our test cards to test your integration.

See also