Worldpay gateway guide

Quick Start

New to integrating Worldpay with Spreedly? Here's your setup guide:

  1. Retrieve your Worldpay credentials
    1. Contact the Worldpay support team to obtain API credentials
  2. Get familiar with the Spreedly API
    1. Review Spreedly API basics
    2. Understand the core concepts: Gateways, Payment Methods, and Transactions
  3. Add Worldpay gateway to Spreedly in sandbox mode
📘

Review this documentation to understand more about how to test transactions.

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 3DS Global you will need to have your account configured or you will receive the following message: “Your contract does not allow using an merchant-located MPI”.

order_id is used to populate the required attribute orderCode of the <order> element for Worldpay. This is a required field.

When using Network Tokens on Worldpay you will need to ensure you are sending stored credential fields to Spreedly to ensure proper request flagging. If stored credential fields are not sent, transactions could fail with generic decline codes.

Adding a Worldpay gateway

Required Credentials

merchant_id: Your Worldpay merchant identifier (merchant ID)

passcode: Your Worldpay passcode used authentication.

Option Gateway Setting (3DS)

hmac_secret: Your Worldpay HMAC Secret.

issuer_id: Your Worldpay Issuer ID.

org_unit_id: Your Worldpay Org Unit ID.

Request:

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

Response:

<gateway>
  <token>IFEnzFllMG2bcTo7fWmVe6xxyzS</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">false</supports_network_tokenization>
    <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_field>custom_string_fields</gateway_specific_field>
    <gateway_specific_field>refund_reference</gateway_specific_field>
    <gateway_specific_field>partial_authorisation</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>

Purchase

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 1000,
      "currency_code": "USD"
    }
  }'

Advanced features

3DS2 gateway-specific

Spreedly supports gateway specific 3DS20 via Worldpay.

Worldpay has a couple of 3DS2 implementations. The one that Spreedly connects to is 3DS Flex with Cardinal. 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}}

3DS2 exemptions

When conducting 3DS2 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 3DS2 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 fieldWorldpay field
three_ds_versionthreeDSVersion
ecommerce_indicatoreci
authentication_valuecavv
directory_server_transaction_iddsTransactionId

Gateway Specific Fields

Common Fields

Field NameTypeRequiredDescriptionExample
installation_idStringNoWorldpay installation ID for the merchant. Maps to XML installationId.123456
order_contentStringNoOrder description sent in XML orderContent.Some order content
statement_narrativeStringNoText shown on the cardholder statement. Max 50 characters.MERCHANT STATEMENT NARRATIVE
idempotency_keyStringNoSent as HTTP Idempotency-Key header to prevent duplicate requests.11111
skip_captureBooleanNoAuthorize only; do not auto-capture on purchase.true
skip_default_addressBooleanNoDo not apply default billing address values when address is missing.true
zero_dollar_authBooleanNoRun a zero-amount auth for Visa/Mastercard verify flows.true
instalmentsStringNoNumber of installments for installment payments.3
cpfStringNoCustomer CPF for Brazil transactions.1a2b3c4d
hcg_additional_dataObjectNoAdditional hosted card gateway data key/value pairs.{"key1": "value1"}
custom_string_fieldsObjectNoFraudSight custom string fields.{"custom_string_field_1": "testing"}
level_2_dataObjectNoLevel 2 commercial card data.See Worldpay XML Direct guide
level_3_dataObjectNoLevel 3 line-item commercial card data.See Worldpay XML Direct guide
fast_fund_creditBooleanNoEnables fast fund / push credit (general credit) flow.true

3DS Fields

Field NameTypeRequiredDescriptionExample
session_idStringNoShopper session ID for 3DS2 / general credit. Auto-generated if omitted on 3DS requests.0215ui8ib1
user_agentStringNoBrowser user agent for 3DS2.Mozilla/5.0...
accept_headerStringNoBrowser accept header for 3DS2.text/html,application/xhtml+xml
exemption_typeStringNo3DS exemption type. Common value: LV (low value).LV
exemption_placementStringNoWhere exemption is applied. Defaults to AUTHORISATION.authentication
risk_dataObjectNo3DS / fraud risk data (authentication_risk_data, shopper_account_risk_data, transaction_risk_data).See Worldpay 3DS docs

Store credential fields

Field NameTypeRequiredDescriptionExample
stored_credential_usageStringNoCredential usage. FIRST or USED.USED
stored_credential_initiated_reasonStringNoReason code. RECURRING, INSTALMENT, or UNSCHEDULED.UNSCHEDULED
stored_credential_transaction_idStringNoOriginal scheme transaction ID for subsequent MIT transactions.39270fd70be13aab55f84e28be45cad3

Refund/Void fields

Field NameTypeRequiredDescriptionExample
bypass_authorization_status_checkBooleanNoSkip authorization status inquiry before refund/capture.true
cancel_or_refundBooleanNoUse Worldpay cancelOrRefund instead of standard refund.true
refund_referenceStringNoMerchant reference sent with refund.12345abcde

Store fields

Field NameTypeRequiredDescriptionExample
customer_idStringNoauthenticatedShopperID when storing a payment method at Worldpay.shopper_123

Sub-merchant data (payfac)

Field NameTypeRequiredDescriptionExample
pf_idStringNoPayment facilitator ID.12345678901
sub_nameStringNoSub-merchant name.Example Shop
sub_idStringNoSub-merchant ID.1234567
sub_streetStringNoSub-merchant street address.123 Street
sub_cityStringNoSub-merchant city.San Francisco
sub_stateStringNoSub-merchant state/province.CA
sub_country_codeStringNoSub-merchant ISO numeric country code.840
sub_postal_codeStringNoSub-merchant postal code.94101
sub_tax_idStringNoSub-merchant tax ID.987-65-4321

ACH/Bank Account Transactions

Spreedly supports processing of ACH/Bank Account transactions through the Worldpay gateway. This allows users to securely vault bank accounts and execute purchases or validations directly against Worldpay's US Domestic Acquiring platform.

To enable ACH processing on your Worldpay gateway deployment within Spreedly, you must provide your specialized banking credentials during gateway provisioning:

Merchant ID (MID): Your primary Worldpay production account identifier
Secure Net ID: Your secure banking integration identifier required for high-risk validation mapping

Account Funding Transaction (AFT)

Account Funding Transaction is the transferring of funds from a card account to a different destination that is not the standard purchase of goods or services. These transactions can be used for things like

  • Loading funds to a mobile wallet
  • Moving funds into another financial account
  • Topping up a pre-paid card
  • Funding money remittance

In order to perform an AFT on Worldpay you must specify that a General Credit transaction be performed using AFT by passing true in the account_funding_transaction gateway specific field. General Credit transactions that omit the account_funding_transaction field will perform a standard General Credit. These are all the other gateway specific fields available for AFT.

Field NameTypeRequiredDescriptionExample
account_funding_transactionBooleanYes (for AFT)Enables account funding transaction flow.true
aft_typeStringYes (for AFT)AFT type sent to Worldpay.A
aft_payment_purposeStringNoPayment purpose code.00
aft_sender_account_typeStringYes (for AFT)Sender account type.03
aft_sender_account_referenceStringYes (for AFT)Sender account reference.GB29NWBK60161331926819
aft_sender_full_nameObjectYes (for AFT)Sender name (first, middle, last).{"first": "John", "last": "Doe"}
aft_sender_funding_addressObjectNoSender address fields.{"address1": "1 Main St", "city": "London", "country_code": "GB"}
aft_recipient_account_typeStringYes (for AFT)Recipient account type.03
aft_recipient_account_referenceStringYes (for AFT)Recipient account reference.GB29NWBK60161331926819
aft_recipient_full_nameObjectYes (for AFT)Recipient name.{"first": "Jane", "last": "Doe"}
aft_recipient_funding_addressObjectNoRecipient address fields.{"address1": "2 High St", "city": "London", "country_code": "GB"}
aft_recipient_funding_dataObjectNoExtra recipient data (birth_date, telephone_number).{"telephone_number": "+441234567890"}

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 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>LgpTNGjsWQs9DwdxcbreUVzxyzp</token>
  <transaction_type>Authorization</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>
       <authorised_amount>123</authorised_amount>
       <avs_result_code_description>UNKNOWN</avs_result_code_description>
       <funding_link_id>000000000000012345678912345671230</funding_link_id>
     </worldpay>
  </gateway_specific_response_fields>
</transaction>

Partial authorization

In order to enable partial authorization, you must set the gateway specific field partial_authorisation to true on an Authorize transaction.

If a partial amount is authorized, the transaction response from Spreedly will reflect the following:

  • The state will be "succeeded"
  • The response.messagewill be "PARTIAL APPROVAL". This value will also be returned in the gateway specific response field iso8583_return_code_description.
  • The response.error_code will be "10". This value will also be returned in the gateway specific response field iso8583_return_code_code.
  • The partial amount (in cents) will be returned as the gateway specific response field authorised_amount

When enabling partial authorization, you must keep track of the authorised_amount by the gateway and specify this value as the amount in your follow-up Capture request to Spreedly, should you choose to capture the partial amount.

Worldpay recommends choosing one of the following options when determining how to proceed in the event of a partial authorization:

Submit a new order to authorise the remaining amount with a new card. This is treated as a separate order and must be captured separately

Cancel the order and ask the shopper to submit the payment with an alternative card

Cancel the order and take no further action. The funds in the shopper's account are released when the authorisation expires

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.

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>WucDSXyY6oD4NBWzTdSS6oYxyzn</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>T11bJAANtTWnxl36GYjKWvxyz0g</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>Tp99vI4yQ959K4ezNklLtEixyxF</reference_token>
</transaction>

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.

Stored Credentials

WorldPay supports Spreedly’s native stored credential fields on Purchase and Authorize requests:

stored_credential_initiator

stored_credential_reason_type

Spreedly maps these to WorldPay’s <StoredCredentials> element as usage (FIRST / USED) plus customerInitiatedReason or merchantInitiatedReason (RECURRING, INSTALMENT, UNSCHEDULED).

📘

Learn more about how spreedly enables use of stored credentials by reviewing our Stored credentials Guide

First / credential-on-file setup (CIT)

reason_typeinitiatorWorldpay usage
installmentcardholderFIRST
recurringcardholderFIRST
unscheduledcardholderFIRST

Subsequent use

reason_typeinitiatorWorldpay usage
installmentmerchantUSED
installmentcardholderUSED
recurringmerchantUSED
recurringcardholderUSED
unscheduledmerchantUSED
unscheduledcardholderUSED

Additional resources

📘

If you need support with this gateway, please contact Support at [email protected].



Did this page help you?