API referenceiFrame APIExpress APISupportBlog
Guides

Qvalent gateway guide

Suggest Edits

Qvalent fact sheet

Additional notes
Support for Authorize transactions requires “Pre-Auths” to be activated for your merchant account by Qvalent.
Support for General Credit transactions requires “Adhoc Refunds” to be activated for your merchant account by Qvalent.

Adding a Qvalent gateway

To add a Qvalent gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>qvalent</gateway_type>
        <username>Your username</username>
        <password>Your password</password>
        <merchant>Your merchant</merchant>
        <pem>-----BEGIN RSA PRIVATE KEY-----
MIIEogIBAAKCAQEAn0hOiAqdiHgp94A/cB+YxqQTPJynzTHZmCGxKylRf4sd0Mrs
SD8kzhaGoUo4/KUSXuATjHpfnBbtHWWVzbN7V8y0457q0qo76jSQj8ce+bfOGatN
FPirNZ35Tw8W2o9v1GJeSEsRFCudd2kAoJOOF5Gf7quDzWk/0LpIcAb8sKZ7amNV
fQF4KIyoLF/wSdXA2A5KkuFBdenQcqjD3OwTk2lbQBeT1fuZYHjTK1T3id2/pHMZ
1aobTeXwnt+y+8W79TtiCYFCPpsjV3rmBxwflsshd+LbDpt6+fUhmNxIHA2NuJtd
I7a9XkNk7EehVZKKvc/MRm4hVxHJrgrvyI+i9QIDAQABAoIBADhTMmoLDu/+RiDe
ehBlK/o6dQ7++pumICMa7vKrVsV6ZV27FFjr81DpSExq2cIFgXyJUoBfmcWxmcHG
dXXbHSfMHL9NKA684hkM433kVQDLTZdoKwbadHiuV0XsuREqncoFyv9XhD+UuMdM
G0utQhb1iQ+2GRKfQFDIPutWnS698ZFJ8vVkPZbX/nNbnhM8Ct/8qyj6IyOJleJI
jAUNM1m9o9Ox1ggG6q2Ey2XaSzkamqK2b4xDm88Z0kGJUTvv67zQzydFa07HVLae
bWppGBZDghNjA4IsFjT3w++6D5rwSJEnXLfEkhs/GW19bMG53srlW3pCfkH7Rm0S
zr+RSYECgYEAz7kYbbDMc8VcYK5A9LFn8t1JgNAGE+oL/zvDVlVeDFDdM26hzvDe
VwN3vCqXIziXFAnlECWXU+NIYSdoNjJFMX38xapIw3hmEN153RPLd0bHckNyPd5q
GbLvL+Ohq9sSguvwDAPpJM7LO2xdEd/k0fATKqT1+2Mph8fQcyq/SFUCgYEAxE0j
7lsAZHImZopIR8uHOJwpVKmOgPBp6fW063lKnm4uScKSvy99fNDi/UeeWKjrhLeK
LgXNeR91vsvmJEIxdqEgXbzxZO8/pjB9ITL1blCo2KFElZNC6ArxNg66D1XIPs0R
UhV145bpkWJpuUHuLtCVzJgoVRfvR0Zq9dXaECECgYAC0iasxqvgHpwEjBlBuW8J
80tePnT2rEUBcFRUxdADJs36NtRntQmv8NIdcg6fYdNbaE7+CySk9P80oo5dvg0G
gQl/vbJDRU1NiVRwViZ7NjDbMmNIx851DuMEqXi2lsEHmiCmaR8vaseDxRL2fS3k
U/hOqfLVOSGFQIdqKPh0CQKBgAwNkH86JzQDrkfthbKi1JKtQ/xmzNEt8dLju1Aa
CnLf4Qe2YrxKdjILwWQ72YUoGg30Fw/sW0lsnRYx/teLGO5nxkz7JPdFmWri30wC
jP9RBI0ImeV1PU5yHY1sKhB2++yfOskHeE2ZHo5GtKcjXTSSqh/917wh1BdUQ40E
rHcBAoGAMtXp+rfxxBxQWZUpxFHgdWXPn+5MtkFtSUQ3QJD8HyIsRLc6YP1iggd8
pN+wWJY+cL31XAyqNA2GA8+vf2JD/pVHqHREbRXtrwuFN9SdWBO1SLTNPW2ni42E
L2qsUyUaOIRteOE0kUR3YkDrtGMr1n7KgRArpeDZSxssQJHX98U=
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIEogIBAAKCAQEAn0hOiAqdiHgp94A/cB+YxqQTPJynzTHZmCGxKylRf4sd0Mrs
SD8kzhaGoUo4/KUSXuATjHpfnBbtHWWVzbN7V8y0457q0qo76jSQj8ce+bfOGatN
FPirNZ35Tw8W2o9v1GJeSEsRFCudd2kAoJOOF5Gf7quDzWk/0LpIcAb8sKZ7amNV
fQF4KIyoLF/wSdXA2A5KkuFBdenQcqjD3OwTk2lbQBeT1fuZYHjTK1T3id2/pHMZ
1aobTeXwnt+y+8W79TtiCYFCPpsjV3rmBxwflsshd+LbDpt6+fUhmNxIHA2NuJtd
I7a9XkNk7EehVZKKvc/MRm4hVxHJrgrvyI+i9QIDAQABAoIBADhTMmoLDu/+RiDe
ehBlK/o6dQ7++pumICMa7vKrVsV6ZV27FFjr81DpSExq2cIFgXyJUoBfmcWxmcHG
dXXbHSfMHL9NKA684hkM433kVQDLTZdoKwbadHiuV0XsuREqncoFyv9XhD+UuMdM
G0utQhb1iQ+2GRKfQFDIPutWnS698ZFJ8vVkPZbX/nNbnhM8Ct/8qyj6IyOJleJI
jAUNM1m9o9Ox1ggG6q2Ey2XaSzkamqK2b4xDm88Z0kGJUTvv67zQzydFa07HVLae
bWppGBZDghNjA4IsFjT3w++6D5rwSJEnXLfEkhs/GW19bMG53srlW3pCfkH7Rm0S
zr+RSYECgYEAz7kYbbDMc8VcYK5A9LFn8t1JgNAGE+oL/zvDVlVeDFDdM26hzvDe
VwN3vCqXIziXFAnlECWXU+NIYSdoNjJFMX38xapIw3hmEN153RPLd0bHckNyPd5q
GbLvL+Ohq9sSguvwDAPpJM7LO2xdEd/k0fATKqT1+2Mph8fQcyq/SFUCgYEAxE0j
7lsAZHImZopIR8uHOJwpVKmOgPBp6fW063lKnm4uScKSvy99fNDi/UeeWKjrhLeK
LgXNeR91vsvmJEIxdqEgXbzxZO8/pjB9ITL1blCo2KFElZNC6ArxNg66D1XIPs0R
UhV145bpkWJpuUHuLtCVzJgoVRfvR0Zq9dXaECECgYAC0iasxqvgHpwEjBlBuW8J
80tePnT2rEUBcFRUxdADJs36NtRntQmv8NIdcg6fYdNbaE7+CySk9P80oo5dvg0G
gQl/vbJDRU1NiVRwViZ7NjDbMmNIx851DuMEqXi2lsEHmiCmaR8vaseDxRL2fS3k
U/hOqfLVOSGFQIdqKPh0CQKBgAwNkH86JzQDrkfthbKi1JKtQ/xmzNEt8dLju1Aa
CnLf4Qe2YrxKdjILwWQ72YUoGg30Fw/sW0lsnRYx/teLGO5nxkz7JPdFmWri30wC
jP9RBI0ImeV1PU5yHY1sKhB2++yfOskHeE2ZHo5GtKcjXTSSqh/917wh1BdUQ40E
rHcBAoGAMtXp+rfxxBxQWZUpxFHgdWXPn+5MtkFtSUQ3QJD8HyIsRLc6YP1iggd8
pN+wWJY+cL31XAyqNA2GA8+vf2JD/pVHqHREbRXtrwuFN9SdWBO1SLTNPW2ni42E
L2qsUyUaOIRteOE0kUR3YkDrtGMr1n7KgRArpeDZSxssQJHX98U=
-----END CERTIFICATE-----
</pem>
        <pem_password>Your pem_password</pem_password>
      </gateway>'

<gateway>
  <token>ZERTM5mb5dEYocgHW4r3zy2dXzH</token>
  <gateway_type>qvalent</gateway_type>
  <name>Qvalent</name>
  <description nil="true"/>
  <username>Your username</username>
  <merchant>Your merchant</merchant>
  <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">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_verify type="boolean">false</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_store type="boolean">true</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_disburse type="boolean">false</supports_disburse>
  </characteristics>
  <credentials>
    <credential>
      <name>username</name>
      <value>Your username</value>
    </credential>
    <credential>
      <name>merchant</name>
      <value>Your merchant</value>
    </credential>
  </credentials>
  <gateway_specific_fields>
    <gateway_specific_field>customer_merchant_name</gateway_specific_field>
    <gateway_specific_field>customer_merchant_street_address</gateway_specific_field>
    <gateway_specific_field>customer_merchant_location</gateway_specific_field>
    <gateway_specific_field>customer_merchant_state</gateway_specific_field>
    <gateway_specific_field>customer_merchant_country</gateway_specific_field>
    <gateway_specific_field>customer_merchant_post_code</gateway_specific_field>
    <gateway_specific_field>customer_merchant_sub_merchant_id</gateway_specific_field>
    <gateway_specific_field>xid</gateway_specific_field>
    <gateway_specific_field>cavv</gateway_specific_field>
    <gateway_specific_field>eci</gateway_specific_field>
    <gateway_specific_field>customer_reference_number</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2018-06-19T17:07:27Z</created_at>
  <updated_at type="dateTime">2018-06-19T17:07:27Z</updated_at>
</gateway>

Gateway specific fields

When interacting with a Qvalent gateway to run transactions, there are some gateway specific fields you can specify.

Electronic commerce indicator (ECI)

The eci field is required for recurring transactions on the Qvalent gateway. Specify eci directly, or you can have eci determined as part of Spreedly’s first class support for sending stored credential data.

Soft descriptors

For merchant accounts that have been enabled, Qvalent allows the use of soft descriptors to provide control over text that appears in credit card statements. Note that all fields must be present for Qvalent to accept the request. For more information see the Qvalent docs.

3DS data

3D Secure information can be sent with the cavv, xid, and eci fields, but be advised when sending the eci field for 3D Secure transactions, the xid and cavv fields are required.

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>
          <qvalent>
            <xid>XID value</xid>
            <cavv>CAVV value</cavv>
            <eci>ECI value</eci>
            <customer_merchant_name>The Merchant</customer_merchant_name>
            <customer_merchant_street_address>123 Merchant Address</customer_merchant_street_address>
            <customer_merchant_location>Sydney</customer_merchant_location>
            <customer_merchant_state>NSW</customer_merchant_state>
            <customer_merchant_country>AU</customer_merchant_country>
            <customer_merchant_post_code>2070</customer_merchant_post_code>
            <customer_merchant_sub_merchant_id>10330482</customer_merchant_sub_merchant_id>
            <customer_reference_number>12345678910</customer_reference_number>
          </qvalent>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2021-04-13T18:19:26Z</created_at>
  <updated_at type="dateTime">2021-04-13T18:19:26Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>9kMOhVrjMsiQkRHNFV7sdI6qk1K</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>
    <qvalent>
      <xid>XID value</xid>
      <cavv>CAVV value</cavv>
      <eci>ECI value</eci>
      <customer_merchant_name>The Merchant</customer_merchant_name>
      <customer_merchant_street_address>123 Merchant Address</customer_merchant_street_address>
      <customer_merchant_location>Sydney</customer_merchant_location>
      <customer_merchant_state>NSW</customer_merchant_state>
      <customer_merchant_country>AU</customer_merchant_country>
      <customer_merchant_post_code>2070</customer_merchant_post_code>
      <customer_merchant_sub_merchant_id>10330482</customer_merchant_sub_merchant_id>
      <customer_reference_number>12345678910</customer_reference_number>
    </qvalent>
  </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"/>
  <application_id 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-04-13T18:19:26Z</created_at>
    <updated_at type="dateTime">2021-04-13T18:19:26Z</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-04-13T14:32:43Z</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"/>
    <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>

Gateway specific response fields

A response from Qvalent gateway may contain a reference_number, response_code, and/or summary_code field which you can find in the gateway_specific_response_fields.

The response_code Gateway Specific Response Field will map to the error_code field returned in the transcript, except in cases where the response_code is 00 or 08, indicating a successful transaction. For additional information regarding response_codes see the Qvalent documentation.

For example, a transaction could have something like this:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <qvalent>
       <reference_number>987654321</reference_number>
       <response_code>51</response_code>
       <summary_code>1</summary_code>
     </qvalent>
  </gateway_specific_response_fields>
</transaction>

Updated 4 months ago