BlueSnap Gateway Guide
Services and Compatibility
- Payment Gateway Company Name:
- BlueSnap
- Services that work with Spreedly:
-
- BlueSnap
- Supported operations:
- Purchase, Authorize, Capture, Refund, Void, Verify, Store
- Supported payment types:
- Credit Card, Bank Account
- Spreedly 3DS2 Global Supported
- Yes
- Gateway Specific 3DS1 Supported
- No
- Gateway Specific 3D2 Supported
- No
- Regions:
- Europe, Latin America, North America
- API endpoint URL:
-
https://ws.bluesnap.com/services/2
Authentication and Security
- Specific names for credentials:
- Api Username, Api Password
Onboarding Merchants in:
-
United States
-
Canada
-
United Kingdom
-
Austria
-
Belgium
-
Bulgaria
-
Croatia
-
Cyprus
-
Czech Republic
-
Denmark
-
Estonia
-
Finland
-
France
-
Germany
-
Greece
-
Hungary
-
Ireland
-
Italy
-
Latvia
-
Lithuania
-
Luxembourg
-
Malta
-
Netherlands
-
Poland
-
Portugal
-
Romania
-
Slovakia
-
Slovenia
-
Spain
-
Sweden
-
Argentina
-
Bolivia (Plurinational State of)
-
Brazil
-
Belize
-
Chile
-
Colombia
-
Costa Rica
-
Dominican Republic
-
Ecuador
-
French Guiana
-
Guadeloupe
-
Guatemala
-
Honduras
-
Haiti
-
Saint Martin (French part)
-
Martinique
-
Mexico
-
Nicaragua
-
Panama
-
Peru
-
Puerto Rico
-
Paraguay
-
El Salvador
-
Uruguay
-
Venezuela (Bolivarian Republic of)
Additional Notes
This gateway supports Level 2 and Level 3 transaction processing via Spreedly. If you are interested in Level 2 or Level 3 transaction support, please contact the gateway to confirm that your account is enabled for these processing types. Please let us know if there are any specific parameters you would like to have enabled.
For additional information about setting up your BlueSnap account to use with Spreedly, visit BlueSnap’s guide.
Adding a BlueSnap gateway
To add a BlueSnap gateway:
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>blue_snap</gateway_type>
<api_username>Your API Username</api_username>
<api_password>Your API Password</api_password>
</gateway>'
<gateway>
<token>EbEGGdjoLQ2solWH6EIsWCvACew</token>
<gateway_type>blue_snap</gateway_type>
<name>BlueSnap</name>
<description nil="true"/>
<api_username>Your API Username</api_username>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_adjust type="boolean">false</supports_adjust>
<supports_verify type="boolean">true</supports_verify>
<supports_reference_purchase type="boolean">false</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
<supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
</characteristics>
<credentials>
<credential>
<name>api_username</name>
<value>Your API Username</value>
</credential>
</credentials>
<gateway_specific_fields>
<gateway_specific_field>soft_descriptor</gateway_specific_field>
<gateway_specific_field>store_card</gateway_specific_field>
<gateway_specific_field>customer_reference_number</gateway_specific_field>
<gateway_specific_field>sales_tax_amount</gateway_specific_field>
<gateway_specific_field>freight_amount</gateway_specific_field>
<gateway_specific_field>duty_amount</gateway_specific_field>
<gateway_specific_field>destination_zip_code</gateway_specific_field>
<gateway_specific_field>destination_country_code</gateway_specific_field>
<gateway_specific_field>ship_from_zip_code</gateway_specific_field>
<gateway_specific_field>discount_amount</gateway_specific_field>
<gateway_specific_field>tax_amount</gateway_specific_field>
<gateway_specific_field>tax_rate</gateway_specific_field>
<gateway_specific_field>level_3_data_items</gateway_specific_field>
<gateway_specific_field>personal_identification_number</gateway_specific_field>
<gateway_specific_field>authorized_by_shopper</gateway_specific_field>
<gateway_specific_field>include_capture_amount</gateway_specific_field>
<gateway_specific_field>challenge_indicator</gateway_specific_field>
<gateway_specific_field>threeri_indicator</gateway_specific_field>
<gateway_specific_field>purchase_date</gateway_specific_field>
<gateway_specific_field>installment</gateway_specific_field>
<gateway_specific_field>recurring_end</gateway_specific_field>
<gateway_specific_field>recurring_frequency</gateway_specific_field>
<gateway_specific_field>transaction_meta_data</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
<payment_method>bank_account</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<created_at type="dateTime">2019-09-09T20:32:56Z</created_at>
<updated_at type="dateTime">2019-09-09T20:32:56Z</updated_at>
</gateway>
ACH/ECP transactions
ACH/ECP payments are supported for US
transactions. In order to process ACH/ECP transactions with BlueSnap, special setup is required. First, the ECP payment method must be enabled in your account dashboard.
Second, for each ACH/ECP transaction, you must obtain the shopper’s permission to debit their account. For example, by showing a checkbox with the following wording on your checkout page: I authorize this Electronic Check (ACH/ECP) transaction and agree to this debit of my account.
In addition, you must set the authorized_by_shopper
gateway specific field to true
to indicate that the shopper’s permission has been obtained. For more information, see BlueSnap’s ACH/ECP docs.
Third-party 3D Secure 2 auth data
Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to BlueSnap. For more information about how to use this feature, see the 3DS2 Third-party Authentication Guide. Spreedly fields map to the relevant BlueSnap fields as described in the following table. Please see BlueSnap’s third-party 3DS2 documentation for detailed descriptions of each of these fields and when to use them.
Spreedly Field | BlueSnap Field |
---|---|
three_ds_version |
three-d-secure-version |
ecommerce_indicator |
eci |
authentication_value |
cavv |
directory_server_transaction_id |
ds-transaction-id |
xid |
xid |
Gateway specific fields
When interacting with a BlueSnap gateway to run transactions, there are a number of gateway specific fields you can specify. If not specifically set, store_card
will have a value of false
. The transaction_fraud_info
field can be used to send information used for fraud prevention. For additional information on using transaction_fraud_info
, please visit BlueSnap’s Transaction Fraud Info documentation. See the example for more information on each field.
Support for partial captures
By default, the amount
is not sent to BlueSnap for capture requests, and the full amount reserved from the authorization is captured. To have the capture amount included, send an include_capture_amount
gateway specific field with the value true
with the capture request. This is necessary for partial captures.
Level 2 data
Level 2 processing requires customer_reference_number
and sales_tax_amount
.
Level 3 data
For Level 3 processing, Level 2 fields are required along with level_3_data_items
, an array of JSON objects detailing the items of the purchase. Each object must contain at least the following properties:
line_item_total
commodity_code
description
product_code
item_quantity
unit_cost
unit_of_measure
For more information on Level 2 and 3 field restrictions for card brands, required fields, or optional fields, please visit BlueSnap’s Level 2/3 Data documentation.
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>
<gateway_specific_fields>
<blue_snap>
<soft_descriptor>Merchant Name</soft_descriptor>
<store_card>true</store_card>
<customer_reference_number>customer</customer_reference_number>
<sales_tax_amount>amount</sales_tax_amount>
<freight_amount>amount</freight_amount>
<duty_amount>amount</duty_amount>
<destination_zip_code>zip</destination_zip_code>
<destination_country_code>country</destination_country_code>
<ship_from_zip_code>zip</ship_from_zip_code>
<discount_amount>amount</discount_amount>
<tax_amount>amount</tax_amount>
<tax_rate>rate</tax_rate>
<level_3_data_items><![CDATA[
[{
"line_item_total": "9.00",
"description": "test_desc",
"product_code": "test_code",
"item_quantity": "1.0",
"unit_of_measure": "lb",
"commodity_code": "123",
"unit_cost": "10.00"
}, {
"line_item_total": "12.00",
"description": "test_2",
"product_code": "2_code",
"item_quantity": "2.0",
"unit_of_measure": "oz",
"commodity_code": "321",
"unit_cost": "13.00"
}]
]]></level_3_data_items>
<personal_identification_number>id_number</personal_identification_number>
<transaction_fraud_info>
<fraud_session_id>unique_id</fraud_session_id>
</transaction_fraud_info>
</blue_snap>
</gateway_specific_fields>
</transaction>'
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2021-01-25T16:45:56Z</created_at>
<updated_at type="dateTime">2021-01-25T16:45:56Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>Q4Xo6Ac1ZIapm4Thvn68PhYbsA3</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>
<blue_snap>
<soft_descriptor>Merchant Name</soft_descriptor>
<store_card>true</store_card>
<customer_reference_number>customer</customer_reference_number>
<sales_tax_amount>amount</sales_tax_amount>
<freight_amount>amount</freight_amount>
<duty_amount>amount</duty_amount>
<destination_zip_code>zip</destination_zip_code>
<destination_country_code>country</destination_country_code>
<ship_from_zip_code>zip</ship_from_zip_code>
<discount_amount>amount</discount_amount>
<tax_amount>amount</tax_amount>
<tax_rate>rate</tax_rate>
<level_3_data_items>
[{
"line_item_total": "9.00",
"description": "test_desc",
"product_code": "test_code",
"item_quantity": "1.0",
"unit_of_measure": "lb",
"commodity_code": "123",
"unit_cost": "10.00"
}, {
"line_item_total": "12.00",
"description": "test_2",
"product_code": "2_code",
"item_quantity": "2.0",
"unit_of_measure": "oz",
"commodity_code": "321",
"unit_cost": "13.00"
}]
</level_3_data_items>
<personal_identification_number>id_number</personal_identification_number>
<transaction_fraud_info>
<fraud_session_id>unique_id</fraud_session_id>
</transaction_fraud_info>
</blue_snap>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>54</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<stored_credential_initiator nil="true"/>
<stored_credential_reason_type nil="true"/>
<warning nil="true"/>
<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>
<smart_routed type="boolean">false</smart_routed>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<gateway_type>test</gateway_type>
<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 nil="true"/>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2021-01-25T16:45:56Z</created_at>
<updated_at type="dateTime">2021-01-25T16:45:56Z</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">2021-01-14T19:24:44Z</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>
<metadata>
<key>string value</key>
</metadata>
<callback_url nil="true"/>
<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 type="boolean">true</eligible_for_card_updater>
<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>
<attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>
env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
gateway_specific_fields: {
blue_snap: {
soft_descriptor: 'Merchant Name',
store_card: true
}
}
)
#<Spreedly::Purchase:0x007ff93aa2db78
@token="7UDglYpb937Y4UivslgoeuvSeDB",
@created_at="2018-08-09T15:32:07Z",
@updated_at="2018-08-09T15:32:07Z",
@state="succeeded",
@message="Succeeded!",
@succeeded="true",
@order_id="",
@ip="",
@description="",
@gateway_token="T11bJAANtTWnxl36GYjKWvbNK0g",
@gateway_transaction_id="54",
@email="",
@merchant_name_descriptor="",
@merchant_location_descriptor="",
@on_test_gateway="true",
@currency_code="USD",
@amount="4432",
@response,=
#<Spreedly::Response:0x007ff93ba48f08
@success="true",
@pending="false",
@cancelled="false",
@fraud_review="",
@created_at="2018-08-09T15:32:07Z",
@updated_at="2018-08-09T15:32:07Z",
@message="Successful purchase",
@avs_code="",
@avs_message="",
@cvv_code="",
@cvv_message="",
@error_code="",
@error_detail="">,
@shipping_address,=
#<Spreedly::ShippingAddress:0x007ff93ba39ee0
@name="Newfirst Newlast",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="">,
@gateway_specific_fields={:blue_snap=>{:soft_descriptor=>"Merchant Name", :store_card=>"true"}},
@payment_method,=
#<Spreedly::CreditCard:0x007ff93ba320f0
@token="1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
@created_at="2017-06-26T17:04:38Z",
@updated_at="2018-08-09T15:32:07Z",
@email="joey@example.com",
@storage_state="retained",
@data="<my_payment_method_identifier>448</my_payment_method_identifier>\n <extra_stuff>\n <some_other_things>Can be anything really</some_other_things>\n </extra_stuff>",
@first_name="Newfirst",
@last_name="Newlast",
@full_name="Newfirst Newlast",
@month="3",
@year="2032",
@number="XXXX-XXXX-XXXX-1111",
@last_four_digits="1111",
@first_six_digits="411111",
@card_type="visa",
@verification_value="",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="",
@company="",
@fingerprint="e3cef43464fc832f6e04f187df25af497994",
@eligible_for_card_updater="",
@errors=[]>>
Gateway specific response fields
Transaction amounts may change slightly due to currency exchange rates, which can impact reference actions like capture, for example. Use the amount
field which you can find in the gateway_specific_response_fields
to know the exact amount from the BlueSnap response.
For example, a transaction could have something like this:
<transaction>
<token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
<transaction_type>Authorize</transaction_type>
<gateway_specific_response_fields>
<blue_snap>
<amount>7999</amount>
</blue_snap>
</gateway_specific_response_fields>
</transaction>