In-person donations using Adyen Giving

With Adyen Giving, your users can give shoppers the option to donate to a nonprofit organization when shoppers make an in-store purchase. To enable this, you set up donation campaigns for account holder resources.

When a campaign has been started and a shopper chooses to donate, the donation is processed as a separate transaction. Adyen covers all fees and the donation amount is transferred to the nonprofit in full. This means you can split amounts and fees on the original transaction, but not on the donation transaction.

Requirements

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

How it works

To enable your users to accept donations at the point of sale:

1. Choose a nonprofit.

2. Set up a donation campaign in your Customer Area, under Giving > Campaigns.
   You need to select:

   • The account holders that you want to make the campaign available to.
   • The nonprofit.

   • The stores and donation settings.

3. Optionally configure a donation campaign logo to show as the standby screen on payment terminals.

4. To be able to inform shoppers about their donation, implement either or both of the following methods:

   • Generate a shopper receipt for the donation. This is only possible if you use the two-step interaction flow.

   • Use Giving webhook messages to send shoppers a receipt by email or mobile messaging.

5. Start the campaign from the Campaigns overview in your Customer Area.

After the next scheduled reboot of the payment terminals, the terminals automatically show the donation options from the campaign after every payment, except when the terminal is offline or the payment method is not supported by Adyen Giving.

Donation settings

With our Giving integration, you have the flexibility to choose a combination of interaction flow and donation type. You configure these choices in your donation campaign.

However, there are limitations to the supported choices, depending on region and currency, payment method, and terminal model.

Interaction flow

You can choose to use a one-step flow or a two-step flow. Technically, there are two transactions: one for the payment and one for the donation. But in the one-step flow, the payment and the donation are shown as a single transaction, and shoppers need to present their card only once.

In the two-step flow, shoppers need to present their card twice. With a Terminal API integration, this enables you to provide the shopper with a receipt for their donation, because you can retrieve the full donation transaction response. The two-step flow also supports more payment methods than the one-step flow.

The effect on your payment terminals is as follows:

1. After you have set up and activated your donation campaign, both flows start in the same way:

   1. You initiate a payment for the goods your shopper is purchasing.

   2. The shopper presents their card on the payment terminal.

2. From this moment, the flows are different:

   One-step flow	Two-step flow
   	The terminal screen shows that the payment is approved, and...
   The terminal presents the options to donate to the nonprofit.	... the terminal also presents the options to donate to the nonprofit.
   If the shopper chooses to donate, the terminal processes the donation.	If the shopper chooses to donate, the terminal starts the donation transaction for the amount the shopper specified and asks for the card.
   	The shopper presents their card on the terminal to complete the donation transaction.
   The terminal shows a confirmation to thank the shopper.	The terminal shows a confirmation to thank the shopper.
   The terminal shows that the payment is approved.

In both flows:

• The terminal does not prompt for a donation when it is offline or after a gift card payment.
• If the shopper selects the donation option Not now, the terminal shows a confirmation screen with a message that no donation was made.

Donation type

You can present the following donation types on the payment terminal screen:

• Fixed amounts: configure up to three fixed amounts to present to shoppers.
• Round up: allow shoppers to donate by rounding up the transaction amount of their purchase. You can enable the round-up feature on its own, or together with one fixed amount.

The terminal always shows a "Not now" option that the shopper can select to skip donating.

The following example screens are for the two-step flow, showing that the payment was approved.

Fixed amounts	Round up	Round up and one fixed amount

Set up a donation campaign for account holders

The Campaigns user interface in the Customer Area guides you through setting up a donation campaign, and shows example screens. The main steps to create an Adyen Giving donation campaign for your account holders are as follows:

1. In your Customer Area, go to Giving > Campaigns.

2. Select Create new campaign > For account holders.

3. Add the account holders to the campaign, one by one or as a group:

   • One by one: select Search accounts, select your balance platform, and search by account holder ID or reference, legal entity ID or name, or email address. Then select Add in the tile of the individual account holder.
   • Group: select Submit a list of accounts, select your balance platform, enter a comma-separated list of account holder IDs, and select Add.

   The UI will inform you if an account holder has already been added or cannot be found on the selected balance platform.

4. Select the campaign details:

   • The nonprofit.
   • Either a specific cause, or "General fundraising".

   • The sales channel: online payments (ecommerce), in-person payments (point of sale), or both.

5. If you selected online payments, first select the stores that the campaign applies to.
   Then select the donation type. When you choose fixed amounts and enter the amounts in your default currency, we automatically add equivalent amounts in other currencies if necessary for the selected stores.

6. If you selected in-person payments, first select the stores that the campaign applies to.
   Then select:

   • The one-step or two-step interaction flow.
   • Timeouts for the donation prompt and the payment screen.
   • The text to show on the donation screen on the terminal: the name of the nonprofit or the cause you selected.

   • The donation type. When you choose fixed amounts and enter the amounts in your default currency, we automatically add equivalent amounts in other currencies if necessary for the selected stores.

7. Review the summary. When everything is correct, select Create campaign.

The campaign is now set up, but not active yet.

When you are ready to activate the campaign:

1. In your Customer Area, go to Giving > Campaigns.
2. Find the tile for the campaign, and select Start.

(Optional) Configure a logo

(Optional) Get the two-step donation response

If you are using the two-step flow in a Terminal API integration, you can retrieve the full response for the donation transaction through a transaction status request.

A reason to retrieve the donation response is that this includes a PaymentReceipt object that you can use to generate a shopper receipt for the donation.

1. Make a transaction status request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to TransactionStatus.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		TransactionStatus
     MessageType		Request
     SaleID		Your unique ID for the POS system component to send this request from.
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • The TransactionStatusRequest object with:

     • ReceiptReprintFlag: true

     • DocumentQualifier: The receipt data you want to receive in the response. Can be one or both of:

       • CashierReceipt: cashier receipt, including signature data.

       • CustomerReceipt: shopper receipt.

     • MessageReference: this object identifies what you want to receive:

       Parameter	Description
       MessageCategory	Payment.
       SaleID	AdyenGiving. If you specify this SaleID and omit the ServiceID, you will get the response for the latest donation made on the terminal that you route the transaction status request to.
       ServiceID	The adyen_giving_service_id from the original payment response. Use this parameter to retrieve the response for a specific donation instead of the latest donation made on the terminal.

   The example below shows how to check the status of a donation with the adyen_giving_service_id 8ha5925831.

2. In the TransactionStatusResponse, note the RepeatedMessageResponse. This contains the response for the donation transaction. Use the RepeatedMessageResponse.PaymentReceipt object to generate a shopper receipt for the donation.

Giving webhook

You can get the outcome of each donation in a webhook message. This enables you to inform shoppers by email or mobile messaging about their donation, provided you have the shopper's contact details.

To receive these webhook messages, enable the Adyen Giving merchant webhook, which includes eventCode: DONATION.

For a successful donation, the event contains:

• success: true.
• originalReference: use this value to associate the donation with the shopper's original transaction.

See also