Module: ActiveMerchant::Billing::PaypalCommonAPI

Includes:
Empty
Included in:
PaypalExpressGateway, PaypalGateway
Defined in:
lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb

Overview

This module is included in both PaypalGateway and PaypalExpressGateway

Constant Summary collapse

API_VERSION = 
'124'
API_VERSION_3DS2 = 
'214.0'
URLS = 
{
  :test => { :certificate => 'https://api.sandbox.paypal.com/2.0/',
             :signature   => 'https://api-3t.sandbox.paypal.com/2.0/' },
  :live => { :certificate => 'https://api.paypal.com/2.0/',
             :signature   => 'https://api-3t.paypal.com/2.0/' }
}
PAYPAL_NAMESPACE = 
'urn:ebay:api:PayPalAPI'
EBAY_NAMESPACE = 
'urn:ebay:apis:eBLBaseComponents'
ENVELOPE_NAMESPACES = 
{ 'xmlns:xsd' => 'http://www.w3.org/2001/XMLSchema',
  'xmlns:env' => 'http://schemas.xmlsoap.org/soap/envelope/',
  'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance'
}
CREDENTIALS_NAMESPACES = 
{ 'xmlns' => PAYPAL_NAMESPACE,
  'xmlns:n1' => EBAY_NAMESPACE,
  'env:mustUnderstand' => '0'
}
AUSTRALIAN_STATES = 
{
  'ACT' => 'Australian Capital Territory',
  'NSW' => 'New South Wales',
  'NT'  => 'Northern Territory',
  'QLD' => 'Queensland',
  'SA'  => 'South Australia',
  'TAS' => 'Tasmania',
  'VIC' => 'Victoria',
  'WA'  => 'Western Australia'
}
SUCCESS_CODES = 
[ 'Success', 'SuccessWithWarning' ]
FRAUD_REVIEW_CODE = 
"11610"
STANDARD_ERROR_CODE_MAPPING = 
{
  '15005' => :card_declined,
  '10754' => :card_declined,
  '10752' => :card_declined,
  '10759' => :card_declined,
  '10761' => :card_declined,
  '15002' => :card_declined,
  '11084' => :card_declined,
  '15004' => :incorrect_cvc,
  '10762' => :invalid_cvc,
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



58
59
60
61
62
63
64
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 58

def self.included(base)
  base.default_currency = 'USD'
  base.cattr_accessor :pem_file
  base.cattr_accessor :signature
  base.live_url = URLS[:live][:signature]
  base.test_url = URLS[:test][:signature]
end

Instance Method Details

#authorize_transaction(transaction_id, money, options = {}) ⇒ Object

DoAuthorization takes the transaction_id returned when you call DoExpressCheckoutPayment with a PaymentAction of ‘Order’. When you did that, you created an order authorization subject to settlement with PayPal DoAuthorization and DoCapture

Parameters:

  • :transaction_id – The ID returned by DoExpressCheckoutPayment with a PaymentAction of ‘Order’.

  • :money – The amount of money to be authorized for this purchase.



263
264
265
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 263

def authorize_transaction(transaction_id, money, options = {})
  commit 'DoAuthorization', build_do_authorize(transaction_id, money, options)
end

#balance(return_all_currencies = false) ⇒ Object

Parameters:

  • :return_all_currencies – Either ‘1’ or ‘0’

    0 – Return only the balance for the primary currency holding.
1 – Return the balance for each currency holding.



245
246
247
248
249
250
251
252
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 245

def balance(return_all_currencies = false)
  clean_currency_argument = case return_all_currencies
                            when 1, '1' , true; '1'
                            else
                              '0'
                            end
  commit 'GetBalance', build_get_balance(clean_currency_argument)
end

#capture(money, authorization, options = {}) ⇒ Object 



103
104
105
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 103

def capture(money, authorization, options = {})
  commit 'DoCapture', build_capture_request(money, authorization, options)
end

#credit(money, identification, options = {}) ⇒ Object 



141
142
143
144
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 141

def credit(money, identification, options = {})
  ActiveMerchant.deprecated Gateway::CREDIT_DEPRECATION_MESSAGE
  refund(money, identification, options)
end

#initialize(options = {}) ⇒ Object

The gateway must be configured with either your PayPal PEM file or your PayPal API Signature. Only one is required.

:pem The text of your PayPal PEM file. Note

this is not the path to file, but its
contents. If you are only using one PEM
file on your site you can declare it
globally and then you won't need to
include this option

:signature The text of your PayPal signature.

If you are only using one API Signature
on your site you can declare it
globally and then you won't need to
include this option



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 81

def initialize(options = {})
  requires!(options, :login, :password)

  headers = {'X-PP-AUTHORIZATION' => options.delete(:auth_signature), 'X-PAYPAL-MESSAGE-PROTOCOL' => 'SOAP11'} if options[:auth_signature]
  options = {
    :pem => pem_file,
    :signature => signature,
    :headers => headers || {}
  }.update(options)


  if options[:pem].blank? && options[:signature].blank?
    raise ArgumentError, "An API Certificate or API Signature is required to make requests to PayPal"
  end

  super(options)
end

#inquire(authorization, options = {}) ⇒ Object

For full documentation see Paypal API Reference:

Parameter:

  • :money – (Required) The amount of this new transaction,

required fo the payment details portion of this request

Options:

  • :reference_id – (Required) A transaction ID from a previous purchase, such as a credit card charge using the DoDirectPayment API, or a billing agreement ID.

  • :payment_action – (Optional) How you want to obtain payment. It is one of the following values:

    Authorization – This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.
Sale – This is a final sale for which you are requesting payment.

  • :ip_address – (Optional) IP address of the buyer’s browser.

Note: PayPal records this IP addresses as a means to detect possible fraud.

  • :req_confirm_shipping – Whether you require that the buyer’s shipping address on file with PayPal be a confirmed address. You must have permission from PayPal to not require a confirmed address. It is one of the following values:

    0 – You do not require that the buyer’s shipping address be a confirmed address.
1 – You require that the buyer’s shipping address be a confirmed address.

  • :merchant_session_id – (Optional) Your buyer session identification token.

  • :return_fmf_details – (Optional) Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. It is one of the following values:

    0 – Do not receive FMF details (default)
1 – Receive FMF details

  • :soft_descriptor – (Optional) Per transaction description of the payment that is passed to the consumer’s credit card statement. If the API request provides a value for the soft descriptor field, the full descriptor displayed on the buyer’s statement has the following format:

    <PP * | PAYPAL *><Merchant descriptor as set in the Payment Receiving Preferences><1 space><soft descriptor>
The soft descriptor can contain only the following characters:

Alphanumeric characters
- (dash)
* (asterisk)
. (period)
{space}



183
184
185
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 183

def inquire(authorization, options = {})
  transaction_details(authorization)
end

#manage_pending_transaction(transaction_id, action) ⇒ Object

The ManagePendingTransactionStatus API operation accepts or denies a pending transaction held by Fraud Management Filters.

Parameters:

  • :transaction_id – The ID of the transaction held by Fraud Management Filters.

  • :action – Either ‘Accept’ or ‘Deny’



274
275
276
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 274

def manage_pending_transaction(transaction_id, action)
  commit 'ManagePendingTransactionStatus', build_manage_pending_transaction_status(transaction_id, action)
end

#reauthorize(money, authorization, options = {}) ⇒ Object 



99
100
101
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 99

def reauthorize(money, authorization, options = {})
  commit 'DoReauthorization', build_reauthorize_request(money, authorization, options)
end

#reference_transaction(money, options = {}) ⇒ Object 



187
188
189
190
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 187

def reference_transaction(money, options = {})
  requires!(options, :reference_id)
  commit 'DoReferenceTransaction', build_reference_transaction_request(money, options)
end

#refund(money, identification, options = {}) ⇒ Object

Refunds a transaction.

For a full refund pass nil for the amount:

gateway.refund nil, 'G39883289DH238'

This will automatically make the :refund_type be “Full”.

For a partial refund just pass the amount as usual:

gateway.refund 100, 'UBU83983N920'



137
138
139
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 137

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

#scrub(transcript) ⇒ Object 



282
283
284
285
286
287
288
289
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 282

def scrub(transcript)
  transcript.
    gsub(%r((<n1:Password>).+(</n1:Password>)), '\1[FILTERED]\2').
    gsub(%r((<n1:Username>).+(</n1:Username>)), '\1[FILTERED]\2').
    gsub(%r((<n1:Signature>).+(</n1:Signature>)), '\1[FILTERED]\2').
    gsub(%r((<n2:CreditCardNumber>).+(</n2:CreditCardNumber)), '\1[FILTERED]\2').
    gsub(%r((<n2:CVV2>)\d+(</n2:CVV2)), '\1[FILTERED]\2')
end

#supports_scrubbing? ⇒ Boolean

Returns:

  • (Boolean) 


278
279
280
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 278

def supports_scrubbing?
  true
end

#transaction_details(transaction_id) ⇒ Object 



192
193
194
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 192

def transaction_details(transaction_id)
  commit 'GetTransactionDetails', build_get_transaction_details(transaction_id)
end

#transaction_search(options) ⇒ Object

For full documentation see PayPal API Reference

Options:

  • :payer – (Optional) Search by the buyer’s email address.

  • :receipt_id – (Optional) Search by the PayPal Account Optional receipt ID.

  • :receiver – (Optional) Search by the receiver’s email address. If the merchant account has only one email address, this is the primary email. It can also be a non-primary email address.

  • :transaction_id – (Optional) Search by the transaction ID. The returned results are from the merchant’s transaction records.

  • :invoice_id – (Optional) Search by invoice identification key, as set by you for the original transaction. This field searches the records for items the merchant sells, not the items purchased.

  • :card_number – (Optional) Search by credit card number, as set by you for the original transaction. This field searches the records for items the merchant sells, not the items purchased.

  • :auction_item_number – (Optional) Search by auction item number of the purchased goods.

  • :transaction_class – (Optional) Search by classification of transaction. Some kinds of possible classes of transactions are not searchable with this field. You cannot search for bank transfer withdrawals, for example. It is one of the following values:

    All – All transaction classifications
Sent – Only payments sent
Received – Only payments received
MassPay – Only mass payments
MoneyRequest – Only money requests
FundsAdded – Only funds added to balance
FundsWithdrawn – Only funds withdrawn from balance
Referral – Only transactions involving referrals
Fee – Only transactions involving fees
Subscription – Only transactions involving subscriptions
Dividend – Only transactions involving dividends
Billpay – Only transactions involving BillPay Transactions
Refund – Only transactions involving funds
CurrencyConversions – Only transactions involving currency conversions
BalanceTransfer – Only transactions involving balance transfers
Reversal – Only transactions involving BillPay reversals
Shipping – Only transactions involving UPS shipping fees
BalanceAffecting – Only transactions that affect the  balance
ECheck – Only transactions involving eCheck

  • :currency_code – (Optional) Search by currency code.

  • :status – (Optional) Search by transaction status. It is one of the following values:

    One of:
Pending – The payment is pending. The specific reason the payment is pending is returned by the GetTransactionDetails API PendingReason field.
Processing – The payment is being processed.
Success – The payment has been completed and the funds have been added successfully to your account balance.
Denied – You denied the payment. This happens only if the payment was previously pending.
Reversed – A payment was reversed due to a chargeback or other type of reversal. The funds have been removed from your account balance and returned to the buyer.



235
236
237
238
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 235

def transaction_search(options)
  requires!(options, :start_date)
  commit 'TransactionSearch', build_transaction_search(options)
end

#transfer(*args) ⇒ Object

Transfer money to one or more recipients.

gateway.transfer 1000, '[email protected]',
  :subject => "The money I owe you", :note => "Sorry it's so late"

gateway.transfer [1000, '[email protected]'],
  [2450, '[email protected]', :note => 'You will receive another payment on 3/24'],
  [2000, '[email protected]'],
  :subject => "Your Earnings", :note => "Thanks for your business."



117
118
119
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 117

def transfer(*args)
  commit 'MassPay', build_mass_pay_request(*args)
end

#void(authorization, options = {}) ⇒ Object 



121
122
123
 
# File 'lib/active_merchant/billing/gateways/paypal/paypal_common_api.rb', line 121

def void(authorization, options = {})
  commit 'DoVoid', build_void_request(authorization, options)
end