The Giving feature for API only

Accept donations for a charity and build your own payment form to have full control over the look and feel of your checkout page.

With our Giving feature, you can give the shopper the option to donate to a charity after they complete a payment. You can also use the shopper's stored payment details for donations. When shoppers choose to make a donation, it is charged to the same payment method they used for the payment.

Before you begin

This page assumes you've already:

• Built an API-only integration.

Before starting your Giving integration:

1. Enable and integrate a supported payment method.
2. If you chose a charity that isn't one our one of our pre-approved charities, confirm that they completed the Giving onboarding process by contacting your Adyen Account Manager or our Support Team.
3. Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments or /payments/details response.
4. Set up the webhook for Giving in your Customer Area.

How it works

The payment flow depends on if you ask ask the shopper to donate immediately after a transaction or make a donation with stored payment details, for example if the shopper pays for your subscription-based service:

After the shopper completes their purchase, you can start the donation flow:

1. Show the shopper a donation form.
2. From your server, make a /donations request to make a donation.
3. Get the outcome from a notification webhook and show it to the shopper.

Step 1: Show a donation form

Before you show the option to donate, the shopper must make a payment with a payment method that supports donations. If their payment is successful, show the shopper a donation form.

Render a donation form with either:

• A field for the shopper to enter a donation amount.
• Buttons for the shopper to select a donation amount. For example, Donate €3, Donate €5, and Donate €10.

The donation form must:

• Show the name of the charity, and some information about them.
• Link to the charity's Privacy Policy and Terms & Conditions.
• Have the option for the shopper to decline to donate. For example, a Not now button.
• Tell the shopper that two different transactions will show up in their bank statement: one for the purchase (paid to your account) and another for the donation (paid to the charity's account).

If the shopper paid with iDeal and chooses to donate:

• Tell the shopper that the donation is a SEPA Direct Debit from the bank account associated with their iDeal payment and get their consent to process the donation.
• Tell the shopper that the donation transaction will show up in their bank statement a day or more later.

Step 2: Make a donation

The shopper can choose to make a donation after completing the payment for their purchase. You can make a donation request with either:

• a unique donation token that you get after a payment.
• a tokenized payment method, for example, the shopper's stored card details for subscription payments.

Make a donation request with a unique donation token

From your server, make a POST request to /donations specifying:

Field name	Required	Description
donationToken		For cards, the donationToken from the /payments response. For iDeal, the donationToken from the /payments/details response.
paymentMethod		For cards, type: scheme. For iDeal, type: sepadirectdebit.
amount		The currency and value of the donation.
donationOriginalPspReference		The PSP reference of the payment.
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 choosing your charity
shopperInteraction		ContAuth.

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

Make a donation request with stored payment details

For a subscription-based business model, you can use the shopper's stored payment details that they use to make their subscription payments. If you don't store the shopper's payment details on your server, get the token and make sure it's for a supported payment method.

From your server, make a POST request to /donations specifying:

Field name	Required	Description
paymentMethod.storedPaymentMethodId		Your reference for the shopper's stored payment method.
amount		The currency and value of the donation.
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 choosing your charity
shopperInteraction		ContAuth.
recurringProcessingModel		The type of the recurring payment.

curl https://checkout-test.adyen.com/v69/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",
      "storedPaymentMethodId":"8415718415172200"
   },
   "returnUrl":"https://your-company.com/...",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "donationAccount":"{hint:Use this for testing donations.}MyCharity_Giving_TEST{/hint}",
   "shopperInteraction":"ContAuth",
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID",
   "recurringProcessingModel":"CardOnFile"
}'

Step 3: Get the donation outcome

You get the outcome of each donation asynchronously, in a webhook event with eventCode: DONATION.

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

{
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "amount": {
          "currency": "EUR",
          "value": 500
        },
        "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"
      }
    }
  ]
}

For cards, you can show the shopper if their donation is successful after you get the webhook. 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.

Test and go live

To test your Giving integration:

1. Contact either your Adyen Account Manager or our Support Team and ask them to set up your account for Giving.
2. Make a /donations request using the donationAccount MyCharity_Giving_TEST. For live payments, use the donationAccount of the charity you chose.
3. Verify that your test donations are successful when you receive webhook events with the eventCode: DONATION.

See also