Decidir Gateway Guide

Decidir fact sheet

Adding a Decidir gateway

Spreedly supports the PCI implementation of the Decidir API. This version of the API allows a merchant to include credit card and transaction information in a single API request. The PCI implementation supports using a single API key for each API request.

To add a Decidir gateway you must supply the API key provided by Decidir.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>decidir</gateway_type>
        <api_key>Your api key</api_key>
        <preauth_mode>false</preauth_mode>
      </gateway>'

<gateway>
  <token>PdVrmpJsIQ9xkvJ06iuyl8Obr9T</token>
  <gateway_type>decidir</gateway_type>
  <name>Decidir</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <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">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_inquire_by_gateway_transaction_id type="boolean">true</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>
  </characteristics>
  <credentials>
  </credentials>
  <gateway_settings>
    <preauth_mode>false</preauth_mode>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>payment_method_id</gateway_specific_field>
    <gateway_specific_field>payment_type</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>card_holder_identification_type</gateway_specific_field>
    <gateway_specific_field>card_holder_identification_number</gateway_specific_field>
    <gateway_specific_field>card_holder_door_number</gateway_specific_field>
    <gateway_specific_field>card_holder_birthday</gateway_specific_field>
    <gateway_specific_field>debit</gateway_specific_field>
    <gateway_specific_field>establishment_name</gateway_specific_field>
    <gateway_specific_field>fraud_detection</gateway_specific_field>
    <gateway_specific_field>site_id</gateway_specific_field>
    <gateway_specific_field>aggregate_data</gateway_specific_field>
    <gateway_specific_field>sub_payments</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>customer_email</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</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-09-29T14:19:23Z</created_at>
  <updated_at type="dateTime">2023-09-29T14:19:23Z</updated_at>
</gateway>

Enabling preauth mode

By default, Decidir gateways support purchase transactions, which executes the authorization and capture of funds in a single step. However, Decidir can be configured to require pre-authorization and capture in two steps. Currently, using the preauth mode means purchase actions are unsupported, and an authorize andcaptureaction must be used for every transaction.

To enable preauth mode, you must make a request to Decidir support to enable pre-authorization and capture for your account, also referred to as transactions in two steps. Decidir will provide an api_key that can only be used for pre-authorization and capture mode. To create a gateway that utilizes preauth mode, use the preauth and capture api_key from Decidir and set the preauth_mode gateway field to true.

Note: Verify transactions require preauth mode to be enabled and are unsupported if not using preauth mode.

For more information, please see the Decidir documentation for completing transactions in two steps.

Partial capture

When pre-authorization and capture is enabled, it is possible to perform a variable or partial capture of the amount that was pre-authorized. Decidir allows merchants to capture an amount equal to, less than, or greater than the pre-authorized amount, based on pre-configured percentage rules. Please contact Decidir support to set up this option.

See the Decidir transactions in two steps documentation for more information.

Gateway specific fields

When interacting with a Decidir gateway to run transactions, there are a number of gateway specific fields you can specify. See below for usage notes for certain fields, and Decidir’s documentation for more information.

payment_method_id - id of the payment method, used for bin validation; defaults to 1
debit - set to true if the payment method is a debit card in order to send the payment_method_id corresponding to the debit version of the identified card brand; defaults to false
payment_type - type of payment, one of single or distributed; defaults to single
installments - number of payment installments; defaults to 1
site_id - the specific merchant site for this transaction; for more information, see the Decidir documentation.
establishment_name - business name
fraud_detection - a container for fraud detection fields; for more information, see the Decidir documentation. These three fraud_detection sub-fields are currently supported:
- send_to_cs
- channel
- dispatch_method
- csmdds
aggregate_data - a container for the fields required for payment aggregators. See the Decidir documentation for more information.
sub_payments - container(s) for sub payments fields. See the Decidir documentation on distributed transactions for more information. These three sub_payments sub-fields are currently supported:
- site_id
- installments
- amount
customer_id - id associated with cardholder
customer_email - email associated with cardholder. Allows for direct pass in to the request if an email was not saved at the time of card tokenization.

The following fields are provided with Visa transactions for additional validation:

card_holder_identification_type - the card holder’s national identification type; DNI or CUIL
card_holder_identification_number - the card holder’s national identification number
card_door_number - the card holder’s delivery address door number
card_holder_birthday - the card holder’s birthday; formatted as MMDDYYYY

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>
          <decidir>
            <payment_method_id>1</payment_method_id>
            <payment_type>single</payment_type>
            <installments>1</installments>
            <card_holder_identification_type>DNI</card_holder_identification_type>
            <card_holder_identification_number>123456</card_holder_identification_number>
            <card_holder_door_number>1234</card_holder_door_number>
            <card_holder_birthday>01011980</card_holder_birthday>
            <debit>true</debit>
            <establishment_name>Business Name</establishment_name>
            <site_id>99999999</site_id>
            <fraud_detection>
              <send_to_cs>false</send_to_cs>
              <channel>Web</channel>
              <dispatch_method>Store Pick Up</dispatch_method>
              <csmdds>
                <code>17</code>
                <description>Campo MDD17</description>
              </csmdds>
            </fraud_detection>
            <aggregate_data>
              <indicator>1</indicator>
              <identification_number>308103480</identification_number>
              <bill_to_pay>test1</bill_to_pay>
              <bill_to_refund>test2</bill_to_refund>
              <mechant_name>Merchant</mechant_name>
              <street>Main</street>
              <number>1234</number>
              <postal_code>12345</postal_code>
              <category>111</category>
              <channel>005</channel>
              <geographic_code>C1234</geographic_code>
              <city>Ciudad de Buenos Aires</city>
              <merchant_id>dec_agg</merchant_id>
              <province>Buenos Aires</province>
              <country>Argentina</country>
              <merchant_email>[email protected]</merchant_email>
              <merchant_phone>2678433111</merchant_phone>
            </aggregate_data>
            <sub_payments>
              <site_id>01234</site_id>
              <installments>2</installments>
              <amount>451</amount>
            </sub_payments>
            <customer_id>abc123</customer_id>
            <customer_email>[email protected]</customer_email>
          </decidir>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2023-09-29T14:08:06Z</created_at>
  <updated_at type="dateTime">2023-09-29T14:08:06Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>ZCUrEacyRyLAaqnOCw5eteN9khr</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>
    <decidir>
      <payment_method_id>1</payment_method_id>
      <payment_type>single</payment_type>
      <installments>1</installments>
      <card_holder_identification_type>DNI</card_holder_identification_type>
      <card_holder_identification_number>123456</card_holder_identification_number>
      <card_holder_door_number>1234</card_holder_door_number>
      <card_holder_birthday>01011980</card_holder_birthday>
      <debit>true</debit>
      <establishment_name>Business Name</establishment_name>
      <site_id>99999999</site_id>
      <fraud_detection>
        <send_to_cs>false</send_to_cs>
        <channel>Web</channel>
        <dispatch_method>Store Pick Up</dispatch_method>
        <csmdds>
          <code>17</code>
          <description>Campo MDD17</description>
        </csmdds>
      </fraud_detection>
      <aggregate_data>
        <indicator>1</indicator>
        <identification_number>308103480</identification_number>
        <bill_to_pay>test1</bill_to_pay>
        <bill_to_refund>test2</bill_to_refund>
        <mechant_name>Merchant</mechant_name>
        <street>Main</street>
        <number>1234</number>
        <postal_code>12345</postal_code>
        <category>111</category>
        <channel>005</channel>
        <geographic_code>C1234</geographic_code>
        <city>Ciudad de Buenos Aires</city>
        <merchant_id>dec_agg</merchant_id>
        <province>Buenos Aires</province>
        <country>Argentina</country>
        <merchant_email>[email protected]</merchant_email>
        <merchant_phone>2678433111</merchant_phone>
      </aggregate_data>
      <sub_payments>
        <site_id>01234</site_id>
        <installments>2</installments>
        <amount>451</amount>
      </sub_payments>
      <customer_id>abc123</customer_id>
      <customer_email>[email protected]</customer_email>
    </decidir>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>63</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-09-29T14:08:06Z</created_at>
    <updated_at type="dateTime">2023-09-29T14:08:06Z</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-09-24T16:41:41Z</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 Decidir may contain the following fields:

card_authorization_code
merchant_id
site_id
site_transaction_id
ticket
payment_method_id
bin
installments
payment_type
sub_payments
txn_token
additional_description (on failed transactions)

 <transaction>
    <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
    <transaction_type>Store</transaction_type>
    <gateway_specific_response_fields>
       <decidir>
         <card_authorization_code>123456</card_authorization_code>
         <merchant_id>11111</merchant_id>
         <site_id>74747</site_id>
         <ticket>78902345</ticket>
         <site_transaction_id>919abcde2013</site_transaction_id>
         <payment_method_id>1</payment_method_id>
         <bin>123456</bin>
         <installments>3</installments>
         <payment_type>Single</payment_type>
         <sub_payments>['A', 'B', 'C']<sub_payments>
         <txn_token>12345abcde<txn_token>
         <additional_description>NO REINTENTAR USE OTRA TARJETA<additional_description>
       </decidir>
    </gateway_specific_response_fields>
  </transaction>

Please refer to using a payment method for more information on how to send GSFs

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.

Syncing transactions

Spreedly supports updating the status of transactions that have been initiated at the Decidir gateway. Decidir currently only supports using gateway_transaction_id for updates which would be the payment_id of the order. See our documentation for more information.

Network Tokenization

Decidir only accepts Visa network tokens. If a non-Visa network token is passed then the transaction will fallback to use PAN.