Forum OpenACS Q&A: ACS Service Contract questions (for a PayPal gateway)

Hi all,

Since I'm only now starting with service contracts, I've decided to submit my thoughts to the community to make sure I'm looking at this right, and also to try to solve some questions.

So I'm writing a service contract for a Paypal payment gateway (along with its implementation). The way I need to do this, the customer will be given the choice, at checkout time, as to what payment method s/he wants to use (s/he will be presented with a list of available payments, registered through the appropriate service contracts in the ecommerce package). That choice will be saved for future purchases, if the user so desires.

To give a little background, what needs to happen for Paypal authorization to happen is this:

  • Send customer paypal acct, merchant paypal acct, shopping cart items (with prices), a URL that Paypal will POST back to. All this via POST to a Paypal https URL.
  • Customer will then be on Paypal's shopping cart pages, looking at the items, just like on your site.
  • Customer will go through Paypal's checkout foo, and after payment is completed, Paypal will POST back to our site to the notify_url passed earlier. In the POST will come an encrypted string that we need to POST back to Paypal.
  • We POST back to Paypal everything that it sent, including the encrypted string. Paypal then responds with a payment_status variable.

I'm new to service contracts (so please feel free to pitch in), but this is what I'm envisioning the following for the service contract (Neophytos, are you reading this? 😊):

Operation: Charge
Input takes:
response_code:string,reason:string,paypal_transaction_id:string
Output returns:
response_code:string,reason:string,paypal_transaction_id:string

Operation: Refund
Input and Output similar to Charge.

My questions are the following:

Should I pass a Tcl array (err, hash) with all the shopping cart items or just let the appropriate implementation function grab that off the DB? If I should pass the array, do I just specify "cart_items:array" in the acs_sc_msg_type_new declaration?

In this case, where the "Charge" operation will take multiple steps and will not immediately return a value, do I need to do something special with respect to the service contract or its implementation?

Anything obvious that I'm missing? Suggestions/criticism appreciated. Obviously, all of this will go back to the OpenACS tree.

Hi Roberto, the service contracts package was designed to provide flexibility of design. In our case the ecommerce package is not coupled into any specific payment gateway (e.g. authorizenet, verisign, paypal, ...) but it is depended on implementations of an abstract contract that describes the functionality required by any concrete implementation of such a service.

Therefore, provided that the existing (Bart & Janine) payment-gateway contract is general enough, you only need to write an implementation of that contract for paypal. This way your paypal implementation will automatically be available to the ecommerce package (or any other package that makes use of the payment-gateway service contract) without any modifications to the ecommerce libraries or data model or page flow.

In case the existing payment-gateway contract is not general enough to cover paypal's functionality only then did you need to provide a new (generalized/abstract) contract, say micropayments-gateway and then write an implementation for paypal with the new contract. Note though, that in such a case it will be required that the ecommerce package code be modified to handle both contracts.

Let me know if you need more info about this.

The gateway that's been implemented is thought to be general enough to handle the likes of paypal.  You might ping Bart or Janine directly.  Bart's here in the Netherlands attending his brother's wedding and doing other family chores (though he stopped by here at Greenpeace yesterday,volunteered to help and fixed two bugs before we went out for dinner, thanks, Bart!) so might not answer e-mail immediately.
Neophytus and Don,

Yes I know that's what the SC package was created for, and I realize that in an ideal world I would be writing a Paypal implementation for the Payment Gateway service contract.

Unfortunately, as far as I could see, the payment gateway service contract is too especific for credit cards. It asks for all sorts of data that simply are not available in, say, a paypal payment (or anything else that is not a credit card payment).

Another thing that I forgot to mention is that the site I'm working on wants to give the user the choice of payment method. Credit card, paypal or whatever else. If I just bind the PaymentGateway service contract to (say) the PayFlow Pro implementation, then credit card is the only payment method available. If I bind it to Paypal (if that was feasible) than only Paypal will be available.
Is there documentation for acs-service-contract?  There is some info in /acs-service-contract/doc/ and there are some samples in the sql directory, but I'm still not sure how to create and use the service contracts.  Any help would be appreciated.  Thanks.
In that case, as I mentioned in my previous message, you could define a new service contract for micropayments (micropayments-gateway) -- paypal will be an implementation of that contract.

It is good practice, when specifying a new contract, to try and make it as general as possible so that it will support future implementations from other micropayments vendors -- there's no point of having a contract unless there is a possibility and reason to support other/alternative/multiple implementations.

I'll leave it to someone else to comment on your original post on how to proceed with the details of a micropayments contract.

Your best bet is probably looking at current implementations. There's an example simple contract in the acs-s-c package. Then you have the search package, the payment gateway, the payflowpro, the authorize.net, the value-based shipping service contracts too.
Neophytos,

Yes, you're right wrt to the micropayments-gateway. I'll do that. Thanks  for the suggestion. My other questions still hold though 😊

We posted at the same time :)

Roberto: Yes, you can do what you describe, i.e. have the user choose either "pay by credit card" or "pay by micropayment account". Then your package will choose an implementation of the payment-gateway when "pay by credit card" is chosen or an implementation of the micropayments-gateway when "pay by micropayments account" is chosen. Next step is to advogate your service contract to package developers so that they make their packages aware of your new service contract. For example, modify the ecommerce package to use micropayment-gateway along with payment-gateway.

Everybody: To avoid confusion, in the given example, I say that the ecommerce package should be modified, for Roberto is talking about writing a new *contract* specification. There would be no need to change the ecommerce package or any other package that makes use of a contract when writing an *implementation* for that contract. For example, the ecommerce package will automatically support any new implementation of the payment-gateway, say for vendor "my credit card verification company XYZ".

Gilbert: There is not much in terms of documentation but the idea is pretty simple. Your best bet as Roberto has already pointed out is to check out the packages that either define a contract specification or provide an implementation of a contract. In loose terms, a contract is a set of abstract operations and an implementation of a contract provides one function for each abstract operation in the contract. Then the acs-service-contract package acts as a message redirector that calls the "right" function for a given contract, implementation, operation and arguments. For example, you say "acs_sc_call PaymentGateway [ad_parameter which_payment_gateway_implementation] AuthorizeCreditCard {1234-1234-1234 {Neophytos Demetriou}}" instead of "verisign_authorize {1234-1234-1234 {Neophytos Demetriou}}.

[Roberto, it seems that you posted again before I finished my message but I'm posting it anyway :) ]

Thanks Neophytos.  It all makes sense now.  I was looking at the payment-gateway package and couldn't figure out where the functions were. I should have looked in the authorize-gateway package! :)

I have some more questions on the service contract, but I'll move it to the design forum...

Can I do this with iKobo.com? They have much large coverage and lower fees. Please help. Have you ever tried with www.iKobo.com ?