Worldpay: Introduce normalized stored credential options

[davidsantoso]

The Visa/Mastercard Stored Credentials Framework is becoming standard
functionality across all gateways. There are a few gateways in Active
Merchant which support sending in very specific fields in the options
hash which will be set while building a auth/purchase request. However
Active Merchant should be a consistent interface to gateways and to that
end, this commit is introducing a new normalized hash which contains
a standard set of fields by which the proper logic should be able to
construct a correct stored credentials request to any gateway.
The hash takes the following structure:

{
  stored_credential: {
    inital_transaction: Boolean, # either true or false
    recurring: Boolean, # either true or false
    initiator: String, # either "merchant" or "cardholder"
    network_transaction_id: String # returned card network transaction id
  }
}

With those 4 bits of information, you should be able to successfully add
the necessary fields to any gateway request. Note that there should be
logic to add the necessary values in the request (see this commit as an
example) and not all gateways will need or accept all those fields.

In many ways this is similar to normalizing address fields in that
Active Merchant always expects and address hash to use a field zip
instead of something like postalCode. However the downside to this
setup is that there is no field level validation which we get with
something like an Active Merchant CreditCard.

Lastly, this commit also allows for the specific fields to also be sent
to maintain backwards compatibility with anyone who might already be
using the specific fields.

[jknipp]

👍- Travis is failing on Rubocop errors.

[curiousepic]

I'm on board with this normalization 👍

[bdewater]

TIL about this. I'll have to read a little to get more context, but one concern I'd like to voice now for implementing this:

However the downside to this setup is that there is no field level validation which we get with something like an Active Merchant CreditCard.

If we're officially introducing this as an addition to the API I think it's better for the long term to introduce a proper object. It's a one time pain to change now but I think it's better than yet another defined-but-not-enforced hash (which smells like primitive obsession) that's harder to evolve in the future.

[davidsantoso]

@bdewater I hear ya. It was also a concern of mine which is why I brought it up in the commit message. Although I am going back and forth on it since the options hash in Active Merchant is sort of a catch all place where you can send in all sorts of parameters to help generate the right request. As of right now, I don't think we have any other Objects that go into the options hash with it always being more or less unstructured.

In this case, it feels like a bit of an in between of how we have the billing_address hash implemented and how something like the CreditCard object works- billing address isn't necessarily required so we just have a defined hash we use but no logic when adding billing address information. Credit cards on the other hand are always required and sometimes there's formatting logic for the request. Stored credential information isn't required for a gateway request, but there could be some formatting of the data required to send the correct field.

At this point I'm leaning towards it being a somewhat of a beta feature with documentation in the wiki on how it works and how to use it with the caveat that unless it's used accordingly, it will likely not work as expected. I'm looking into adding it across multiple gateways and once I get a better feel for implementing it in other scenarios I don't want to also prematurely optimize for these exact field level validations. However it is top of mind so I suspect it will become hardened as Active Merchant work continues.

[bdewater]

I'm looking into adding it across multiple gateways and once I get a better feel for implementing it in other scenarios I don't want to also prematurely optimize for these exact field level validations.

This makes a lot of sense - let's iterate and get a sense of what the proper encapsulation should look like as we go :)

[davidsantoso]

👍 thanks for the set of eyes!

[davidsantoso]

Closed with https://github.com/activemerchant/active_merchant.

Apologies, forgot to add the "Closes #3134" to the commit message before pushing.