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:

• M400
• P400 Plus
• 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 cash register won't receive a response for the donation because it is initiated by the terminal instead of by the cash register.

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. Fill out the donation options and the charity name you want to show on the terminal display, and any other settings you want to update.

Donation options

The donation options include:

• The Not now option. This enables shoppers to skip donating.
• Up to three other options. These can include fixed donation amounts and the Custom option that lets shoppers enter an amount of their own choice.

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, refer to Add information to a payment for instructions.

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

   • 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);

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 cash register receives no further details at this point about the donation, because the donation is a separate transaction that is initiated by the terminal instead of by the cash register.

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

   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"
                   }
               }
           }
       }
   }

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 cash register.
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours.
     POIID		Unique ID of the terminal that you want to route 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.

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

   • 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);

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

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

   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.852604433530682C"
                               }
                           },
                           "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"
               }
           }
       }
   }

See also