The Chained Payments API allows you to split a payment amongst several parties. This is nice when customers want a percentage cut out of their Paypal sales.
1. Create and login to an account at http://developer.paypal.com
2. Navigate to Applications > Sandbox Accounts
3. A Business account will have been made for you. This will represent your client’s Paypal account. Make a buyer account as well, call it whatever you want.
4. Take note of your Business account’s API credentials. You can click on it in the list of accounts then go to Profile > API Credentials to get them.
5. Install ActiveMerchant and the Paypal adaptive payments adapter:[vc_column_text css=”.vc_custom_1413388010432{margin-top: 10px !important;margin-bottom: 10px !important;padding: 10px !important;border: 3px dashed #d3d3d3 !important;}”]gem 'activemerchant'
gem 'active_paypal_adaptive_payment'
6. You will want to setup some test configuration and most likely use it in all environments except production. It is also a good idea to make configuration for the buyer/seller e-mails, the clients account, etc. but I will be hardcoding it for this article.
Rails.application.default_url_options = Rails.application.config.action_mailer.default_url_optionsActiveMerchant::Billing::Base.mode = :testIf you haven’t set up your ActionMailer default URL options you probably should as it’s needed for Devise. If your application doesn’t need ActionMailer, just set it to a hash like normal.
7. I prefer to have a class called ChainedPayment but you can put this code wherever you see fit. I will just go through what you need to do in order to make a chained payment. You will first need to setup your gateway with ActiveMerchant:
def gateway @gateway ||= ActiveMerchant::Billing::PaypalAdaptivePayment.new login: '<your business account e-mail>', password: '<your business account password as shown under API credentials>', signature: '<your business account signature>', appid: 'APP-80W284485P519543T'endThe appid is important here, this is the Paypal sandbox app ID that is hardcoded into all sandboxes applications. Like I mentioned, it would be good to use configuration here to set this in only the sandboxes environments. Eventually in production, you will be changing this to the real application ID registered on Paypal.
8. Setup an array of payment recipients. This array will determine how the payment will be split
def recipients [ { email: 'recipient1@email.com', amount: recipient1_cut, primary: false }, { email: 'recipient2@email.com', amount: recipient2_cut, primary: false } ]endIn most cases, one of these will probably be your client. Also a good thing to note, these values are floats and in dollars, not cents. I have no idea why. Also, all recipients should be set as non-primary.
9. Call setup_purchase on your gateway. Since you are using the Paypal adaptive payment adapter, this will contact the Paypal API and do whatever it needs to do to prepare your purchase.
response = gateway.setup_purchase return_url: <success URL>, cancel_url: <failure URL>, ipn_notification_url: <notification URL>, receiver_list: recipientsThe notification URL is important, Paypal will be sending you information about the transaction to that URL. That is where you will verify and store the transaction in your local Rails DB. The other URLs (return/cancel) are just for flow.
10. Redirect the user to Paypal. The response variable saved in Step 9 has a valued in the ‘payKey’ hash key. You can use your gateway object and this key to generate a redirect URL and redirect to it:
redirect_to gateway.redirect_url_for(response['payKey'])11. At this point, the user is on Paypal and will complete the transaction there. For testing, you can use the buyer sandbox account made earlier to complete a purchase. When you finalize the payment, you should be redirected to the return_url that you setup in your gateway and likewise for cancellation.
12. Next you will need to handle Paypal IPN notifications, which tells you if a transaction was successful. This will be a simple example and you might need to do more to handle all the different kinds of statuses.
notification = ActiveMerchant::Billing::Integrations::PaypalAdaptivePayment::Notification.new(request.raw_post)if notification.acknowledge # finalize the paymentendhead :okTo prevent spoofing, Paypal recommends you post back their exact request to their server. ActiveMerchant has this built in, so all you need are these two lines. If acknowledge returns true, you can go ahead and do whatever you need to do to complete the payment (set a status to “paid”, or whatever). This method should respond with a blank 200 ( head :ok )
