# coding=utf-8 """ The end developer will do most of their work with the PayPalInterface class found in this module. Configuration, querying, and manipulation can all be done with it. """ import types import logging from pprint import pformat import warnings import requests from paypal.settings import PayPalConfig from paypal.response import PayPalResponse from paypal.response_list import PayPalResponseList from paypal.exceptions import (PayPalError, PayPalAPIResponseError, PayPalConfigError) from paypal.compat import is_py3 if is_py3: #noinspection PyUnresolvedReferences from urllib.parse import urlencode else: from urllib import urlencode logger = logging.getLogger('paypal.interface') class PayPalInterface(object): __credentials = ['USER', 'PWD', 'SIGNATURE', 'SUBJECT'] """ The end developers will do 95% of their work through this class. API queries, configuration, etc, all go through here. See the __init__ method for config related details. """ def __init__(self, config=None, **kwargs): """ Constructor, which passes all config directives to the config class via kwargs. For example: paypal = PayPalInterface(API_USERNAME='somevalue') Optionally, you may pass a 'config' kwarg to provide your own PayPalConfig object. """ if config: # User provided their own PayPalConfig object. self.config = config else: # Take the kwargs and stuff them in a new PayPalConfig object. self.config = PayPalConfig(**kwargs) def _encode_utf8(self, **kwargs): """ UTF8 encodes all of the NVP values. """ if is_py3: # This is only valid for Python 2. In Python 3, unicode is # everywhere (yay). return kwargs unencoded_pairs = kwargs for i in unencoded_pairs.keys(): #noinspection PyUnresolvedReferences if isinstance(unencoded_pairs[i], types.UnicodeType): unencoded_pairs[i] = unencoded_pairs[i].encode('utf-8') return unencoded_pairs def _check_required(self, requires, **kwargs): """ Checks kwargs for the values specified in 'requires', which is a tuple of strings. These strings are the NVP names of the required values. """ for req in requires: # PayPal api is never mixed-case. if req.lower() not in kwargs and req.upper() not in kwargs: raise PayPalError('missing required : %s' % req) def _sanitize_locals(self, data): """ Remove the 'self' key in locals() It's more explicit to do it in one function """ if 'self' in data: data = data.copy() del data['self'] return data def _call(self, method, **kwargs): """ Wrapper method for executing all API commands over HTTP. This method is further used to implement wrapper methods listed here: https://www.x.com/docs/DOC-1374 ``method`` must be a supported NVP method listed at the above address. ``kwargs`` the actual call parameters """ post_params = self._get_call_params(method, **kwargs) payload = post_params['data'] api_endpoint = post_params['url'] # This shows all of the key/val pairs we're sending to PayPal. if logger.isEnabledFor(logging.DEBUG): logger.debug('PayPal NVP Query Key/Vals:\n%s' % pformat(payload)) http_response = requests.post(**post_params) response = PayPalResponse(http_response.text, self.config) logger.debug('PayPal NVP API Endpoint: %s' % api_endpoint) if not response.success: raise PayPalAPIResponseError(response) return response def _get_call_params(self, method, **kwargs): """ Returns the prepared call parameters. Mind, these will be keyword arguments to ``requests.post``. ``method`` the NVP method ``kwargs`` the actual call parameters """ payload = {'METHOD': method, 'VERSION': self.config.API_VERSION} certificate = None if self.config.API_AUTHENTICATION_MODE == "3TOKEN": payload['USER'] = self.config.API_USERNAME payload['PWD'] = self.config.API_PASSWORD payload['SIGNATURE'] = self.config.API_SIGNATURE elif self.config.API_AUTHENTICATION_MODE == "CERTIFICATE": payload['USER'] = self.config.API_USERNAME payload['PWD'] = self.config.API_PASSWORD certificate = (self.config.API_CERTIFICATE_FILENAME, self.config.API_KEY_FILENAME) elif self.config.API_AUTHENTICATION_MODE == "UNIPAY": payload['SUBJECT'] = self.config.UNIPAY_SUBJECT none_configs = [config for config, value in payload.items() if value is None] if none_configs: raise PayPalConfigError( "Config(s) %s cannot be None. Please, check this " "interface's config." % none_configs) # all keys in the payload must be uppercase for key, value in kwargs.items(): payload[key.upper()] = value return {'data': payload, 'cert': certificate, 'url': self.config.API_ENDPOINT, 'timeout': self.config.HTTP_TIMEOUT, 'verify': self.config.API_CA_CERTS} def address_verify(self, email, street, zip): """Shortcut for the AddressVerify method. ``email``:: Email address of a PayPal member to verify. Maximum string length: 255 single-byte characters Input mask: ?@?.?? ``street``:: First line of the billing or shipping postal address to verify. To pass verification, the value of Street must match the first three single-byte characters of a postal address on file for the PayPal member. Maximum string length: 35 single-byte characters. Alphanumeric plus - , . ‘ # \ Whitespace and case of input value are ignored. ``zip``:: Postal code to verify. To pass verification, the value of Zip mustmatch the first five single-byte characters of the postal code of the verified postal address for the verified PayPal member. Maximumstring length: 16 single-byte characters. Whitespace and case of input value are ignored. """ args = self._sanitize_locals(locals()) return self._call('AddressVerify', **args) def create_recurring_payments_profile(self, **kwargs): """Shortcut for the CreateRecurringPaymentsProfile method. Currently, this method only supports the Direct Payment flavor. It requires standard credit card information and a few additional parameters related to the billing. e.g.: profile_info = { # Credit card information 'creditcardtype': 'Visa', 'acct': '4812177017895760', 'expdate': '102015', 'cvv2': '123', 'firstname': 'John', 'lastname': 'Doe', 'street': '1313 Mockingbird Lane', 'city': 'Beverly Hills', 'state': 'CA', 'zip': '90110', 'countrycode': 'US', 'currencycode': 'USD', # Recurring payment information 'profilestartdate': '2010-10-25T0:0:0', 'billingperiod': 'Month', 'billingfrequency': '6', 'amt': '10.00', 'desc': '6 months of our product.' } response = create_recurring_payments_profile(**profile_info) The above NVPs compose the bare-minimum request for creating a profile. For the complete list of parameters, visit this URI: https://www.x.com/docs/DOC-1168 """ return self._call('CreateRecurringPaymentsProfile', **kwargs) def do_authorization(self, transactionid, amt): """Shortcut for the DoAuthorization method. Use the TRANSACTIONID from DoExpressCheckoutPayment for the ``transactionid``. The latest version of the API does not support the creation of an Order from `DoDirectPayment`. The `amt` should be the same as passed to `DoExpressCheckoutPayment`. Flow for a payment involving a `DoAuthorization` call:: 1. One or many calls to `SetExpressCheckout` with pertinent order details, returns `TOKEN` 1. `DoExpressCheckoutPayment` with `TOKEN`, `PAYMENTACTION` set to Order, `AMT` set to the amount of the transaction, returns `TRANSACTIONID` 1. `DoAuthorization` with `TRANSACTIONID` and `AMT` set to the amount of the transaction. 1. `DoCapture` with the `AUTHORIZATIONID` (the `TRANSACTIONID` returned by `DoAuthorization`) """ args = self._sanitize_locals(locals()) return self._call('DoAuthorization', **args) def do_capture(self, authorizationid, amt, completetype='Complete', **kwargs): """Shortcut for the DoCapture method. Use the TRANSACTIONID from DoAuthorization, DoDirectPayment or DoExpressCheckoutPayment for the ``authorizationid``. The `amt` should be the same as the authorized transaction. """ kwargs.update(self._sanitize_locals(locals())) return self._call('DoCapture', **kwargs) def do_direct_payment(self, paymentaction="Sale", **kwargs): """Shortcut for the DoDirectPayment method. ``paymentaction`` could be 'Authorization' or 'Sale' To issue a Sale immediately:: charge = { 'amt': '10.00', 'creditcardtype': 'Visa', 'acct': '4812177017895760', 'expdate': '012010', 'cvv2': '962', 'firstname': 'John', 'lastname': 'Doe', 'street': '1 Main St', 'city': 'San Jose', 'state': 'CA', 'zip': '95131', 'countrycode': 'US', 'currencycode': 'USD', } direct_payment("Sale", **charge) Or, since "Sale" is the default: direct_payment(**charge) To issue an Authorization, simply pass "Authorization" instead of "Sale". You may also explicitly set ``paymentaction`` as a keyword argument: ... direct_payment(paymentaction="Sale", **charge) """ kwargs.update(self._sanitize_locals(locals())) return self._call('DoDirectPayment', **kwargs) def do_void(self, **kwargs): """Shortcut for the DoVoid method. Use the TRANSACTIONID from DoAuthorization, DoDirectPayment or DoExpressCheckoutPayment for the ``AUTHORIZATIONID``. Required Kwargs --------------- * AUTHORIZATIONID """ return self._call('DoVoid', **kwargs) def get_express_checkout_details(self, **kwargs): """Shortcut for the GetExpressCheckoutDetails method. Required Kwargs --------------- * TOKEN """ return self._call('GetExpressCheckoutDetails', **kwargs) def get_transaction_details(self, **kwargs): """Shortcut for the GetTransactionDetails method. Use the TRANSACTIONID from DoAuthorization, DoDirectPayment or DoExpressCheckoutPayment for the ``transactionid``. Required Kwargs --------------- * TRANSACTIONID """ return self._call('GetTransactionDetails', **kwargs) def transaction_search(self, **kwargs): """Shortcut for the TransactionSearch method. Returns a PayPalResponseList object, which merges the L_ syntax list to a list of dictionaries with properly named keys. Note that the API will limit returned transactions to 100. Required Kwargs --------------- * STARTDATE Optional Kwargs --------------- STATUS = one of ['Pending','Processing','Success','Denied','Reversed'] """ plain = self._call('TransactionSearch', **kwargs) return PayPalResponseList(plain.raw, self.config) def set_express_checkout(self, **kwargs): """Start an Express checkout. You'll want to use this in conjunction with :meth:`generate_express_checkout_redirect_url` to create a payment, then figure out where to redirect the user to for them to authorize the payment on PayPal's website. Required Kwargs --------------- * PAYMENTREQUEST_0_AMT * PAYMENTREQUEST_0_PAYMENTACTION * RETURNURL * CANCELURL """ return self._call('SetExpressCheckout', **kwargs) def refund_transaction(self, transactionid=None, payerid=None, **kwargs): """Shortcut for RefundTransaction method. Note new API supports passing a PayerID instead of a transaction id, exactly one must be provided. Optional: INVOICEID REFUNDTYPE AMT CURRENCYCODE NOTE RETRYUNTIL REFUNDSOURCE MERCHANTSTOREDETAILS REFUNDADVICE REFUNDITEMDETAILS MSGSUBID MERCHANSTOREDETAILS has two fields: STOREID TERMINALID """ # This line seems like a complete waste of time... kwargs should not # be populated if (transactionid is None) and (payerid is None): raise PayPalError( 'RefundTransaction requires either a transactionid or ' 'a payerid') if (transactionid is not None) and (payerid is not None): raise PayPalError( 'RefundTransaction requires only one of transactionid %s ' 'and payerid %s' % (transactionid, payerid)) if transactionid is not None: kwargs['TRANSACTIONID'] = transactionid else: kwargs['PAYERID'] = payerid return self._call('RefundTransaction', **kwargs) def do_express_checkout_payment(self, **kwargs): """Finishes an Express checkout. TOKEN is the token that was returned earlier by :meth:`set_express_checkout`. This identifies the transaction. Required -------- * TOKEN * PAYMENTACTION * PAYERID * AMT """ return self._call('DoExpressCheckoutPayment', **kwargs) def generate_express_checkout_redirect_url(self, token, useraction=None): """Returns the URL to redirect the user to for the Express checkout. Express Checkouts must be verified by the customer by redirecting them to the PayPal website. Use the token returned in the response from :meth:`set_express_checkout` with this function to figure out where to redirect the user to. The button text on the PayPal page can be controlled via `useraction`. The documented possible values are `commit` and `continue`. However, any other value will only result in a warning. :param str token: The unique token identifying this transaction. :param str useraction: Control the button text on the PayPal page. :rtype: str :returns: The URL to redirect the user to for approval. """ url_vars = (self.config.PAYPAL_URL_BASE, token) url = "%s?cmd=_express-checkout&token=%s" % url_vars if useraction: if not useraction.lower() in ('commit', 'continue'): warnings.warn('useraction=%s is not documented' % useraction, RuntimeWarning) url += '&useraction=%s' % useraction return url def generate_cart_upload_redirect_url(self, **kwargs): """https://www.sandbox.paypal.com/webscr ?cmd=_cart &upload=1 """ required_vals = ('business', 'item_name_1', 'amount_1', 'quantity_1') self._check_required(required_vals, **kwargs) url = "%s?cmd=_cart&upload=1" % self.config.PAYPAL_URL_BASE additional = self._encode_utf8(**kwargs) additional = urlencode(additional) return url + "&" + additional def get_recurring_payments_profile_details(self, profileid): """Shortcut for the GetRecurringPaymentsProfile method. This returns details for a recurring payment plan. The ``profileid`` is a value included in the response retrieved by the function ``create_recurring_payments_profile``. The profile details include the data provided when the profile was created as well as default values for ignored fields and some pertinent stastics. e.g.: response = create_recurring_payments_profile(**profile_info) profileid = response.PROFILEID details = get_recurring_payments_profile(profileid) The response from PayPal is somewhat self-explanatory, but for a description of each field, visit the following URI: https://www.x.com/docs/DOC-1194 """ args = self._sanitize_locals(locals()) return self._call('GetRecurringPaymentsProfileDetails', **args) def manage_recurring_payments_profile_status(self, profileid, action, note=None): """Shortcut to the ManageRecurringPaymentsProfileStatus method. ``profileid`` is the same profile id used for getting profile details. ``action`` should be either 'Cancel', 'Suspend', or 'Reactivate'. ``note`` is optional and is visible to the user. It contains the reason for the change in status. """ args = self._sanitize_locals(locals()) if not note: del args['note'] return self._call('ManageRecurringPaymentsProfileStatus', **args) def update_recurring_payments_profile(self, profileid, **kwargs): """Shortcut to the UpdateRecurringPaymentsProfile method. ``profileid`` is the same profile id used for getting profile details. The keyed arguments are data in the payment profile which you wish to change. The profileid does not change. Anything else will take the new value. Most of, though not all of, the fields available are shared with creating a profile, but for the complete list of parameters, you can visit the following URI: https://www.x.com/docs/DOC-1212 """ kwargs.update(self._sanitize_locals(locals())) return self._call('UpdateRecurringPaymentsProfile', **kwargs) def bm_create_button(self, **kwargs): """Shortcut to the BMButtonSearch method. See the docs for details on arguments: https://cms.paypal.com/mx/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_BMCreateButton The L_BUTTONVARn fields are especially important, so make sure to read those and act accordingly. See unit tests for some examples. """ kwargs.update(self._sanitize_locals(locals())) return self._call('BMCreateButton', **kwargs)