Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Reference Transaction Payment

Takeshi AKIMA edited this page · 5 revisions

Reference Transaction Payment

Official PayPal API document about Reference Transaction is here.

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 =
  :username   => SET_YOUR_OWN,
  :password   => SET_YOUR_OWN,
  :signature  => SET_YOUR_OWN
payment_request =
  :billing_type  => :MerchantInitiatedBilling,
  # Or ":billing_type => :MerchantInitiatedBillingSingleAgreement"
  # Read official document for details
  :billing_agreement_description => SET_YOUR_OWN
response = request.setup(

Assume the end-user approved the payment request on 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.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


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
Something went wrong with that request. Please try again.