CommerceHub Gateway Guide

CommerceHub fact sheet

Additional notes

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.

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 CommerceHub 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>

Third-party 3DS2 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	CommerceHub field
`directory_server_transaction_id`	`dsTransactionId`
`authentication_response_status`	`authenticationStatus`
`three_ds_server_trans_id`	`serverTransactionId`
`acs_transaction_id`	`acsTransactionId`
`authentication_value`	`mpiData.cavv`
`ecommerce_indicator`	`mpiData.eci`
`xid`	`mpiData.xid`
`three_ds_version`	`versionData.recommendedVersion`

Important note: The field xid is only optional for American Express, if available the customer should send it. For clarity, xid is not needed for Mastercard or Visa and the field should not be sent if the customer doesn’t provide it for American Express.

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 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
Options:
SECURE_ECOM - Frictionless approved
NON_AUTH_ECOM – Attempted
CHANNEL_ENCRYPTED - Declined / unavailable but merchants want to override authentication status and continue authorization. This option is the default.
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>[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>
    <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>

To request any gateway_specific_fields or gateway_specific_response_fields, please contact Support with your request and the gateway documentation for the fields of interest.