Fundraising/Data and flow/PSP integrations/Ingenico

Ingenico
Original Name	Globalcollect
Our Name	Ingenico
Current Name	Worldline
Payment Methods	Credit Card, iDEAL
Countries	Backup credit card processor
Documentation	https://epayments.developer-ingenico.com/documentation/hosted-payment-pages/
Production Console	https://wpc.gcsip.com/wpc/ https://account.ingenico.com/
Test Console	https://wpc.gcsip.nl/wpc/ https://preprod.account.ingenico.com/
Contact	?

Overview

Ingenico is our backup credit card processor.

We are using their hosted payment page which loads the credit card form in an iframe that is hosted by them.

https://epayments.developer-ingenico.com/documentation/hosted-payment-pages/

The API we're using is called Ingenico Connect. It is a REST API and uses JSON formatted requests and responses. When we first integrated with the company (called GlobalCollect at the time), we used an older API called WebCollect. This logic is still present in the globalcollect_gateway folder but should be deleted and the newer logic extricated (phab task).

Ingenico Connect was the first payment processor API we implemented in the SmashPig library. Many of those SmashPig methods required DonationInterface to structure the request arrays and format values, and did not normalize the responses. We have updated all of the methods used in recurring payment charges and the pending transaction resolver to return normalized values, but the Ingenico adapter in DonationInterface does not yet read the normalized properties.

Payment Methods

Credit Cards

Credit cards are available with payment_method=cc

Donor Flow

The donor fills in their contact information then chooses their card type by selecting one of the logos/radio buttons. This does a validation click on the above fields and if that passes the iframe loads with card fields. [picture here]

The card entered does not need to match the one selected before the iframe loaded.

Once the donor enters their card information in the iframe and presses the donate button, they are redirected to Special:IngenicoGatewayResult (still inside the iframe). This result page reloads itself in the top frame and on this second load captures the payment. When monthly convert is activated, the result page renders an overlay asking for a monthly donation on top of the donation form. If monthly convert is not activated, or after the donor has interacted with or closed the monthly convert overlay, the result page redirects the donor to the thank you page.

API Calls

When the donor selects a card type, their contact information is sent to our server. DonationInterface's IngenicoAdapter formats this information as defined in its transactions array and calls createHostedPayment on the SmashPig PaymentProvider object, which in turn POSTs to Ingenico's hostedcheckouts endpoint and receives a hostedCheckoutId and a URL to load in the iFrame. We store the hostedCheckoutId as 'gateway_session_id' in the donor's session and in a message we send to the pending queue before loading the iFrame.

Under the hosted checkouts integration, Ingenico performs an authorization as soon as the donor enters their card information, then redirects the donor to the Special:IngenicoGatewayResult URL we provided as 'returnUrl' in the above API call.

When the donor returns to our server, we query the status of the hosted checkout using the gateway_session_id stored in session. IngenicoAdapter calls getHostedPaymentStatus on the PaymentProvider object, which makes a GET request to hostedcheckouts/<gateway_session_id>. The values returned tell us whether the donor has entered their information or cancelled the transaction, whether the card authorization was successful, and the state of AVS and CVV fraud checks. They also give us an identifier for the created payment (distinct from the hostedCheckoutId). We store that identifier as gateway_txn_id.

We combine the AVS and CVV fraud results with other filters, and if the resulting score is low enough we capture the payment. IngenicoAdapter uses the gateway_txn_id to call approvePayment on the PaymentProvider object, which POSTs to payments/<gateway_txn_id>/approve. If that is successful, we send a message to the donations queue.

Recurring

Recurring payments are tokenized when created and charged on our schedule by the SmashPig Civi extension's recurring payment charge job.

Monthly Convert

Ingenico card payments have monthly convert available. This tokenizes all one time donations to add the ability for the donor to start an additional recurring donation with just one click (and not have to re-enter their card information).

Audits

see Fundraising/Data and flow/Audits