CommerceHub Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
CommerceHub
Services that work with Spreedly:
  • CommerceHub
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify, Store, General Credit
Supported payment types:
Credit Card, Apple Pay, Google Pay
Spreedly 3DS2 Global Supported
Yes
Gateway Specific 3DS2 Supported
No
Populate MIT GSF Support
Yes (Beta)
Regions:
North America
API endpoint URL:
https://prod.api.fiservapps.com/ch

Authentication and Security

Specific names for credentials:
Merchant Id, Terminal Id, Api Key, Api Secret, Encoded Public Key, Encryption Type, Key Id

Onboarding Merchants in:

Additional Notes

  • In order to have an extra security layer for sensitive information, Commerce Hub recommends using additional keys in order to encrypt credit card data. To get the set of keys associated to the specific merchant (Encoded Public Key, Encryption Type, Key Id) these should be requested through a specific endpoint and include the fields in credentials during the process of gateway creation. Additional information about the keys can be found on this site.
  • For Commerce Hub billing information is important to provide in the transaction request because it can be used for Address Verification Services as a fraud prevention. Additional information about the address can be found on this site.

Adding a Commerce Hub gateway

Please reach out to your Customer Success contact to use Commerce Hub.

To add a CommerceHub gateway:


curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>commerce_hub</gateway_type>
        <api_key>Your API Key</api_key>
        <api_secret>Your API Secret</api_secret>
        <merchant_id>Merchant ID</merchant_id>
        <terminal_id>Terminal ID</terminal_id>
        <key_id>Key ID</key_id>
        <encoded_public_key>Base64 Encoded Public Key</encoded_public_key>
        <encryption_type>Encryption Type</encryption_type>
      </gateway>'

<gateway>
  <token>6DB9D7L5n44gymM0cXYai0ZCQUX</token>
  <gateway_type>commerce_hub</gateway_type>
  <name>CommerceHub</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <merchant_id>Merchant ID</merchant_id>
  <terminal_id>Terminal ID</terminal_id>
  <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_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
    <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_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">false</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">false</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">true</supports_populate_mit_fields>
    <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
    <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
    <supports_transaction_retry type="boolean">false</supports_transaction_retry>
    <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
  </characteristics>
  <credentials>
    <credential>
      <name>merchant_id</name>
      <value>Merchant ID</value>
    </credential>
    <credential>
      <name>terminal_id</name>
      <value>Terminal ID</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>origin</gateway_specific_field>
    <gateway_specific_field>eci_indicator</gateway_specific_field>
    <gateway_specific_field>pos_condition_code</gateway_specific_field>
    <gateway_specific_field>pos_entry_mode</gateway_specific_field>
    <gateway_specific_field>data_entry_source</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2023-06-06T18:02:27Z</created_at>
  <updated_at type="dateTime">2023-06-06T18:02:27Z</updated_at>
</gateway>


env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.add_gateway(:commerce_hub, api_key: 'api_key', api_secret: 'secret', merchant_id: 'merchant id', terminal_id: 'terminal id', key_id: 'key id', encoded_public_key: 'base64 encoded public key', encryption_type: 'encryption type')


#<Spreedly::Gateway:0x00007f83c4816718
@token="565QUKDciVD47XFep10AXiY5NZj",
@created_at="2023-06-06T18:02:27Z",
@updated_at="2023-06-06T18:02:27Z",
@gateway_type="commerce_hub",
@state="retained",
@name="CommerceHub",
@credentials={"merchant_id"=>"merchant id", "terminal_id"=>"terminal id"}>

Third-party 3D Secure 2 auth data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Commerce Hub. For more information about how to use this feature, see the 3DS2 Third-party Authentication Guide. Spreedly fields map to the relevant Commerce Hub fields as described in the following table. Please see Commerce Hub’s transaction variable documentation for detailed descriptions of each of these fields and when to use them.

Spreedly Field Commerce Hub Field
directory_server_transaction_id dsTransactionId
authentication_response_status authenticationStatus
three_ds_server_trans_id serviceProviderTransactionId
acs_transaction_id acsTransactionId
authentication_value mpiData.cavv
ecommerce_indicator mpiData.eci
xid mpiData.xid
three_ds_version versionData.recommendedVersion

Stored credentials

For Commerce Hub, sending stored credential fields can be done using Spreedly’s first class support. 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

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

Gateway specific fields

Spreedly supports the following gateway specific fields when transacting with a CommerceHub gateway:

  • origin
  • eci_indicator
  • pos_condition_code
  • pos_entry_mode
  • data_entry_source
  • physical_goods_indicator
  • scheme_reference_transaction_id

Spreedly also supports the following gateway specific fields for CommerceHub’s dynamic descriptors:

  • mcc
  • merchant_name
  • customer_service_number
  • service_entitlement
  • dynamic_descriptors_address

The dynamic_descriptors_address field should contain nested subfields that match CommerceHub’s camel case address fields:


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>
    <commerce_hub>
      <mcc>1234</mcc>
      <merchant_name>Spreedly</merchant_name>
      <customer_service_number>12345</customer_service_number>
      <service_entitlement>54321</service_entitlement>
      <dynamic_descriptors_address>
        <street>123 Main St</street>
        <houseNumberOrName>Apt 2</houseNumberOrName>
        <city>Durham</city>
        <stateOrProvince>NC</stateOrProvince>
        <postalCode>27701</postalCode>
        <country>US</country>
      </dynamic_descriptors_address>
    </commerce_hub>
  </gateway_specific_fields>
</transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2023-12-21T20:34:51Z</created_at>
  <updated_at type="dateTime">2023-12-21T20:34:51Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>QITgDRZvSwmbTdQBbxA58AaGFo1</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>
    <commerce_hub>
      <mcc>1234</mcc>
      <merchant_name>Spreedly</merchant_name>
      <customer_service_number>12345</customer_service_number>
      <service_entitlement>54321</service_entitlement>
      <dynamic_descriptors_address>
        <street>123 Main St</street>
        <houseNumberOrName>Apt 2</houseNumberOrName>
        <city>Durham</city>
        <stateOrProvince>NC</stateOrProvince>
        <postalCode>27701</postalCode>
        <country>US</country>
      </dynamic_descriptors_address>
    </commerce_hub>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>67</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">1</gateway_latency_ms>
  <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>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <stored_credential_alternate_gateway nil="true"/>
  <populate_mit_fields type="boolean">false</populate_mit_fields>
  <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-12-21T20:34:51Z</created_at>
    <updated_at type="dateTime">2023-12-21T20:34:51Z</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-12-21T20:34:51Z</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"/>
    <issuer_identification_number nil="true"/>
    <click_to_pay type="boolean">false</click_to_pay>
    <managed nil="true"/>
    <payment_method_type>credit_card</payment_method_type>
    <stored_credential_usage>
      <test>
        <original_network_transaction_id>37be5367d6dbe4a88c9d</original_network_transaction_id>
        <network_transaction_id>37be5367d6dbe4a88c9d</network_transaction_id>
      </test>
    </stored_credential_usage>
    <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>

Gateway specific response fields

A response from CommerceHub gateway may contain stan field, which you can find in the gateway_specific_response_fields. For example, a transaction could have something like this:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <commerce_hub>
       <stan>04321</stan>
     </commerce_hub>
  </gateway_specific_response_fields>
</transaction>