Ways of Handling PayPal Refunds in Rails

PayPal Checkout includes payment solutions ranging from simple to robust that let the merchants as well as developers choose an integration option that can be the best-suited for their website and customers.

In order to integrate Paypal Payment Gateway, we need to do the following:

1. Have a PayPal business or Premier account.
2. Create a PayPal app and get an access token. When we create a PayPal app, PayPal generates a set of OAuth client_id and secret keys for the application. PayPal generates these keys for both the PayPal sandbox and Live environments. To get an access token, pass the client-id:secret credentials in the Authorization header. We use the access token for authentication when we make REST API requests.
3. To perform an end-to-end test of our Express Checkout with In-Context integration, create both merchant and buyer accounts in the PayPal sandbox environment.
https://www.sandbox.paypal.com/in/webapps/mpp/home
Merchant : Select the Business account type and enter an email address and password.
Buyer : Select the Personal account type and enter a high PayPal balance, such as 5000.

Once we create Paypal sandbox account then click on the “Profile” link for that account, look under the tab “API Credentials”. We will have the following information;

• Paypal API Username
• Paypal API Signature
• Paypal API Password

Note: When we are ready to go live we would just use the credentials from our real paypal account instead of the ones from our sandbox account. The credentials can be found in the “My Profile” area under the left hand tab “My Selling Tools” under the option “API access”

How to handle Paypal refunds in Rails:

Method 1:

Paypal Rest API;

For more complex merchant sites, direct calls to PayPal APIs for an Express Checkout integration may be a more appropriate integration.
REST APIs — We can develop an Express Checkout integration using PayPal REST APIs.

To integrate the Express Checkout with In-Context flow;
https://developer.paypal.com/docs/api/
OR
PayPal REST API Ruby SDK (paypal-sdk-rest gem):
The PayPal REST SDK provides Ruby APIs to create, process and manage payment.

Installation:
Add the gem our application, in Gemfile:

gem 'paypal-sdk-rest'

And then execute:

$ bundle install

Configuration:

rails g paypal:sdk:install

Refunds a transaction:
Any transaction we can issue a refund (Both direct and captured payments):

• Refund a completed direct payment (sale)
• Refund an authorized and captured payment (capture)

Refund a completed payment (sale):
If we must refund a completed payment, or sale, provide the sale id given to us in response to a completed payment along with an empty JSON payload for a full refund and for partial refunds, we can instead include an amount object in the JSON payload.

curl -v https://api.sandbox.paypal.com/v1/payments/sale/CARMAXYZC6136044L/refund 
-H "Content-Type:application/json" 
-H "Authorization: Bearer Access-Token" 
-d '{}'

Note: We should substitute all call-specific parameters, such as tokens and IDs, with our own.
Response state of the refund:

• pending- The refund is pending.
• completed- The refund has successfully completed.
• failed- The refund failed.

Refund a captured payment;
We can also refund a captured payment:

API: https://api.paypal.com/v1/payments/capture/{capture_id}/refund

 

Note: We must provide an amount object for both full and partial refunds.

curl -v https://api.sandbox.paypal.com/v1/payments/capture/CARMAXYZC6136044L/refund 
-H "Content-Type:application/json" 
-H "Authorization: Bearer Access-Token" 
-d '{
"amount":
{
"currency": "USD",
"total": "50.54"
},
"description": "This is the capture refund description."
}'

Reference: https://developer.paypal.com

Method 2:

Paypal refund by using Active Merchant Gem:

ActiveMerchant Integration: http://railscasts.com/episodes/145-integrating-active-merchant

In our Application;

config/environment/development.rb

config.after_initialize do
ActiveMerchant::Billing::Base.mode = :test
::GATEWAY = ActiveMerchant::Billing::PaypalGateway.new(
:login => "seller_1229899173_biz_api1.xyz.com",
:password => "FXWU58S7KXFC6HBE",
:signature => “AGjv6SW.mTiKxtkm6L9DcSUCUgePAUDQ3L-kTdszkPG8mRfjaRZDYtSu"
)
end

Refunds a transaction:
Take a look into paypal_common_api.rb file in Active Merchant Gem;
https://github.com/activemerchant/active_merchant/blob/master/lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb

1. For a full refund pass nil for the amount:

gateway.refund nil, 'CARMAXYZC6136044L'

This will automatically make the :refund_type be “Full”.
2. For a partial refund just pass the amount as usual:

gateway.refund 100, 'CARMAXYZC6136044L'

def refund(money, identification, options = {})
commit 'RefundTransaction', build_refund_request(money, identification, options)
end

Ex:

Gateway.refund(nil,'CARMAXYZC6136044L') => Full Refund.

Gateway.refund(798,'CARMAXYZC6136044L') => Partial Refund.

Reference: http://www.rubydoc.info/github/Shopify/active_merchant/ActiveMerchant/Billing/PaypalCommonAPI

Method 3:

Using Braintree Gem;

Braintree Integration:

• Sign up for a Braintree Sandbox account.
  https://www.braintreepayments.com/sandbox
• Follow the tutorials;
  https://developers.braintreepayments.com/start/hello-server/ruby
• Configure the environment and API credentials:

  Braintree::Configuration.environment = :sandbox
  Braintree::Configuration.merchant_id = "use_your_merchant_id"
  Braintree::Configuration.public_key = "use_your_public_key"
  Braintree::Configuration.private_key = "use_your_private_key"

• Complete the integration and sandbox testing.

Requirements:

• Transaction status must be settled or settling.
• Refund amount cannot be greater than remaining non-refunded amount of the original transaction.
• Transaction cannot be refunded again after being completely refunded.

Refunds a transaction:
To issue a refund with the API, we only need to run a Transaction.refund() API request and only requires a transaction_id to refund. Optionally, we may pass a refund amount if there is a requirement for partial refund, and we can pass an order_id if it is different than the original order ID.

result = Braintree::Transaction.refund("the_transaction_id")

Full refund:

result = Braintree::Transaction.refund("CARMAXYZC6136044L", nil)

Partial refund:

result = Braintree::Transaction.refund("CARMAXYZC6136044L", "40.00")

result.success?
#=> true
result.transaction.amount.to_f
#=> 40.00

Note: Only full refunds are allowed for transactions being held in Escrow (Hold a sub-merchant’s transaction funds until we make an additional call to release them). A partial refund of an Escrow transaction will throw a validation error.
https://developers.braintreepayments.com/guides/braintree-marketplace/create/ruby#holding-funds-in-escrow