Are you looking for test card numbers?

Would you like to contact support?

Default icon

The Giving feature for API only

Add Adyen Giving to an existing API-only integration.

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. When they 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:

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 notification webhook for Giving in your Customer Area.

How it works

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:

Make a donation request with a unique donation token

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

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

/donations request with a donation token
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 a tokenized payment method

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

Field name Required Description
paymentMethod.storedPaymentMethodId -white_check_mark- Your reference for the shopper's stored payment method.
amount -white_check_mark- The currency and value of the donation.
donationAccount -white_check_mark- 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 -white_check_mark- 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",
      "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 with eventCode: DONATION.
For a successful payment, the notification contains success: true.

Successful donation webhook notification
{
  "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 notification webhook 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 notification webhooks with the eventCode: DONATION.

See also