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, General Credit
Supported payment types:
Credit Card
Does Spreedly support 3D Secure with this gateway?
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.

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>
      </gateway>'

<gateway>
  <token>3PiysOPhJXcfIW3phTEeEK7T9zy</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_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_store type="boolean">false</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
  </characteristics>
  <credentials>
    <credential>
      <name>login</name>
      <value>Your Merchant Code (may be called Merchant ID)</value>
    </credential>
  </credentials>
  <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_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <created_at type="dateTime">2018-11-26T16:23:51Z</created_at>
  <updated_at type="dateTime">2018-11-26T16:23:51Z</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")


#<Spreedly::Gateway:0x007fe33380f3e0
@token="B8teZ0xLpHz5BMCfjbwx53EAH0Y",
@created_at="2017-07-27T17:51:25Z",
@updated_at="2017-07-27T17:51:25Z",
@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.

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.

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

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