Gradually Migrating Payment Data
The Process
The gradual, self-managed migration option means you can use the third party tokens from your current external vault for existing customers while adding new customer payment methods directly to the Spreedly environment. Additionally, as customers update their payment methods over time, you can transition them from having a third party token payment method to having a universal payment method stored in the Spreedly vault.
This means that, over time, your customers’ payment methods are migrated from a gateway-locked third party token to a universal payment method.
It is important to remember that using a third party token from your existing credit card vault means that those customers are locked to that gateway account until they update their payment methods.
Migration Example
Let’s say you’d like to migrate a card that you have stored in a Litle account vault. All you’ll need to do to migrate that to Spreedly is use that card’s token (the unique Id for the payment method) from Litle and use our creating a new payment method API call:
curl https://core.spreedly.com/v1/payment_methods.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<payment_method>
<payment_method_type>third_party_token</payment_method_type>
<reference>MF424cE3jPVESunRNZW0oFtmyI4</reference>
<gateway_type>litle</gateway_type>
</payment_method>'
<transaction>
<token>ElSwUhstac9uomgiNHUGBrzZPx9</token>
<created_at type="dateTime">2017-07-27T17:51:33Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:33Z</updated_at>
<succeeded type="boolean">true</succeeded>
<transaction_type>AddPaymentMethod</transaction_type>
<retained type="boolean">false</retained>
<state>succeeded</state>
<message key="messages.transaction_succeeded">Succeeded!</message>
<payment_method>
<token>AiVJSv7DVmikj6B5H1estSIyqqv</token>
<created_at type="dateTime">2017-07-27T17:51:33Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:33Z</updated_at>
<gateway_type>litle</gateway_type>
<storage_state>cached</storage_state>
<third_party_token>MF424cE3jPVESunRNZW0oFtmyI4</third_party_token>
<payment_method_type>third_party_token</payment_method_type>
<errors>
</errors>
</payment_method>
</transaction>
The response will contain the Spreedly-specific payment method token that points to the payment method in the third party vault. You can now use that token to reference and operate against the payment method stored in the Litle environment.
Different gateways utilize different fields to identify a payment method in their vault. For some gateways, multiple fields are needed. You can contact us if you’d like more details about a specific gateway’s reference format.
Using Your Token
Once you’ve added the third party token to our vault, you can then use the Spreedly token that was returned to you to transact with it.
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>'
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-07-27T17:53:06Z</created_at>
<updated_at type="dateTime">2017-07-27T17:53:06Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>3mxXbb2X2KYm9Sz0SCjNKXG61DX</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>65</gateway_transaction_id>
<gateway_latency_ms type="integer">25</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-07-27T17:53:06Z</created_at>
<updated_at type="dateTime">2017-07-27T17:53:06Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2017-07-27T17:53:05Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Errors
As stated before, third party tokens can only be used with their associated gateways. If you try to use a third party token with a different gateway type you will get an incompatible third party token error.
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
</transaction>'
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-07-27T17:51:58Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:58Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>MesZ4kwKTHh706N5bBxbKjkDovf</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields nil="true"/>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>57</gateway_transaction_id>
<gateway_latency_ms type="integer">38</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-07-27T17:51:58Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:58Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:24Z</updated_at>
<email>joey@example.com</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>