Reference Transaction Payment

Reference Transaction Payment

Official PayPal API document about Reference Transaction is here.
https://cms.paypal.com/cms_content/US/en_US/files/developer/PP_EnterpriseExpressCheckout_AdvancedFeaturesGuide.pdf

To use this feature, you need to make contract with PayPal.
Contact to PayPal for details.

Setup transaction

Call SetExpressCheckout using this code and let user redirect to the given redirect URI.

request = Paypal::Express::Request.new(
  :username   => SET_YOUR_OWN,
  :password   => SET_YOUR_OWN,
  :signature  => SET_YOUR_OWN
)
payment_request = Paypal::Payment::Request.new(
  :billing_type  => :MerchantInitiatedBilling,
  # Or ":billing_type => :MerchantInitiatedBillingSingleAgreement"
  # Read official document for details
  :billing_agreement_description => SET_YOUR_OWN
)
response = request.setup(
  payment_request,
  YOUR_SUCCESS_CALBACK_URL,
  YOUR_CANCEL_CALBACK_URL
)
response.redirect_uri

Assume the end-user approved the payment request on PayPal.com and redirect back to your site.
In the redirect back request, you get token in query string.

Create Reference Transaction Agreement

Call CreateBillingAgreement using this code.

response = request.agree! token
# inspect this attribute for more details
response.billing_agreement
response.billing_agreement.identifier # => billing_agreement_id

Get agreement details

You can get reference transaction agreement details anytime.
Call BillAgreementUpdate using this code.

NOTE: The API method is BillAgreementUpdate, but actually it is just Fetching.

response = request.agreement billing_agreement_id
# inspect this attribute for more details
response.billing_agreement

Charge

Once you got a billing agreement (represented by reference_id), you can charge money anytime.
Since there are no “Schedule” which Recurring payment has, you need to call DoReferenceTransaction each time you charge.

request.charge! billing_agreement_id, 100 # Charge $100
request.charge! billing_agreement_id, 100, :currency_code => :JPY # Charge ¥100

Revoke agreement

Call BillAgreementUpdate using this code.

NOTE: Here, it is actually Updating status as Canceled.

request.revoke! billing_agreement_id