BlueSnap Gateway Guide

BlueSnap fact sheet

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.

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>OPh9Rm5tJodO6U1gg08hzEVmAL8</token>
  <gateway_type>blue_snap</gateway_type>
  <name>BlueSnap</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key 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>
    <supports_network_tokenization type="boolean">false</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
  </characteristics>
  <credentials>
    <credential>
      <name>api_username</name>
      <value>Your API Username</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>soft_descriptor</gateway_specific_field>
    <gateway_specific_field>billing_address</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_field>transaction_fraud_info</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>reason</gateway_specific_field>
    <gateway_specific_field>cancel_subscription</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <created_at type="dateTime">2022-02-09T08:23:01Z</created_at>
  <updated_at type="dateTime">2022-02-09T08:23:01Z</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 3DS2 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`

Stored credentials

For BlueSnap gateway, sending stored credential fields can be done using Spreedly’s first class support. Sending stored credential data is simple. For any Authorize or Purchase request, you need to include three fields which tell Spreedly a little bit more about the nature of the transaction:

stored_credential_initiator
stored_credential_reason_type
network_transaction_id

Learn more about how Spreedly enables use of stored credentials by reviewing our Stored Credentials Guide.

Gateway specific fields

When interacting with a BlueSnap gateway to run transactions, there are a number of gateway specific fields you can specify.

store_card
transaction_fraud_info
idempotency_key
billing_address
reason
cancel_subscription

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.

The idempotency_key field can be used to prevent requests being performed multiple times. For information on generating an idempotency_key visit BlueSnap’s Idempotency documentation.

The reason and cancel_subscription fields are passed in request for refund operation to specify the reason and flag to cancel subscription.

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>
            <descriptor_phone_number>number</descriptor_phone_number>
            <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>
            <idempotency_key>unique_key</idempotency_key>
            <reason>refund for order</reason>
            <cancel_subscription>true</cancel_subscription>
            <billing_address>
              <name>ABC</name>
              <address1>456 My Street</address1>
              <address2>Apt 1</address2>
              <company>Widgets Inc</company>
              <city>Ottawa</city>
              <state>ON</state>
              <zip>K1C2N6</zip>
              <country>CA</country>
              <phone>(555)555-5555</phone>
              <fax>(555)555-6666</fax>
            </billing_address>
          </blue_snap>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2023-03-10T21:26:23Z</created_at>
  <updated_at type="dateTime">2023-03-10T21:26:23Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>OU9f2X9DmewfT4NKdA8njJM95dT</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"/>
  <merchant_profile_key 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>
      <descriptor_phone_number>number</descriptor_phone_number>
      <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>
      <idempotency_key>unique_key</idempotency_key>
      <reason>refund for order</reason>
      <cancel_subscription>true</cancel_subscription>
      <billing_address>
        <name>ABC</name>
        <address1>456 My Street</address1>
        <address2>Apt 1</address2>
        <company>Widgets Inc</company>
        <city>Ottawa</city>
        <state>ON</state>
        <zip>K1C2N6</zip>
        <country>CA</country>
        <phone>(555)555-5555</phone>
        <fax>(555)555-6666</fax>
      </billing_address>
    </blue_snap>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>54</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">1</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <warning nil="true"/>
  <application_id nil="true"/>
  <amount type="integer">100</amount>
  <local_amount nil="true"/>
  <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">2023-03-10T21:26:23Z</created_at>
    <updated_at type="dateTime">2023-03-10T21:26:23Z</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">2023-03-10T21:19:42Z</updated_at>
    <email>[email protected]</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"/>
    <issuer_identification_number nil="true"/>
    <click_to_pay type="boolean">false</click_to_pay>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value></verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
    <stored_credential_usage>
      <test>
        <original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
        <network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
      </test>
    </stored_credential_usage>
  </payment_method>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

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>

In the case of failed transactions, BlueSnap provides additional error information alongside the specific error code and descriptive message. Use the error_name field which you can find in the gateway_specific_response_fields to access the name of the specific error that accompanies the error code. For example, a failed transaction could look like this:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <response>
    <message>Transaction failed  because of payment processing failure.: 531 - The security code entered is invalid. Please check number and enter again</message>
    <error_code>14002</error_code>
  </response>
  <gateway_specific_response_fields>
     <blue_snap>
      <error_name>CVV_ERROR</error_name>
     </blue_snap>
  </gateway_specific_response_fields>
</transaction>