Jump to content

Fundraising/Data and flow/IPN listener

From Wikitech

Overview

Many payment processors send realtime updates on the state of payments to a listener endpoint on the merchant's servers. We refer to these messages as Instant Payment Notifications (IPNs), following PayPal's terminology. For some of our providers the IPNs are an essential part of the normal payments flow while for others they serve as a second opportunity to capture information about donations in case of problems sending the information from payments-wiki.

Adyen

Adyen sends us IPNs on payment authorization and capture as well as when a new report is available. The IPN listener sends a RecordCaptureJob to the jobs-adyen queue with payment details when a payment is complete (the Capture message for cards, or the Authorization message for iDEAL). The RecordCaptureJob will then combine the payment information with information from the pending table and send it along to the donations queue. When a new report is available, the IPN listener sends a DownloadReportJob to the jobs-adyen queue, which downloads the report to the incoming audits folder.

Amazon

Amazon sends us IPNs for authorizations, captured payments and refunds. For captured payments the IPN listener sends a RecordPaymentJob to the jobs-amazon queue which combines information from the pending table with the IPN info to send to the donations queue. When the pending table entry is missing, the RecordPaymentJob will look up donor name, email, and address from the Amazon Pay API.

Braintree

WIP

PayPal

Paypal sends us IPNs on Payment, Recurring, Refund, and Subscription transactions. The full list of IPN messages can be found here on Paypal's website. However, we only listen to a subset of the messages, you can find the list on Smashpig Paypal config yaml file under each message type.

Running IPN Listeners locally

Braintree

To test out receiving Braintree IPNs, you need to do the following:

  • Code:
    • pull down the latest on Smash0pig
    • pull down the latest on fundraising-dev
    • pull down the latest on config-private
  • Local Docker Updates: Update the Apache config on your fundraising-dev SmashPig container to listen for braintree traffic:
    • docker-compose exec -u root smashpig bash // you need to be root
    • open /etc/apache2/sites-enabled/000-default.conf in your preferred text editor and add the rule RewriteRule ^/braintree /smashpig_http_handler.php?p=braintree/listener [L,QSA] to the end of the RewriteRules list
    • whilst on the SmashPig container, run service apache2 reload to load in the config update.
    • navigate to http://localhost:9006/braintree, and you should have a blank page returning a 200 response if it worked. If that doesn't work as expected, try http://localhost:9006/adyen just to confirm the IPN server is running.
  • Enable remote tunnel Recieve IPNs from the Braintree sandbox
  • Perform an IPN test using the Braintree Sandbox console
    • Head over to https://sandbox.braintreegateway.com/merchants/ms9fqmw9gxrm2bp3/webhooks and create a webhook endpoint for your paymentsipntest URL. You should see the one I've been using, https://paymentsipntest2.wmcloud.org/braintree?XDEBUG_SESSION_START=PHPSTORM (the additional query param is to enable xdebug on demand)
    • Enable a few sample webhook notifications and then click Check URL to trigger an IPN message to be sent to your local machine.
    • To confirm, you can either xdebug the incoming request or you can also monitor your local redis queue. If the IPN is processed successfully, you should have a new queue message on the jobs-braintree queue. An easy way to watch for this is to run docker-compose exec queues redis-cli monitor and this will open up your redis-cli and listen for queue traffic.

Braintree - PayPal

To test out receiving PayPal IPNs, you need to do the following:

  • Code:
    • pull down the latest on Smash-pig
    • pull down the latest on fundraising-dev
    • pull down the latest on config-private
  • Local Docker Updates: Update the Apache config on your fundraising-dev SmashPig container to listen for braintree traffic:
  • Enable remote tunnel Recieve IPNs from the Braintree sandbox
    • Check out your tunnel config and switch yours on using the proxy-forward script in fundraising-dev. Head to your https://paymentsipntest${tunneling_id}.wmcloud.org/paypal address.
  • Perform an IPN test using the Braintree Sandbox console
    • Head over to https://www.sandbox.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-ipn-notify, login with the fr-tech-facilitator account and update the Notification URL with your paymentsipntest Paypal URL (https://paymentsipntest${tunneling_id}.wmcloud.org/paypal ).
    • To confirm, you can either xdebug the incoming request or you can also monitor your local redis queue. If the IPN is processed successfully, you should have a new queue message on the jobs-paypal queue. An easy way to watch for this is to run docker-compose exec queues redis-cli monitor and this will open up your redis-cli and listen for queue traffic.

Dlocal

To test out receiving Dlocal IPNs, you need to do the following:

  • Code:
    • pull down the latest on Smash-pig
    • pull down the latest on fundraising-dev
    • pull down the latest on config-private
  • Local Docker Updates:
    • navigate to http://localhost:9006/dlocal, and you should have a 500 response if it worked. There will also be an error message in the smashpig-syslog as an Authorization header is required. If that doesn't work as expected, try http://localhost:9006/adyen just to confirm the IPN server is running.
  • Enable remote tunnel Receive IPNs from the Dlocal sandbox
  • Perform an IPN test by making a test donation.

Adyen

To test out receiving Adyen IPNs, you need to do the following:

  • Code:
    • pull down the latest on Smash-pig
    • pull down the latest on fundraising-dev
    • pull down the latest on config-private
  • Local Docker Updates:
    • Navigating to http://localhost:9006/adyen should render a blank page with a 200 status in the network tab. This confirms the IPN server is running.
  • Enable remote tunnel Receive IPNs from the AstroPay sandbox
  • Perform an IPN test by sending a test notification from the Adyen test console
    • Head over to https://ca-test.adyen.com/ login with your SandBox account and and navigate to the Adyen notifications page. Update the Webhooks list with your paymentsipntest Adyen URL (https://paymentsipntest${tunneling_id}.wmcloud.org/adyen).
    • To confirm, you can either xdebug the incoming request or you can also monitor your local redis queue. An easy way to watch for this is to set a breakpoint in the Adyen Listener class and then click on Test Configuration on the console. If everything is set up correctly, you should get a hit on the breakpoint in seconds.