FlexCharge Gateway Guide

FlexFactor fact sheet

Additional notes
To properly implement FlexFactor merchants may need to integrate the Sensejs and UI Widget. These front end components are needed to be able to present to customers the FlexFactor challenge in the cases where transactions need extra information. In these scenarios, use Sync to finalize the state of the transaction at Spreedly.

Adding a FlexFactor (FlexCharge) gateway

To add a FlexFactor gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>flex_charge</gateway_type>
        <app_key>app_key</app_key>
        <app_secret>app_secret</app_secret>
        <site_id>site_id</site_id>
        <mid>mid</mid>
      </gateway>'

<gateway>
  <token>4YZ4M1S7GX8XVTMVSX9DCP3YDN</token>
  <gateway_type>flex_charge</gateway_type>
  <name>FlexCharge</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <site_id>ffae80fd-2b8e-487a-94c3-87503a0c71bb</site_id>
  <mid>d9d0b5fd-9433-44d3-8051-63fee28768e8</mid>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">false</supports_authorize>
    <supports_capture type="boolean">false</supports_capture>
    <supports_credit type="boolean">false</supports_credit>
    <supports_general_credit type="boolean">false</supports_general_credit>
    <supports_void type="boolean">false</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <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">true</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">false</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>
    <credential>
      <name>site_id</name>
      <value>ffae80fd-2b8e-487a-94c3-87503a0c71bb</value>
    </credential>
    <credential>
      <name>mid</name>
      <value>d9d0b5fd-9433-44d3-8051-63fee28768e8</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>is_mit</gateway_specific_field>
    <gateway_specific_field>is_recurring</gateway_specific_field>
    <gateway_specific_field>subscription_id</gateway_specific_field>
    <gateway_specific_field>subscription_interval</gateway_specific_field>
    <gateway_specific_field>mit_expiry_date_utc</gateway_specific_field>
    <gateway_specific_field>is_declined</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>card_not_present</gateway_specific_field>
    <gateway_specific_field>response_code</gateway_specific_field>
    <gateway_specific_field>response_code_source</gateway_specific_field>
    <gateway_specific_field>avs_result_code</gateway_specific_field>
    <gateway_specific_field>cvv_result_code</gateway_specific_field>
    <gateway_specific_field>cavv_result_code</gateway_specific_field>
    <gateway_specific_field>timezone_utc_offset</gateway_specific_field>
    <gateway_specific_field>sense_key</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">true</sandbox>
  <mode>default</mode>
  <created_at type="dateTime">2024-06-07T16:38:31Z</created_at>
  <updated_at type="dateTime">2024-06-07T16:38:31Z</updated_at>
</gateway>

Transacting with FlexFactor (FlexCharge)

To transact with FlexFactor, description is required.

Transactions may return a state of processing. In these scenarios you will need to manage the front end interaction with your customer and FlexFactor to collect the extra information required. When that is complete, sync the transaction to match the final state in Spreedly's systems.

Gateway specific fields

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

is_mit: true/false to indicate if this a merchant initiated transaction.
is_recurring: true/false to indicate if this is part of a recurring transaction.
subscription_id: if is a recurring txn the subscription identifier.
subscription_interval: subscription interval 'daily', 'weekly', 'monthly', 'quarterly', 'yearly'.
mit_expiry_date_utc: Iso8601 timestamp Indicates period during which FlexFactor will retry the transaction.
is_declined: true/false original transaction was declined.
idempotency_key: A unique GUID/UUID, to identify repeated requests.
response_code: original transaction response code, E.g.: '203'
response_code_source: original transaction source, E.g.: 'NMI', 'Paypal'
avs_result_code: Address Verification Service result code, E.g.: "M"
cvv_result_code: Card Verification Value result code,
cavv_result_code: Cardholder Authentication Verification Value result code, E.g.: "2"
timezone_utc_offset: UTC offset of the timezone. E.g.: "0", "-5"
extra_data: This value should be a JSON object that includes extra data that FlexFactor may require for the transactions. Please work with FlexFactor to understand which fields you should include

For more information about each field go to FlexFactor Rest API explorer

Gateway specific fields usage example:

curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>xxxxxxxxxx</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <description>MyShoesStore</description>
        <email>[email protected]</email>
        <billing_address>
          <name>Cure Tester</name>
          <phone_number>(555)555-5555</phone_number>
          <address1>456 My Street</address1>
          <company>Widgets Inc</company>
          <city>Ottawa</city>
          <state>ON</state>
          <country>CA</country>
          <zip>K1C2N6</zip>
        </billing_address>
        <gateway_specific_fields>
          <flex_charge>
            <is_mit>true</is_mit>
            <is_recurring>false</is_recurring>
            <mit_expiry_date_utc>2024-05-21T23:00:19Z</mit_expiry_date_utc>
            <is_declined>true</is_declined>
            <idempotency_key>6bff6ffe-2a30-4829-84fa-ed5000186ab6</idempotency_key>
            <response_code>100</response_code>
            <response_code_source>nmi</response_code_source>
            <avs_result_code>200</avs_result_code>
            <cvv_result_code>111</cvv_result_code>
            <cavv_result_code>111</cavv_result_code>
            <timezone_utc_offset>-5</timezone_utc_offset>
            <extra_data>"{\"hello\":\"world\"}"</extra_data>
          </flex_charge>
        </gateway_specific_fields>
      </transaction>'

Syncing Transactions

Spreedly supports updating the status of transactions that have been initiated at the FlexFactor gateway. For transactions that are in a "processing" state and require the FlexFactor front end Challenge, use Sync after completing the required front end information. See our documentation for more information.

Third-party 3D Secure 2 Authentication Data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to FlexFactor.

In order to use 3DS Global & FlexFactor, you will need to perform a Standalone Authentication and then transact using the Authenticated token. For more information about how to use this feature, see the 3DS2 Third-party Authentication Guide.

Spreedly fields map to the relevant FlexFactor fields as described in the following table. Please see FlexFactor transaction variable documentation for detailed descriptions of each of these fields and when to use them.

SPREEDLY FIELD	FLEXCHARGE FIELD
`three_ds_version`	`threeDsVersion`
`ecommerce_indicator`	`ecommerceIndicator`
`authentication_value`	`authenticationValue`
`directory_server_transaction_id`	`directoryServerTransactionId`
`directory_response_status`	`directoryResponseStatus`
`enrolled`	`enrolled`
`xid`	`xid`
`authentication_response_status`	`authenticationResponseStatus`
`authentication_value_algorithm`	`authenticationValueAlgorithm`