In-person donations using Adyen Giving

With Adyen Giving, your users can give shoppers the option to donate to a nonprofit organization as part of an in-store purchase. When 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.

This page describes how to implement in-person donations after a donation campaign has been set up.

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 and set up an account holder donation campaign in your Customer Area or using API calls. For instructions, see Create and manage donation campaigns.

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

3. 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.

4. Start the campaign in your Customer Area, or using an API call. For instructions, see Create and manage donation campaigns.

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 payment method is not supported by Adyen Giving.

(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