Read more
Learn more about Adyen Giving on adyen.com.
With Adyen Giving, 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.
Adyen Giving 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 Adyen 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:
-
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 Adyen 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 chooses to donate, the terminal starts a new transaction (the donation) for the amount that the shopper specified.
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. -
The shopper presents their card and completes the donation transaction.
The donation is routed to the charity, and settled directly to their bank account. - In a Terminal API integration, optionally retrieve the donation response through a transaction status request.
For this, you use the Adyen 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 Adyen Giving
Before your charity can receive donations, they need to be onboarded with Adyen Giving.
You should approach your chosen charity and get their consent before beginning the onboarding process.
To begin the onboarding process, contact either 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 Adyen Giving
When you contact us to start the onboarding process of your charity, also let us know:
- 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.
- What donation options you want to show on the terminal display. You can also configure donation options and related settings yourself in your Customer Area under Payment features.
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:
-
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, refer to 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 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.{ "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 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 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 you would request 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.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" } } } }