Stored Credentials

Major card networks require that merchants include additional data values in their purchase and authorization requests to identify the storage and use of payment credentials. According to the card networks, merchants utilizing the stored credentials framework should see an improvement in approval rates especially for recurring and subscription based charges.

In continuing to provide a consistent interface to payment gateways, Spreedly provides first class support for sending stored credential data to a select number of gateways. Adding a bit of additional data to your transaction will enable Spreedly to generate the appropriate payment gateway request taking into account both the state of the payment method you are using and the additional data you are sending. Furthermore Spreedly handles storing and sending card network specific information allowing payment methods to be seamlessly used between different gateways while still providing the appropriate mapping of stored credential fields.

You can read more about stored credentials in this document provided by Visa.

Supported Gateways

Sending Stored Credential Data

Sending stored credential data is simple. For any Authorize or Purchase request you need to include two fields which tell Spreedly a little bit more about the nature of the transaction.

  • stored_credential_initiator
  • stored_credential_reason_type

Both fields are required for Spreedly to populate requests to your payment gateway with the necessary stored credential fields. If only one of the fields is sent Spreedly will continue with the transaction but skip adding any stored credential data. Additionally, the two fields have a subset of values that are accepted.

  • stored_credential_initiator - merchant or cardholder
  • stored_credential_reason_type - recurring or unscheduled or installment

You should use the combination of those two field values to properly identify the type of transaction you are sending. For example, if your transaction is for a regular monthly subscription and is charged the same time at a set interval (such as monthly) you would send a combination of "merchant" and "recurring". Or, if your customer is purchasing something on your website as a one time purchase but you are storing their payment details for future use, you would send "cardholder" and "unscheduled".

Example Usage

$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "stored_credential_initiator": "cardholder",
          "stored_credential_reason_type": "unscheduled"

$ curl \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>

To see how Spreedly used the stored credential fields you submitted along with the payment method used to generate the request to the gateway, you can use the transcript request to view the communication between Spreedly and your payment gateway. You may need to match it against the gateway docs to see that gateway’s specific stored credential fields.

Card Network Transaction Id

If you’ve read up on stored credentials regulations, you might be wondering where the card network transaction id is or if you need to worry about accessing that from a gateway response in order to submit that with future transactions. The short answer is no, you don’t need to worry about accessing that response from the gateway. Spreedly is handling storing that information for you with your payment methods and automatically injecting it into future transactions. Moreover, we’ll save multiple card network transaction ids by gateway and only use a network transaction id that was returned from a gateway in future transaction requests.

For example, if you initially use a payment method against Worldpay we’ll save a network transaction id returned from Worldpay with your payment method. Then down the road you use that same payment method against Orbital. We won’t send the Worldpay card network transaction id to Orbital, but we will get a new one from Orbital and your payment method will now have a Worldpay and Orbital network transaction id saved with it. If you later switch back to Worldpay you’ll see us send that old Worldpay network transaction id instead of a more recent one returned by Orbital.