WorldPay Gateway Guide

close

Services and Compatibility

Payment Gateway Company Name:
WorldPay
Services that work with Spreedly:
  • Corporate Gateway
  • Business Gateway
Services that do not work with Spreedly:
  • If recurring is important to you, avoid being set up with two MID’s. You should put all transactions (new and recurring) through just the one MID.
Supported operations:
Purchase, Authorize, Capture, Refund, Void, Verify, Store, General Credit
Supported payment types:
Credit Card
3D Secure 1 Supported
Yes
3D Secure 2 Supported
Yes
Regions:
Asia Pacific, Europe, Middle East, North America
API endpoint URL:
https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp

Authentication and Security

Specific names for credentials:
Login, Password
Additional steps needed to activate?
Turn off the capture delay setting. (See notes)

Onboarding Merchants in:

Additional Notes

For US based acquiring accounts, see WorldPay US.

There is a setting in your WorldPay Merchant Interface called Capture Delay which is set to on by default within Worldpay. You’ll need to login and turn that setting off.

In addition, if you tell WorldPay you are working with Spreedly you can usually bypass the need to do a full test transaction before being pushed into production. Lastly, you’ll want to be approved for the “XML Invisible” installation.

Using Visa and Mastercard cards retained with Spreedly falls under Stored Credentials regulations.

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. During 3DS 2.0 transactions you may need to pass additional parameters with completion calls. More information can be found in step 7 of the 3DS 2.0 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>Bv1rubskH9tnHEKABhgrvCczG2f</token>
  <gateway_type>worldpay</gateway_type>
  <name>WorldPay</name>
  <description nil="true"/>
  <login>Your Merchant Code (may be called Merchant 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_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_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>
  </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_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2019-09-16T21:02:37Z</created_at>
  <updated_at type="dateTime">2019-09-16T21:02: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:0x00007fe8202a4da0
@token="PRE9R0UqgbPr7pyQ1w3SYaTyjA9",
@created_at="2019-09-16T21:02:38Z",
@updated_at="2019-09-16T21:02:38Z",
@gateway_type="worldpay",
@state="retained",
@name="WorldPay",
@credentials={"login"=>"Your login"}>

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, transaction_identifier, 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 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.

Spreedly Field Worldpay Field
three_ds_version threeDSVersion
ecommerce_indicator eci
authentication_value cavv
directory_server_transaction_id dsTransactionId

Support for General Credit operation

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.

Support for Store operation

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 a unique customer_id Gateway Specific Field.

Optional 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

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

cpf is only applicable for Brazillian 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.


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

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>
     </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.