I've been implementing a credit card payment gateway recently using the Cybersource system and their SIMPLE API features – it's a COM object based system.

Everything seemed to go swimmingly well until I struck a snag processing Refunds using the follow-on service, which is where you can refund a previous payment by referencing its unique identifiers. As opposed to a stand alone refund credit.

Cybersource steadfastly refused to allow the credit, giving me errors saying that I was missing a data field, which, after spending a bunch of time carefully checking the fields against their SDK documentation, I was convinced was not correct.

Finally I worked it out – and it had been staring at me in the face. Credit card systems generally have two modes:

1. Authorization – where you check that the card number etc is valid, and that the customer has the bucks available
2. Capture – where you then 'capture' the payment based on the Authorization

Virtually every credit card gateway I've used wraps Authorization and Capture into a single function for cases where you just want a straightforward payment. EG you just want to get the customer's money in a single transaction.

Cybersource is different, first you have to Authorize the payment, then Capture it, which of course you have to do as a single set of calls all as part of processing the customer's payment. On the surface of course it makes complete sense, you are replicating the actual process going on behind the scenes.

But in practice it means making two separate calls to the Cybersource API, all while the customer is sitting watching the spinning 'loading' icon in your shopping cart page.

Matters are not assisted by Cybersource's documentation not clearly describing this (a flow chart or diagram would be helpful), and their samples are woefully deficient – they don't actually have a sample that shows a combined Authorize and Capture scenario – which would surely have to be the single most common activity undetaken by developers implementing their API.