Authorize.net Gateway Guide

Authorize.net fact sheet

Additional notes
Reversals for Authorize.Net ACH transactions should be processed via General Credit, not Refund. This gateway supports Level 2 transaction processing via Spreedly. If you are interested in Level 2 transaction support, please contact the gateway to confirm that your account is enabled for this processing type. Please let us know if there are any specific parameters you would like to have enabled.

Adding an Authorize.net gateway

To add an Authorize.Net gateway you just need to supply your Authorize.net API login ID and your Authorize.net transaction key:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>authorize_net</gateway_type>
        <login>Your Authorize.Net API Login ID</login>
        <password>Your Authorize.Net Transaction Key</password>
      </gateway>'

<gateway>
  <token>Le90w7jEK9skQKgWyf7CVKu4Khc</token>
  <gateway_type>authorize_net</gateway_type>
  <name>Authorize.Net</name>
  <description nil="true"/>
  <login>Your Authorize.Net API Login ID</login>
  <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">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_store type="boolean">true</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">true</supports_fraud_review>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>Your Authorize.Net API Login ID</value>
    </credential>
  </credentials>
  <gateway_specific_fields>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>customer_profile_id</gateway_specific_field>
    <gateway_specific_field>duplicate_window</gateway_specific_field>
    <gateway_specific_field>disable_partial_auth</gateway_specific_field>
    <gateway_specific_field>market_type</gateway_specific_field>
    <gateway_specific_field>recurring</gateway_specific_field>
    <gateway_specific_field>email_customer</gateway_specific_field>
    <gateway_specific_field>header_email_receipt</gateway_specific_field>
    <gateway_specific_field>line_items</gateway_specific_field>
    <gateway_specific_field>po_number</gateway_specific_field>
    <gateway_specific_field>tax_exempt</gateway_specific_field>
    <gateway_specific_field>tax</gateway_specific_field>
    <gateway_specific_field>duty</gateway_specific_field>
    <gateway_specific_field>shipping</gateway_specific_field>
    <gateway_specific_field>transaction_id</gateway_specific_field>
    <gateway_specific_field>require_billing_address</gateway_specific_field>
    <gateway_specific_field>customer_payment_profile_id</gateway_specific_field>
    <gateway_specific_field>ship_from_address</gateway_specific_field>
    <gateway_specific_field>summary_commodity_code</gateway_specific_field>
    <gateway_specific_field>authentication_indicator</gateway_specific_field>
    <gateway_specific_field>cardholder_authentication_value</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>bank_account</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2023-01-31T19:20:50Z</created_at>
  <updated_at type="dateTime">2023-01-31T19:20:50Z</updated_at>
</gateway>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

Visit your Connections area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select ☑️Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

Authorize.Net requires the API login ID in the login field, and your transaction key in the password field.

Stored credential gateway specific fields

An Authorize.Net gateway supports our standardized Stored Credential data fields. In some cases, Authorize.net may require a reason to be passed for a merchant-initiated transaction; you may pass the stored_credential_reason_type_override field to populate the reason to Authorize.net. Note that the accepted values for this field are distinct from the reason codes supported in Spreedly’s standardized stored_credential_reason_type field. See the Authorize.Net Card on File documentation for further details.

Gateway specific fields

When interacting with a Authorize.Net gateway to run transactions, there are many gateway specific fields you can specify when making a call. These fields can be sent like so:

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>
          <authorize_net>
            <customer_id>3341</customer_id>
            <duplicate_window>0</duplicate_window>
            <disable_partial_auth>true</disable_partial_auth>
            <device_type>10</device_type>
            <market_type>0</market_type>
            <recurring>false</recurring>
            <verify_amount>0</verify_amount>
            <email_customer>true</email_customer>
            <header_email_receipt>subject line</header_email_receipt>
            <po_number>123</po_number>
            <tax_exempt>false</tax_exempt>
            <require_billing_address>true</require_billing_address>
            <customer_profile_id>23455</customer_profile_id>
            <customer_payment_profile_id>495065</customer_payment_profile_id>
            <authentication_indicator>code</authentication_indicator>
            <cardholder_authentication_value>value</cardholder_authentication_value>
            <summary_commodity_code>CODE</summary_commodity_code>
            <stored_credential_reason_type_override>delayedcharge</stored_credential_reason_type_override>
            <ship_from_address>
              <zip>27701</zip>
              <country>US</country>
            </ship_from_address>
            <tax>
              <amount>100</amount>
              <name>tax name</name>
              <description>tax description</description>
            </tax>
            <duty>
              <amount>100</amount>
              <name>duty name</name>
              <description>duty description</description>
            </duty>
            <shipping>
              <amount>100</amount>
              <name>shipping name</name>
              <description>shipping description</description>
            </shipping>
            <line_items>
              <line_item>
                <item_id>1</item_id>
                <name>mug</name>
                <description>coffee</description>
                <quantity>100</quantity>
                <unit_price>10</unit_price>
                <unit_of_measure>oz</unit_of_measure>
                <total_amount>1000</total_amount>
                <product_code>coupon</product_code>
              </line_item>
              <line_item>
                <item_id>2</item_id>
                <name>vase</name>
                <description>floral</description>
                <quantity>200</quantity>
                <unit_price>20</unit_price>
                <unit_of_measure>oz</unit_of_measure>
                <total_amount>2000</total_amount>
                <product_code>coupon</product_code>
              </line_item>
            </line_items>
            <surcharge>
              <amount>10</amount>
              <description>description</description>
            </surcharge>
          </authorize_net>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2022-08-05T19:21:24Z</created_at>
  <updated_at type="dateTime">2022-08-05T19:21:24Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>MbNHRHYdLgsPRnb6XzcHmKeIWGL</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>
    <authorize_net>
      <customer_id>3341</customer_id>
      <duplicate_window>0</duplicate_window>
      <disable_partial_auth>true</disable_partial_auth>
      <device_type>10</device_type>
      <market_type>0</market_type>
      <recurring>false</recurring>
      <verify_amount>0</verify_amount>
      <email_customer>true</email_customer>
      <header_email_receipt>subject line</header_email_receipt>
      <po_number>123</po_number>
      <tax_exempt>false</tax_exempt>
      <require_billing_address>true</require_billing_address>
      <customer_profile_id>23455</customer_profile_id>
      <customer_payment_profile_id>495065</customer_payment_profile_id>
      <authentication_indicator>code</authentication_indicator>
      <cardholder_authentication_value>value</cardholder_authentication_value>
      <summary_commodity_code>CODE</summary_commodity_code>
      <stored_credential_reason_type_override>delayedcharge</stored_credential_reason_type_override>
      <ship_from_address>
        <zip>27701</zip>
        <country>US</country>
      </ship_from_address>
      <tax>
        <amount>100</amount>
        <name>tax name</name>
        <description>tax description</description>
      </tax>
      <duty>
        <amount>100</amount>
        <name>duty name</name>
        <description>duty description</description>
      </duty>
      <shipping>
        <amount>100</amount>
        <name>shipping name</name>
        <description>shipping description</description>
      </shipping>
      <line_items>
        <line_item type="array">
          <line_item>
            <item_id>1</item_id>
            <name>mug</name>
            <description>coffee</description>
            <quantity>100</quantity>
            <unit_price>10</unit_price>
            <unit_of_measure>oz</unit_of_measure>
            <total_amount>1000</total_amount>
            <product_code>coupon</product_code>
          </line_item>
          <line_item>
            <item_id>2</item_id>
            <name>vase</name>
            <description>floral</description>
            <quantity>200</quantity>
            <unit_price>20</unit_price>
            <unit_of_measure>oz</unit_of_measure>
            <total_amount>2000</total_amount>
            <product_code>coupon</product_code>
          </line_item>
        </line_item>
      </line_items>
      <surcharge>
        <amount>10</amount>
        <description>description</description>
      </surcharge>
    </authorize_net>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>61</gateway_transaction_id>
  <sub_merchant_key nil="true"/>
  <gateway_latency_ms type="integer">0</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">2022-08-05T19:21:24Z</created_at>
    <updated_at type="dateTime">2022-08-05T19:21:24Z</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">2022-08-05T19:16:56Z</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"/>
    <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>

Verify amount

The verify_amount gateway specific field allows you to set a custom value for the verify transaction, allowing a $0 authorize for supported brands and acquirers. Please note Authorize.net also requires the address1 and zip fields to be present in the billing_address to perform a $0 authorize.

Recurring billing

By default, the recurringBilling flag will only be automatically sent as recurring in the transaction if the payment method is not a credit card or a third party token. If you wish to override this behavior, you can set the recurring gateway specific field to false to not send the recurringBilling field, or to true to ensure that it is sent as recurring.

Authorize.Net customer_profile_id

When storing a credit card with Authorize.Net CIM using third party vaulting, you can specify a customer_profile_id if you’d like to add the card onto an existing customer in your Authorize.Net account:

If you have already created a token with Authorize.Net and choose to store it with Spreedly by creating a third party token, you will need to provide the customerPaymentProfileID as the reference in the Create Third Party Token request and pass the associated customerProfileId in the gateway specific field customer_profile_id for each transaction using that token.

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/store.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <gateway_specific_fields>
          <authorize_net>
            <customer_profile_id>123456789</customer_profile_id>
          </authorize_net>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <created_at type="dateTime">2017-07-27T17:47:46Z</created_at>
  <updated_at type="dateTime">2017-07-27T17:47:46Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <token>INLw6GtiOs8n3H6UqfO2EVl3KKl</token>
  <state>succeeded</state>
  <gateway_specific_fields>
    <authorize_net>
      <customer_profile_id>123456789</customer_profile_id>
    </authorize_net>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <transaction_type>Store</transaction_type>
  <third_party_token nil="true"/>
  <gateway_transaction_id>56</gateway_transaction_id>
  <gateway_latency_ms type="integer">21</gateway_latency_ms>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <payment_method>
    <token>FXDi6wCDUsG7vLCQrXLbbdYB3Ie</token>
    <created_at type="dateTime">2017-07-27T17:47:46Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:47:46Z</updated_at>
    <gateway_type>test</gateway_type>
    <storage_state>retained</storage_state>
    <third_party_token>test_vault:4111111111111111</third_party_token>
    <payment_method_type>third_party_token</payment_method_type>
    <errors>
    </errors>
  </payment_method>
  <basis_payment_method>
    <token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
    <created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:47:46Z</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>
    <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>
  </basis_payment_method>
  <response>
    <success type="boolean">true</success>
    <message>Successful store</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></error_code>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2017-07-27T17:47:46Z</created_at>
    <updated_at type="dateTime">2017-07-27T17:47:46Z</updated_at>
  </response>
</transaction>

Requiring billing address

For some European customers, billing addresses are required for refund transactions. If Authorize.Net rejects refunds due to missing or incomplete billing address information, try calling refund with require_billing_address set to true.

Response code 4: Held for review

<responseCode>4</responseCode> received from ANET indicates that the transaction was held for review. This community article indicates these responses are related to an anti-fraud tool:

Response code 4 relates to transactions held by the Advanced Fraud Detection Suite (response reason codes 252 and 253) and are only applicable to merchants using that service. These transactions require a manual review by the merchant in their online interface before they will be completed.

With these response codes, it is not possible for you, as the developer, to know whether the merchant will ultimately decide to accept or reject the transaction. Therefore, it is important to present a somewhat ambiguous response to the customer when these response codes occur.

These transactions are marked as succeeded, since they are received to be processed. However, they are flagged as fraud_review:true so they may indeed fail after review.

We’ve mapped the Spreedly response statuses based on Authorize.net’s docs:

Response Code - indicates the overall status of the transaction with possible values of Approved, Declined, Errored or Held for Review:

1: Approved

2: Declined

3: Error

4: Action Required (typically used for AFDS transactions that are held for review)

Spreedly does not do any callbacks once we receive a response from the gateway, so it is up to the merchant to determine the ultimate status of transactions showing <response_code>4</response_code>.

Gateway specific response fields

A response from Authorize.net may contain a full_response_code, response_reason_code, and/or authorization_code.

You can find this information in 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>
     <authorize_net>
       <full_response_code>I00001</full_response_code>
       <response_reason_code>252</response_reason_code>
       <authorization_code>IJK2DZ</authorization_code>
     </authorize_net>
  </gateway_specific_response_fields>
</transaction>

Authorize.net offers response reason code lookup tool which may help you discern why a transaction is failing. This can be especially helpful when you initially setup your Authorize.net gateway and run a real transaction to verify your credentials are correct.

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.