Donations using our Giving feature

With our Giving feature, you can give your shoppers the option to donate to a charity after they made a purchase in your store.

Donations can be made using many popular payment methods, and are settled directly to the charity's bank account.

The Giving feature is supported with Terminal API and Classic integrations and also with the Standalone solution. All you need is one of the following payment terminals:

• AMS1
• M400
• P400 Plus
• S1E
• S1F2
• V240m Plus
• V400c Plus
• V400m

Before your charity can receive donations, they need to be onboarded and we need to configure Giving for your merchant account. The payment terminal will then prompt for a donation either:

• Automatically after every payment. This is possible with all integrations and with the Standalone solution.
• Through your payment request, so that you have control over when to ask for a donation. This is possible with a Terminal API integration.

Supported payment methods

In-store donations are supported for the following payment methods:

• Credit and debit cards: American Express, Bancontact, Cartes Bancaires, Diners, Discover, JCB, Mastercard, UnionPay, Visa, Visa Debit.
• Wallets: Apple Pay and Google Pay.

How it works

Regardless of whether donation is prompted automatically after every payment or through your payment request, the donation flow is as follows:

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

2. The shopper presents their card on the payment terminal and completes the payment.
   In a Terminal API or Classic integration, you receive the response to your payment request. In a Terminal API integration, this response includes Giving parameters which you can later use to retrieve the donation response.

3. The terminal shows the payment is Approved and presents the options to donate to the charity.

   

   

   The terminal doesn't prompt for a donation when it is offline or after a gift card payment.

4. If the shopper selects Not now, the flow stops.

   If the shopper chooses to donate, the terminal starts a new transaction (the donation) for the amount that the shopper specified.

5. The shopper completes the donation transaction.

   

   The donation is routed to the charity, and settled directly to their bank account.

   In a Terminal API or classic integration, your POS app won't receive a response for the donation because it is initiated by the terminal instead of by the POS app.

6. In a Terminal API integration, optionally retrieve the donation response through a transaction status request.
   For this, you use the Giving parameters that you received in the original payment response. Retrieving the donation response allows you, for example, to gain insight into the usage of the donation feature, or to generate a shopper receipt for the donation.

Your shopper will see two separate charges on their bank statement, one for the payment, and one for the donation.

Onboarding with Giving

Before your charity can receive donations, they need to be onboarded with Giving.

To begin the onboarding process, contact your Adyen Account Manager or our POS Support Team. They will handle the onboarding with the charity. The charity will get their own Customer Area account, where they can see an overview of donations, and handle any refunds and chargebacks.

Configure Giving

When the charity is onboarded:

1. Contact your Adyen Account Manager or our POS Support Team to:

   • Enable Giving.

   • Configure whether you want to automatically prompt for a donation after every payment, or prompt for a donation through your payment request. The latter is possible with a Terminal API integration.

2. In your Customer Area go to Point of sale > Terminal settings > Payment features.
3. Under Adyen Giving, fill out:
   • The amounts for the donation options and whether you want to include a Custom option.
   • The charity name you want to show on the terminal display.
   • Any other settings you want to update. For example, the timeout of the donation screen on the terminal.

Donation options

The donation options include:

• The Not now option. This option is shown by default. It enables shoppers to skip donating.
• Up to three other options, which you need to specify in the Customer Area:
  • Specify the amounts of the donation options.
  • Enable or disable Show custom amount. When enabled, customers can select the Custom option to enter an amount of their own choice.

    The Custom option is not supported yet on Android payment terminals.

Ask for a donation through your payment request

With a Terminal API integration you can use the tender option AskGiving in your payment request to control when the shopper is asked for a donation.

To ensure that the terminal prompts the shopper for a donation after their payment:

1. Make a PaymentRequest that contains a SaletoAcquirerData field with the tender option AskGiving specified in one of the following formats:

   • Option 1: A JSON object {"tenderOption": "AskGiving"} converted to a Base64 encoded string:
     "SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQXNrR2l2aW5nIn0="

   • Option 2: tenderOption=AskGiving:
     "SaleToAcquirerData": "tenderOption=AskGiving"

   The format that you use here will also be the format of the AdditionalResponse that you receive.

   If there are more tender options and other data elements that you need to pass in the SaleToAcquirerData field, see Add information to a payment for instructions.

   JSON Java

   JSON Java

   {
       "SaleToPOIRequest": {
           "PaymentRequest": {
               "SaleData": {
                   "SaleTransactionID": {
                       "TransactionID": "997",
                       "TimeStamp": "2020-12-02T16:16:48.000Z"
                   },
                   "SaleToAcquirerData": "tenderOption=AskGiving"
               },
               "PaymentTransaction": {
                   "AmountsReq": {
                       "Currency": "EUR",
                       "RequestedAmount": 155.75
                   }
               }
           },
           "MessageHeader": {
               "ProtocolVersion": "3.0",
               "MessageClass": "Service",
               "MessageCategory": "Payment",
               "MessageType": "Request",
               "ServiceID": "0110123015",
               "SaleID": "POSSystemID12345",
               "POIID": "M400-260193322"
           }
       }
   }

   String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
       String saleID = "YOUR_CASH_REGISTER_ID";
       String POIID = "YOUR_TERMINAL_ID";
       String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
   
       SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
       MessageHeader messageHeader = new MessageHeader();
       messageHeader.setProtocolVersion("3.0");
       messageHeader.setMessageClass( MessageClassType.SERVICE );
       messageHeader.setMessageCategory( MessageCategoryType.PAYMENT );
       messageHeader.setMessageType( MessageType.REQUEST );
       messageHeader.setServiceID(serviceID);
       messageHeader.setSaleID(saleID);
       messageHeader.setPOIID(POIID);
       saleToPOIRequest.setMessageHeader(messageHeader);
   
       PaymentRequest paymentRequest = new PaymentRequest();
       SaleData saleData = new SaleData();
       TransactionIdentification saleTransactionID = new TransactionIdentification();
       saleTransactionID.setTransactionID(transactionID);
       saleTransactionID.setTimeStamp(DatatypeFactory.newInstance().newXMLGregorianCalendar(new GregorianCalendar()));
       saleData.setSaleTransactionID(saleTransactionID);
       saleData.setSaleToAcquirerData("tenderOption=AskGiving");
       paymentRequest.setSaleData(saleData);
   
       PaymentTransaction paymentTransaction = new PaymentTransaction();
       AmountsReq amountsReq = new AmountsReq();
       amountsReq.setCurrency("EUR");
       amountsReq.setRequestedAmount( BigDecimal.valueOf(155.75) );
       paymentTransaction.setAmountsReq(amountsReq);
       paymentRequest.setPaymentTransaction(paymentTransaction);
       saleToPOIRequest.setPaymentRequest(paymentRequest);
       terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

   https://docs.adyen.com/point-of-sale/donate#donate_1

2. In the response, note the AdditionalResponse data which you can use in a subsequent TransactionStatusRequest to retrieve the donation response:

   • adyen_giving_sale_id: the donation sale ID, which is fixed to AdyenGiving.
   • adyen_giving_service_id: the donation service ID. For example, 8ha5925831.

   Other than the above AdditionalResponse data, the payment response is the same as the response you receive for an approved payment without AskGiving tender option. The payment response contains no details of the donation, because the donation is a separate transaction that is initiated by the terminal instead or by your POS app.

   Payment response after asking for a donation

   {
       "SaleToPOIResponse": {
           "MessageHeader": {...},
           "PaymentResponse": {
               "POIData": {...},
               "PaymentReceipt": [...],
               "PaymentResult": {
                   "AmountsResp": {
                       "AuthorizedAmount": 155.75,
                       "Currency": "EUR"
                   },
                   ...,
                   "PaymentAcquirerData": {...},
                   "PaymentInstrumentData": {...}
               },
               "Response": {
                   "AdditionalResponse": "...adyen_giving_sale_id=AdyenGiving...adyen_giving_service_id=8ha5925831",
                   "Result": "Success"
               },
               "SaleData": {
                   "SaleTransactionID": {
                       "TimeStamp": "2020-12-02T16:16:48.163Z",
                       "TransactionID": "997"
                   }
               }
           }
       }
   }

   https://docs.adyen.com/point-of-sale/donate#payment-response-after-asking-for-a-donation

Retrieve the donation response

In a Terminal API integration, you can retrieve the donation result through a transaction status request. You can do this regardless of whether you automatically prompt for a donation after every payment, or prompt for a donation through your payment request.

The transaction status request returns the response of the donation transaction, including a PaymentReceipt object that you can use to generate a shopper receipt for the donation.

1. To start a TransactionStatusRequest , make a POST request to a Terminal API endpoint, specifying:

   If you're using cloud communications, make the request to a /sync endpoint.

   • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:

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

   • TransactionStatusRequest: the request body with:

     • ReceiptReprintFlag: true

     • DocumentQualifier: 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. This parameter returns the response for a specific donation.

   The example below shows how you would request the status of a donation with the adyen_giving_service_id 8ha5925831.

   JSON Java

   JSON Java

   {
       "SaleToPOIRequest": {
           "MessageHeader": {
               "ProtocolVersion": "3.0",
               "MessageClass": "Service",
               "MessageCategory": "TransactionStatus",
               "MessageType": "Request",
               "SaleID": "POSSystemID12345",
               "ServiceID": "29246",
               "POIID": "M400-260193322"
           },
           "TransactionStatusRequest": {
               "ReceiptReprintFlag": true,
               "DocumentQualifier": [
                   "CashierReceipt",
                   "CustomerReceipt"
               ],
               "MessageReference": {
                   "MessageCategory": "Payment",
                   "SaleID": "AdyenGiving",
                   "ServiceID": "8ha5925831"
               }
           }
       }
   }

   String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
       String saleID = "YOUR_CASH_REGISTER_ID";
       String POIID = "YOUR_TERMINAL_ID";
       String transactionID = "YOUR_UNIQUE_TRANSACTION_ID";
   
       SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
       MessageHeader messageHeader = new MessageHeader();
       messageHeader.setProtocolVersion("3.0");
       messageHeader.setMessageClass( MessageClassType.SERVICE );
       messageHeader.setMessageCategory( MessageCategoryType.TRANSACTIONSTATUS );
       messageHeader.setMessageType( MessageType.REQUEST );
       messageHeader.setServiceID(serviceID);
       messageHeader.setSaleID(saleID);
       messageHeader.setPOIID(POIID);
       saleToPOIRequest.setMessageHeader(messageHeader);
   
       TransactionStatusRequest transactionStatusRequest = new TansactionStatusRequest();
       transactionStatusRequest.setReceiptReprintFlag(true);
       transactionStatusRequest.setDocumentQualifier("CashierReceipt", "CustomerReceipt");
   
       MessageReference messageReference = new MessageReference();
       messageReference.setMessageCategory("Payment");
       messageReference.setSaleID("AdyenGiving");
       messageReference.setServiceID("8ha5925831");
       transactionStatusRequest.setMessageReference(messageReference);
       saleToPOIRequest.setTransactionStatusRequest(transactionStatusRequest);
       terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

   https://docs.adyen.com/point-of-sale/donate#transaction-status

2. In the TransactionStatusResponse , note the RepeatedMessageResponse. This contains the response for the donation transaction.

   Transaction status response with the donation response

   {
       "SaleToPOIResponse": {
           "MessageHeader": {
               "MessageCategory": "TransactionStatus",
               "MessageClass": "Service",
               "MessageType": "Response",
               "POIID": "M400-260193322",
               "SaleID": "POSSystemID12345",
               "ServiceID": "29246"
           },
           "TransactionStatusResponse": {
               "MessageReference": {
                   "MessageCategory": "Payment",
                   "SaleID": "AdyenGiving"
               },
               "RepeatedMessageResponse": {
                   "MessageHeader": {
                       "DeviceID": "6",
                       "MessageCategory": "Payment",
                       "MessageClass": "Service",
                       "MessageType": "Response",
                       "POIID": "M400-260193322",
                       "SaleID": "AdyenGiving",
                       "ServiceID": "8ha5925831"
                   },
                   "RepeatedResponseMessageBody": {
                       "PaymentResponse": {
                           "POIData": {
                               "POIReconciliationID": "1001",
                               "POITransactionID": {
                                   "TimeStamp": "2020-12-02T16:16:48.000Z",
                                   "TransactionID": "6JuQ001604433524001.NC6HT9CRT65ZGN82"
                               }
                           },
                           "PaymentReceipt": [
                               {
                                   "DocumentQualifier": "CashierReceipt",
                                   ...
                               },
                               {
                                   "DocumentQualifier": "CustomerReceipt",
                                   ...
                               }
                           ],
                           "PaymentResult": {
                               "AmountsResp": {
                                   "AuthorizedAmount": 5,
                                   "Currency": "EUR"
                               },
                               "OnlineFlag": true,
                               "PaymentAcquirerData": {...},
                               "PaymentInstrumentData": {...}
                           },
                           "Response": {
                               "AdditionalResponse": "...",
                               "Result": "Success"
                           },
                           "SaleData": {
                               "SaleTransactionID": {
                                   "TimeStamp": "2020-11-03T19:58:44.000Z",
                                   "TransactionID": "6JuQ001604433524001"
                               }
                           }
                       }
                   }
               },
               "Response": {
                   "AdditionalResponse": "...",
                   "Result": "Success"
               }
           }
       }
   }

   https://docs.adyen.com/point-of-sale/donate#transaction-status-response-with-the-donation-response

See also