[Request] Better docs/examples

[barryvdh]

I like using Omnipay because the API is pretty consistent on most gateways and it makes it easy to switch gateways. But the documentation isn't really clear on a general 'flow' of how to do things. This maybe because I generally use iDeal gateways (off-site redirects) and the focus for americans is probably Creditcards.

The general workflow for iDeal is something like getIssuers - show form -> redirect to offsite gateway -> process -> return back to returnUrl (or notifyUrl). But there are more inconsistensies, like how to handle the transactionReference/transactionId (should you get them from the purchaseResponse and store them, or are they in the returnUrl, or both), and different parameters (apiKey, merchantId, orderId etc).

Most gateways have almost no readme, is it a good idea to ask gateway maintainer to write a simple documentation of how the gateway should be handled, and what parameters are possible/required? Or perhaps a simple example.

Most of it is also found in the API documentation of that gateway but that usually is a lot harder to work through and match those parameters to the ones of gateway (eg. orderId -> transactionId, issuers/methods, name in creditcard etc)

For example, this shows (imho) a bit more how to start using the gateway: https://github.com/fruitcakestudio/omnipay-sisow#example But maybe there should be a format that people can use.

[greydnls]

I'm working on getting some proper documentation and examples set up, for Omnipay as a whole, but also a separate page setup for each gateway to document the differences found there.

[barryvdh]

Okay nice :) Let me know if you need any help/feedback.

[eileenmcnaughton]

I've been trying to pull together my understanding. I created a shell extention (to use as a starting point) & stuck my prelimary notes in a readme in it https://github.com/eileenmcnaughton/omnipay-shell/

[jargij]

Try this link http://omnipay.thephpleague.com/

[barryvdh]

@jargij Ah didn't see that. That's still the same information from the readme (if I'm not mistaken) but it looks a lot more clearer :) But that doesn't change anything about the mentioned issues.

[cottonhen]

I have been playing around and reading everything omnipay related but I haven't been able to understand how to create my own payment method.

My main concern is that i know how to make a payment using simple php (with my very own gateway) but I have no idea and found no documentation about how to implement it in omnipay.

Also note that many questions on stackexchange (or expressionengine stackexchange) are still there with no answers about omnipay.

thankyou Francesco

[judgej]

So how do we go about capturing all the knowledge out there? There must be loads of people with small insights into how various parts of OmniPay work, but with no way to feed that back into the project, and nowhere appropriate to push it to. So how do we collaborate on improving the documentation? A wiki?

[cottonhen]

Hi judgei,

thanks for your response I want to be very clear about my concern and explain my special case because it can be useful for writing docs or wiki...

I came to omnipay because I'm building an ecommerce using Expressionengine and Expresso Store so I know that Expresso Store uses omnipay to play with many different Payment methods.

I have undestood that omnipay is a library that abstracts different actions common to many payment gateways and so in my case it acts like an interpreter betwen my Payment gateway (gestpay) and expresso store.

I have read the website http://omnipay.thephpleague.com and managed to understand that I need to abstract those common actions: authorize, capture, purchase (that is authorize+capture at the same time)

and reading in the docs I have undestood that: authorize needs completeAuthorize method to handle return from off-site gateways Purchase needs completepurchase to hanle return from off-site gateways

now if I read the docs I come to "responses" ... in the docs I've read: "The payment response must implement ResponseInterface. "

My first question is "outch! what's the difference from completeAuthorize/Purchase ?" Also in authorizing and Charging I've learnt that I need to create some methods (authorize($options) - completeAuthorize($options)) while here there's no explanation on why and what needs to be done.

Also looking at the implemented gateway I noticed that some have those methods authorize, capture, purchase etc etc while others have other methods like fetchTransaction() or other fetch methods...

So the very first thing to document is how omipay inner core works and how/where to do things. maybe one or two case studies would help people using this library!

bye and... sorry for my english...

[eileenmcnaughton]

I agree that writing an Omnipay plugin is pretty confusing. Some of it I believe is that not all the existing ones are fully standardised.

For example our return function is

$this->gateway = Omnipay::create(str_replace('omnipay_', '', $paymentProcessorTypeName));
$this->setProcessorFields();
$response = $this->gateway->completePurchase($params)->send();
if ($response->getTransactionReference()) {
  $this->setTransactionID($response->getTransactionReference());
}
if ($response->isSuccessful()) {
  // process in our system
}
else {
  ....
}

However, in the case of Mollie I believe we need to call FetchTransaction in that flow. It seems to me it should be called by completePurchase and that flow shouldn't need to know about the internals of Mollie given it is intended to deal with multiple processors.

Authorize, Capture & Purchase are just a documentation issue (authorize = stake a claim on the money on the credit card & then capture is actually take the money - e.g in delayed shipping. Purchase means do both at once)

[judgej]

I've created fetchTransaction() in the Helcim driver, and got that name by searching through what other drivers use. Fetching transactions is not one of the core methods of OmniPay, but it probably does need to be; some gateways make it essential to fetch the transaction from the back-end API to make sure the transaction details are what you think they should be (some gateways pass far too much information via the user's browser IMO, and do not hash or encrypt everything, so large portions of that information in the transaction result cannot be trusted).

I agree that if a payment or authorisation needs to fetch the transaction to do this validation checking, then it should be called up internally by the authorize/payment method so you don't need to know it is even happening. In my case, with Helcim, the front-end part and the back-end API are so different, the check involves creating a new gateway object to do the fetchTransaction() It works, and is invisible to the application, but it is a bitch to test (you are testing a gateway that has to create another gateway to do its job), which is something I have not got my head around yet.

[NoelDavies]

The Documentation is sparce, and provides little detail. The Worldpay Implementation is using their old API (which I'm updating at the moment). It took me an entire day dissasembling existing packages to work out how Omnipay works because the documentation doesn't provide any details.

I'm in full support of anybody (preferable the author) who puts together a proper set of documentation on how to build a custom gateway and what each method does, and what it expect, as you'd expect from proper documentation.

[devnix]

+1 to this. I don't get at all the difference between authorizing and charging, and when I should call authorize or purchase methods.