• Documentation
• WorldPay

WorldPay Gateway Guide

Adding a Worldpay gateway

To add a WorldPay gateway:

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>worldpay</gateway_type>
        <login>Your Merchant Code (may be called Merchant ID)</login>
        <password>Your XML Password</password>
        <hmac_secret> HMAC Secret </hmac_secret>
        <issuer_id> Issuer ID</issuer_id>
        <org_unit_id> Organization Unit Id</org_unit_id>
      </gateway>'

<gateway>
  <token>IFEnzFllMG2bcTo7fWmVe6xH4sS</token>
  <gateway_type>worldpay</gateway_type>
  <name>WorldPay</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <login>Your Merchant Code (may be called Merchant ID)</login>
  <issuer_id> Issuer ID</issuer_id>
  <org_unit_id> Organization Unit Id</org_unit_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">true</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">true</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">true</supports_3dsecure_purchase>
    <supports_3dsecure_authorize type="boolean">true</supports_3dsecure_authorize>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</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">true</supports_network_tokenization>
    <supports_populate_mit_fields type="boolean">false</supports_populate_mit_fields>
    <supports_3dsecure_2_purchase type="boolean">true</supports_3dsecure_2_purchase>
    <supports_3dsecure_2_authorize type="boolean">true</supports_3dsecure_2_authorize>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>Your Merchant Code (may be called Merchant ID)</value>
    </credential>
    <credential>
      <name>issuer_id</name>
      <value> Issuer ID</value>
    </credential>
    <credential>
      <name>org_unit_id</name>
      <value> Organization Unit Id</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>installation_id</gateway_specific_field>
    <gateway_specific_field>hcg_additional_data</gateway_specific_field>
    <gateway_specific_field>session_id</gateway_specific_field>
    <gateway_specific_field>user_agent</gateway_specific_field>
    <gateway_specific_field>accept_header</gateway_specific_field>
    <gateway_specific_field>instalments</gateway_specific_field>
    <gateway_specific_field>cpf</gateway_specific_field>
    <gateway_specific_field>stored_credential_usage</gateway_specific_field>
    <gateway_specific_field>stored_credential_initiated_reason</gateway_specific_field>
    <gateway_specific_field>stored_credential_transaction_id</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>bypass_authorization_status_check</gateway_specific_field>
    <gateway_specific_field>exemption_type</gateway_specific_field>
    <gateway_specific_field>exemption_placement</gateway_specific_field>
    <gateway_specific_field>risk_data</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>skip_capture</gateway_specific_field>
    <gateway_specific_field>statement_narrative</gateway_specific_field>
    <gateway_specific_field>cancel_or_refund</gateway_specific_field>
    <gateway_specific_field>order_content</gateway_specific_field>
    <gateway_specific_field>zero_dollar_auth</gateway_specific_field>
    <gateway_specific_field>pf_id</gateway_specific_field>
    <gateway_specific_field>sub_name</gateway_specific_field>
    <gateway_specific_field>sub_id</gateway_specific_field>
    <gateway_specific_field>sub_street</gateway_specific_field>
    <gateway_specific_field>sub_city</gateway_specific_field>
    <gateway_specific_field>sub_state</gateway_specific_field>
    <gateway_specific_field>sub_country_code</gateway_specific_field>
    <gateway_specific_field>sub_postal_code</gateway_specific_field>
    <gateway_specific_field>sub_tax_id</gateway_specific_field>
    <gateway_specific_field>fast_fund_credit</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</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>
  <created_at type="dateTime">2021-12-06T22:40:37Z</created_at>
  <updated_at type="dateTime">2021-12-06T22:40:37Z</updated_at>
</gateway>

env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.add_gateway(:worldpay, login: "Your login", password: "Your password", hmac_secret: "HMAC Secret", issuer_id: "Issuer ID", org_unit_id: "Org Unit Id")

#<Spreedly::Gateway:0x00007f9b1384ecb0
@token="WfubzChW0coNlssAOmEuCmDB7uJ",
@created_at="2021-12-06T22:40:38Z",
@updated_at="2021-12-06T22:40:38Z",
@gateway_type="worldpay",
@state="retained",
@name="WorldPay",
@credentials={"login"=>"Your login", "issuer_id"=>"Issuer ID", "org_unit_id"=>"Org Unit Id"}>

Stored credentials regulations

For Worldpay there are two options for sending stored credential fields. You can either use Spreedly’s native support which is less hands on, or use gateway specific fields. Using gateway specific fields will give you more fine grain control over what it sent, however you will need to store additional data from the gateway that is returned from the gateway in a gateway specific response field.

The three gateway specific fields are stored_credential_usage, stored_credential_transaction_id, and stored_credential_initiated_reason. Note that the transaction_identifier is a Gateway Specific Response Field returned from the first use of a stored payment method. Additionally, it is different from a transaction’s gateway_transaction_id and you should track and provide with any subsequent transactions using that retained card.

For more information on the accepted values for these fields, see Worldpay’s “Stored Credentials” documentation.

3DS 2.0 Gateway Specific

Spreedly supports gateway specific 3DS 2.0 via Worldpay.

Worldpay has a couple of 3DS2 implementations. The one that Spreedly connects to is 3DS FLEX (DIRECT). Before using Worldpay for 3DS 2.0 transactions you must first onboard through Worldpay. After successfully completing this step you will need to update your gateway fields to include hmac_secret, issuer_id and org_unit_id. Worldpay may give you these values as API key, API ID and Org Unit ID respectively.

During 3DS 2.0 transactions you may need to pass additional parameters with completion calls based on the trigger-completion event. Worldpay uses postMessages to notify when authentication needs to progress to the next step. We pass these parameters in event.context.

{"MessageType": "profile.completed", "SessionId": "d3197c02-6f63-4ab2-801c-83633d097e32","Status": true)

These parameters should be included in the complete call using the key context.

{context: {"MessageType": "profile.completed", "SessionId": "d3197c02-6f63-4ab2-801c-83633d097e32", "Status": true}}

More information can be found in Step 3 of Handle transaction response in Gateway Specific 3DS2 Guide

3DS 2.0 exemptions

When conducting 3DS 2.0 transactions you may use the gateway specific fields exemption_type and exemption_placement. See Worldpay’s third-party 3DS2 documentation for more detailed descriptions.

Third-party 3D Secure 2 auth data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Worldpay. For more information about how to use this feature, see the 3DS2 Third-party Authentication Guide. Spreedly fields map to the relevant Worldpay fields as described in the following table. Please see Worldpay’s third-party 3DS2 documentation for detailed descriptions of each of these fields and when to use them.

General Credit operation setup

In order to perform General Credit transactions with Worldpay, special setup is required. First, you must obtain a second Merchant ID (aka Merchant Code) from Worldpay, requesting with them that it be flagged for Credit Fund Transfers (CFT, aka Payouts). Then, you must create a second Worldpay gateway with Spreedly using that Merchant ID. This second gateway can, and should only be used for General Credit transactions; all other normal transactions, including normal credits/refunds, should be performed with your original Worldpay gateway instance that uses your normal “eCom” Merchant ID.

Spreedly is also integrated with Visa Direct Fast Funds through Worldpay. In order to perform General Credit using the Visa Direct Fast Funds feature, you must first request that Worldpay enable this feature on the Merchant ID you use for General Credit transactions (described above). Once this feature is enabled, you may specify that a General Credit transaction be performed using Visa Direct Fast Funds by passing true in the fast_fund_credit gateway specific field. General Credit transactions that omit the fast_fund_credit field will perform a standard General Credit.

Store operation setup

In order to use Third Party Vaulting via the Store operation with WorldPay, you must first contact your WorldPay Relationship Manager to have Tokenisation enabled for your merchant account. Please see WorldPay’s “Before you connect to Tokenisation” for full details on prerequisites.

Additionally, when storing a payment method in WorldPay’s vault, you must pass the unique customer_id gateway specific field.

You can still take advantage of stored credentials when storing a payment method in WorldPay’s vault by including the stored_credential_transaction_id gateway-specific field in your store call.

Gateway specific fields

Spreedly supports the following gateway specific fields when transacting with WorldPay:

• hcg_additional_data
• installation_id
• session_id (required for 3DS; typically passed along with IP address of end-user customer)
• user_agent
• accept_header
• instalments (note the single l)
• cpf
• stored_credential_usage
• stored_credential_initiated_reason
• stored_credential_transaction_id
• customer_id
• exemption_type
• exemption_placement
• bypass_authorization_status_check
• risk_data
• idempotency_key
• skip_capture
• statement_narrative
• cancel_or_refund
• order_content
• zero_dollar_auth
• pf_id
• sub_id
• sub_name
• sub_street
• sub_city
• sub_state
• sub_country_code
• sub_postal_code
• sub_tax_id
• fast_fund_credit

session_id, user_agent and accept_header must be used in 3D Secure transactions.

cpf is only applicable for Brazilian customers paying in installments. Please see WorldPay’s official documentation for more information.

stored_credential fields apply to retained Visa and Mastercard cards. See Worldpay’s “Stored Credentials” documentation for details on usage.

risk_data fields are optional and used to increase the chance that a shopper won’t be challenged. See Worldpay’s “Risk Data” documentation for more details.

idempotency_key is available only to merchants who have been set up for it through Worldpay. See Worldpay’s “Idempotency” documentation for more details.

skip_capture can be used with Purchase transactions. If any value is provided for this field, Spreedly will run an authorization for the purchase, but will not attempt to capture the authorized amount. This will allow a transaction that is marked for the gateway to capture automatically to complete successfully.

statement_narrative provides additional information to the shopper on their statement. See Worldpay’s “Statement Narrative” documentation for more details.

Passing the cancel_or_refund field set to true on a void or refund call will void a transaction that has not settled or refund a settled transaction. When passing this field, it is recommended to also set the bypass_authorization_status_check field to true. While this flag may be set on refund calls, note that Worldpay does not support partial amount refunds when this flag is set.

The order_content element can contain a more detailed description of purchased products/services, supplied in HTML format. See Worldpay’s “Order details” documentation for more details.

In order to run verify transactions with a $0 amount, that feature must be activated on your Worldpay account. You may then pass the zero_dollar_auth field with a value of true to run a verification for $0.

Sub Merchant Data:

pf_id - Payment facilitator ID, obtained from Mastercard/Visa. - Mandatory

sub_id - Sub-merchant ID, supplied by payment faciliator - Mandatory

sub_name - Sub-merchant name, supplied by payment faciliator - Mandatory

sub_street - Sub-merchant street address, only 26 characters will be sent for processing. - Mandatory

sub_city - Sub-merchant city, could be physical city name or web address and so on. - Mandatory

sub_state - Sub-merchant state, mandatory for USA, CAN, and ITA sub-merchants. - Conditional

sub_country_code - Sub-merchant country code - Mandatory

sub_postal_code - Sub-merchant postal code - Mandatory

sub_tax_id - Sub-merchant tax ID, mandatory for USA and CAN sub-merchants. - Conditional

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>
          <worldpay>
            <hcg_additional_fields>
              <key1>value1</key1>
              <key2>value2</key2>
              <key3>value3</key3>
            </hcg_additional_fields>
            <risk_data>
              <authentication_risk_data>
                <authentication_date>
                  <second>32</second>
                  <minute>47</minute>
                  <hour>16</hour>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </authentication_date>
                <authentication_method>localAccount</authentication_method>
              </authentication_risk_data>
              <shopper_account_risk_data>
                <add_card_attempts_last_day>4</add_card_attempts_last_day>
                <previous_suspicious_activity>false</previous_suspicious_activity>
                <purchases_completed_last_six_months>3</purchases_completed_last_six_months>
                <shipping_name_matches_account_name>true</shipping_name_matches_account_name>
                <shopper_account_age_indicator>lessThanThirtyDays</shopper_account_age_indicator>
                <shopper_account_change_indicator>thirtyToSixtyDays</shopper_account_change_indicator>
                <shopper_account_creation_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </shopper_account_creation_date>
                <shopper_account_modification_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </shopper_account_modification_date>
                <shopper_account_password_change_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </shopper_account_password_change_date>
                <shopper_account_password_change_indicator>noChange</shopper_account_password_change_indicator>
                <shopper_account_payment_account_first_use_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </shopper_account_payment_account_first_use_date>
                <shopper_account_payment_account_indicator>thirtyToSixtyDays</shopper_account_payment_account_indicator>
                <shopper_account_shipping_address_first_use_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </shopper_account_shipping_address_first_use_date>
                <shopper_account_shipping_address_usage_indicator>moreThanSixtyDays</shopper_account_shipping_address_usage_indicator>
                <transactions_attempted_last_day>1</transactions_attempted_last_day>
                <transactions_attempted_last_year>2</transactions_attempted_last_year>
              </shopper_account_risk_data>
              <transaction_risk_data>
                <delivery_email_address>abe@lincoln.gov</delivery_email_address>
                <delivery_timeframe>sameDayShipping</delivery_timeframe>
                <gift_card_count>1</gift_card_count>
                <pre_order_purchase>false</pre_order_purchase>
                <reordering_previous_purchases>false</reordering_previous_purchases>
                <shipping_method>shipToBillingAddress</shipping_method>
                <transaction_risk_data_gift_card_amount>
                  <currency>EUR</currency>
                  <debit_credit_indicator>credit</debit_credit_indicator>
                  <exponent>2</exponent>
                  <value>123</value>
                </transaction_risk_data_gift_card_amount>
                <transaction_risk_data_pre_order_date>
                  <day_of_month>21</day_of_month>
                  <month>11</month>
                  <year>2029</year>
                </transaction_risk_data_pre_order_date>
              </transaction_risk_data>
            </risk_data>
            <installation_id>abc1234</installation_id>
            <session_id>0215ui8ib1</session_id>
            <user_agent>Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0</user_agent>
            <accept_header>text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</accept_header>
            <instalments>12</instalments>
            <cpf>678</cpf>
            <stored_credential_usage>USED</stored_credential_usage>
            <stored_credential_initiated_reason>UNSCHEDULED</stored_credential_initiated_reason>
            <stored_credential_transaction_id>456</stored_credential_transaction_id>
            <exemption_type>Exemption Type</exemption_type>
            <exemption_placement>Exemption Placement</exemption_placement>
            <skip_capture>true</skip_capture>
            <statement_narrative>MERCHANT STATEMENT NARRATIVE</statement_narrative>
            <cancel_or_refund>false</cancel_or_refund>
            <order_content></order_content>
            <zero_dollar_auth>true</zero_dollar_auth>
            <pf_id>12345678901</pf_id>
            <sub_name>Example Shop</sub_name>
            <sub_id>1234567</sub_id>
            <sub_street>123 Street</sub_street>
            <sub_city>San Francisco</sub_city>
            <sub_state>CA</sub_state>
            <sub_country_code>840</sub_country_code>
            <sub_postal_code>94101</sub_postal_code>
            <sub_tax_id>987-65-4321</sub_tax_id>
            <fast_fund_credit>false</fast_fund_credit>
          </worldpay>
        </gateway_specific_fields>
      </transaction>'

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

Store-specific customer_id field

When storing a credit card in the WorldPay vault using third party vaulting, you must specify a unique customer_id (which maps to WorldPay’s authenticatedShopperID element) per shopper. Please see WorldPay’s “Create shopper tokens” documentation for details on requirements and recommendations.

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>
          <worldpay>
            <customer_id>2b66bc3789b1eea995a2b4f7e5a42c09</customer_id>
          </worldpay>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <created_at type="dateTime">2019-05-31T17:29:48Z</created_at>
  <currency_code nil="true"/>
  <updated_at type="dateTime">2019-05-31T17:29:48Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <token>SvzUsbdPXf3jKcpEx2CDFMdwV7h</token>
  <state>succeeded</state>
  <gateway_specific_fields>
    <worldpay>
      <customer_id>2b66bc3789b1eea995a2b4f7e5a42c09</customer_id>
    </worldpay>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <transaction_type>Store</transaction_type>
  <third_party_token nil="true"/>
  <gateway_transaction_id>49</gateway_transaction_id>
  <gateway_latency_ms type="integer">31</gateway_latency_ms>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <payment_method>
    <token>7MHuBhhSVM50v7u1b6aZRUtBWXC</token>
    <created_at type="dateTime">2019-05-31T17:29:48Z</created_at>
    <updated_at type="dateTime">2019-05-31T17:29:48Z</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">2019-05-31T17:29:48Z</updated_at>
    <email>joey@example.com</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>
  </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 nil="true"/>
    <error_detail nil="true"/>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"/>
    <created_at type="dateTime">2019-05-31T17:29:48Z</created_at>
    <updated_at type="dateTime">2019-05-31T17:29:48Z</updated_at>
  </response>
</transaction>

env = Spreedly::Environment.new('C7cRfNJGODKh4Iu5Ox3PToKjniY', '4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ', base_url: 'https://core.spreedly.com')
env.purchase_on_gateway("LlkjmEk0xNkcWrNixXa1fvNoTP4", "56wyNnSmuA6CWYP7w0MiYCVIbW6", 4432,
  gateway_specific_fields: {
    worldpay: {
      customer_id: "2b66bc3789b1eea995a2b4f7e5a42c09"
    }
  }
)

#<Spreedly::Purchase:0x00007fd3798ca808
@token="9UhFwpV8SWKWH2QTwjAK57CtxXZ",
@created_at="2019-05-31T17:37:48Z",
@updated_at="2019-05-31T17:37:48Z",
@state="succeeded",
@message="Succeeded!",
@succeeded="true",
@order_id="",
@ip="",
@description="",
@gateway_token="T11bJAANtTWnxl36GYjKWvbNK0g",
@gateway_transaction_id="49",
@email="",
@merchant_name_descriptor="",
@merchant_location_descriptor="",
@on_test_gateway="true",
@currency_code="USD",
@amount="4432",
@response,=
#<Spreedly::Response:0x00007fd3798b8ef0
@success="true",
@pending="false",
@cancelled="false",
@fraud_review="",
@created_at="2019-05-31T17:37:48Z",
@updated_at="2019-05-31T17:37:48Z",
@message="Successful purchase",
@avs_code="",
@avs_message="",
@cvv_code="",
@cvv_message="",
@error_code="",
@error_detail="">,
@shipping_address,=
#<Spreedly::ShippingAddress:0x00007fd3798aa300
@name="Newfirst Newlast",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="">,
@gateway_specific_fields={:worldpay=>{:customer_id=>"2b66bc3789b1eea995a2b4f7e5a42c09"}},
@payment_method,=
#<Spreedly::CreditCard:0x00007fd3798a2510
@token="1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
@created_at="2017-06-26T17:04:38Z",
@updated_at="2019-05-31T17:33:24Z",
@email="joey@example.com",
@storage_state="retained",
@data="<my_payment_method_identifier>448</my_payment_method_identifier>\n      <extra_stuff>\n        <some_other_things>Can be anything really</some_other_things>\n      </extra_stuff>",
@first_name="Newfirst",
@last_name="Newlast",
@full_name="Newfirst Newlast",
@month="3",
@year="2032",
@number="XXXX-XXXX-XXXX-1111",
@last_four_digits="1111",
@first_six_digits="411111",
@card_type="visa",
@verification_value="",
@address1="",
@address2="",
@city="",
@state="",
@zip="",
@country="",
@phone_number="",
@company="",
@fingerprint="e3cef43464fc832f6e04f187df25af497994",
@eligible_for_card_updater="true",
@errors=[]>>

Multiple partial refunds

In order to perform multiple partial refunds, you must set the gateway specific field bypass_authorization_status_check to true. This will bypass checking the status of the reference authorization, allowing you to submit a subsequent refund request even if the authorization status is REFUNDED.

NOTE: It is recommended that you perform refunds without the bypass_authorization_status_check field and only use the field if you wish to force a refund of a settled transaction. Setting the bypass_authorization_status_check field for a refund will prevent unsettled transactions from being voided.

curl https://core.spreedly.com/v1/transactions/KS3oZgWXCfFeirK16anYbijLxR/credit.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <amount>50</amount>
        <currency_code>USD</currency_code>
        <gateway_specific_fields>
          <worldpay>
            <bypass_authorization_status_check>true</bypass_authorization_status_check>
          </worldpay>
        </gateway_specific_fields>
      </transaction>'

<transaction>
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2019-09-17T14:54:41Z</created_at>
  <updated_at type="dateTime">2019-09-17T14:54:41Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <state>succeeded</state>
  <token>WucDSXyY6oD4NBWzTdSS6oYVEkn</token>
  <transaction_type>Credit</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>
    <worldpay>
      <bypass_authorization_status_check>true</bypass_authorization_status_check>
    </worldpay>
  </gateway_specific_fields>
  <gateway_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>64</gateway_transaction_id>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"/>
  <stored_credential_reason_type nil="true"/>
  <amount type="integer">50</amount>
  <currency_code>USD</currency_code>
  <message key="messages.transaction_succeeded">Succeeded!</message>
  <gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <name nil="true"/>
    <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 credit</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">2019-09-17T14:54:41Z</created_at>
    <updated_at type="dateTime">2019-09-17T14:54:41Z</updated_at>
  </response>
  <api_urls>
  </api_urls>
  <reference_token>Tp99vI4yQ959K4ezNklLtEiqLWF</reference_token>
</transaction>

Gateway specific response fields

A response from WorldPay gateway may contain some of a number of specific fields which you can find in the gateway_specific_response_fields.

For example:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0R8p</token>
  <transaction_type>Purchase</transaction_type>
  <gateway_specific_response_fields>
     <worldpay>
       <authorisation_id>123</authorisation_id>
       <cvc_result_code_description>NOT SUPPLIED BY SHOPPER</cvc_result_code_description>
       <issuer_country_code>US</issuer_country_code>
       <iso8583_return_code_code>51</iso8583_return_code_code>
       <iso8583_return_code_description>LIMIT EXCEEDED</iso8583_return_code_description>
       <acquirer_return_description>insufficient funds</acquirer_return_description>
       <transaction_identifier>456</transaction_identifier>
       <three_d_secure_result>Cardholder Authenticated</three_d_secure_result>
       <issuer_response_code>7</issuer_response_code>
       <issuer_response_description>Pickup Card</issuer_response_description>
     </worldpay>
  </gateway_specific_response_fields>
</transaction>

transaction_identifier is used for Stored Credentials transactions.

If you’d like 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 WorldPay gateway. WorldPay currently supports using gateway_transaction_id or order_id for updates. The gateway_transaction_id would be the payment_id or order_id. While order_id is the order code used by the merchant in WorldPay’s system.
See our documentation for more information.