Read more
Learn more about Giving on adyen.com.
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 standalone terminals. 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 standalone terminals.
- 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:
-
You initiate a payment for the goods your shopper is purchasing.
-
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. -
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.
-
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. -
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. -
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.
You should approach your chosen charity and get their consent before beginning the onboarding process.
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:
-
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.
-
In your Customer Area go to Point of sale > Terminal settings > Payment features.
-
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:
-
Make a
PaymentRequest
that contains aSaletoAcquirerData
field with the tender optionAskGiving
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.{ "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);
-
-
In the response, note the
AdditionalResponse
data which you can use in a subsequentTransactionStatusRequest
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.{ "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.
-
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 standardSaleToPOIRequest.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 theServiceID
, 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 to check the status of a donation with the
adyen_giving_service_id
8ha5925831.{ "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);
-
In the
TransactionStatusResponse
, note theRepeatedMessageResponse
. This contains the response for the donation transaction.{ "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" } } } }