Adyen for API only

Accept Adyen Giving donations using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.

With Adyen Giving, you can give your shoppers the option to donate to a charity after a payment has been completed. 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 Adyen 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 Adyen 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 Adyen Giving.
3. Ensure the onboarding process Adyen Giving has been completed. You can confirm by contacting either 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 form for Adyen Giving

Before giving your shopper the option to donate, you will 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

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, 991559660454807J.
• donationAccount: The Adyen account name of your charity. We will provide you with this account name once your chosen charity has been onboarded.

   curl https://checkout-test.adyen.com/v67/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",
              //Optional
              "cvc": "123”
          },
          "donationToken": "YOUR_DONATION_TOKEN",
          "donationOriginalPspReference": "991559660454807J",
          "donationAccount" : “CHARITY_ACCOUNT”,
          "returnUrl": "https://your-company.com/...",
          "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
          "shopperInteraction": "Ecommerce"
        }

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.
• donationOriginalPspReference: The PSP reference of the payment. For example, 991559660454807J.
• donationAccount: The Adyen account name of your charity. We will provide you with this account name once your chosen charity has been onboarded.
• shopperReference: The unique shopper reference to identify the shopper.

   curl https://checkout-test.adyen.com/v67/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": "CHARITY_ACCOUNT",
            "shopperInteraction": "Ecommerce",
            "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" : "CHARITY_ACCOUNT",
   "merchantAccount" : "YOUR_MERCHANT_ACCOUNT",
    "amount": {
          "currency": "EUR",
          "value": 1000
      },
   "reference" : "YOUR_DONATION_REFERENCE",
   "payment" : {
      "pspReference": "8535762347980628",
      "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

When you onboard with Adyen Giving, we create a test charity account that you can use for testing purposes. You will get a separate Customer Area login for this account and a corresponding donationAccount.

To test whether your donation flow is working correctly:

1. Make a /donations request, providing the donationAccount of your test charity.
2. Log in to the Customer Area account for your test charity, and navigate to Transactions > Payments.

If the donation is successful it appears in this transaction list.

When you are live with Adyen Giving, you can confirm whether your chosen charity is receiving donations by contacting either your Adyen Account Manager or our Support Team.

See also