The Giving feature for API only

Using our APIs, accept donations to a charity of your choice, 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 present your shoppers with the option to donate to a charity after they have completed a payment. When your shopper chooses to make a donation, this is charged to the same payment method they used for the payment.

Before you begin

These instructions explain how to add Giving to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.

Before starting your Giving integration:

1. Make sure that you have set up your back end implementation and created an instance of AdyenCheckout.
2. Enable and integrate a payment method that supports Giving.
3. Ensure the Giving onboarding process has been completed. You can confirm by contacting your Adyen Account Manager or our Support Team.
4. Contact your Adyen Account Manager or our Support Team to activate the donationToken in your /payments response.

Build your donations form

Before showing the option to donate, you need to make a payment with a payment method that supports donations. If this payment is successful (the payment result is either Authorised, Received, or Pending Received), present your shopper with the option to make a donation.

Render a donation form with either:

• A field where the shopper can enter their own donation amount.
• Buttons for fixed donation amounts. For example, Donate €3, Donate €5, and Donate €10.

Your donation form will also need to:

• Show the name of the charity, and some information about them.
• Link to the charity's Privacy Policy and Terms & Conditions.
• Have an option to not donate. A button with Not now, for example.
• Inform the shopper that they will see two charges on their bank statement (one for the purchase, and one for the donation), and from two separate entities (you, and the charity).

Make a donation

Make a donation after a completed payment

When the shopper chooses to donate, make a POST request to /donations. In this request, specify:

• amount: The currency and value of the donation. The example is for a donation of 10 EUR.
• donationToken: The donationToken from the /payments response of the payment.
• donationOriginalPspReference: The PSP reference of the payment. For example, V4HZ4RBFJGXXGN82.
• 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 onboarding your charity.

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

Use a token to donate

To make a donation with a tokenized payment method, make a POST request to /donations. In this request, specify:

• amount: The currency and value of the donation. The example is for a donation of 10 EUR.
• paymentMethod.storedPaymentMethodId: The shopper's payment token. For example, 8415718415172200.
• 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 onboarding your charity.
• shopperReference: The unique shopper reference to identify the shopper.

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

The /donations response contains:

• additionalData.merchantReference: Echoes the reference you provided in the /donations request.
• pspReference: Adyen's unique reference for the donation.
• resultCode: The result of the donation.

{
   "id":"UNIQUE_RESOURCE_ID",
   "status":"completed",
   "donationAccount":"MyCharity_Giving_TEST",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "amount":{
      "currency":"EUR",
      "value":1000
   },
   "reference":"YOUR_DONATION_REFERENCE",
   "payment":{
      "pspReference":"FKSPNCQ8HXSKGK82",
      "resultCode":"Authorised",
      "amount":{
         "currency":"EUR",
         "value":1000
      },
      "merchantReference":"YOUR_DONATION_REFERENCE"
   }
}

Present the donation result

If the donation is successfully received, you receive an Authorised resultCode. Present the shopper with a message thanking them for their donation.

If you received another resultCode, refer to the Result codes page to learn what it means.

Test and go live

To test for 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.

See also