Worldpay gateway guide
Quick Start
New to integrating Worldpay with Spreedly? Here's your setup guide:
- Retrieve your Worldpay credentials
- Contact the Worldpay support team to obtain API credentials
- Get familiar with the Spreedly API
- Review Spreedly API basics
- Understand the core concepts: Gateways, Payment Methods, and Transactions
- 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 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 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”.
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 field | Worldpay field |
|---|---|
three_ds_version | threeDSVersion |
ecommerce_indicator | eci |
authentication_value | cavv |
directory_server_transaction_id | dsTransactionId |
Gateway Specific Fields
Common Fields
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
installation_id | String | No | Worldpay installation ID for the merchant. Maps to XML installationId. | 123456 |
order_content | String | No | Order description sent in XML orderContent. | Some order content |
statement_narrative | String | No | Text shown on the cardholder statement. Max 50 characters. | MERCHANT STATEMENT NARRATIVE |
idempotency_key | String | No | Sent as HTTP Idempotency-Key header to prevent duplicate requests. | 11111 |
skip_capture | Boolean | No | Authorize only; do not auto-capture on purchase. | true |
skip_default_address | Boolean | No | Do not apply default billing address values when address is missing. | true |
zero_dollar_auth | Boolean | No | Run a zero-amount auth for Visa/Mastercard verify flows. | true |
instalments | String | No | Number of installments for installment payments. | 3 |
cpf | String | No | Customer CPF for Brazil transactions. | 1a2b3c4d |
hcg_additional_data | Object | No | Additional hosted card gateway data key/value pairs. | {"key1": "value1"} |
custom_string_fields | Object | No | FraudSight custom string fields. | {"custom_string_field_1": "testing"} |
level_2_data | Object | No | Level 2 commercial card data. | See Worldpay XML Direct guide |
level_3_data | Object | No | Level 3 line-item commercial card data. | See Worldpay XML Direct guide |
fast_fund_credit | Boolean | No | Enables fast fund / push credit (general credit) flow. | true |
3DS Fields
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
session_id | String | No | Shopper session ID for 3DS2 / general credit. Auto-generated if omitted on 3DS requests. | 0215ui8ib1 |
user_agent | String | No | Browser user agent for 3DS2. | Mozilla/5.0... |
accept_header | String | No | Browser accept header for 3DS2. | text/html,application/xhtml+xml |
exemption_type | String | No | 3DS exemption type. Common value: LV (low value). | LV |
exemption_placement | String | No | Where exemption is applied. Defaults to AUTHORISATION. | authentication |
risk_data | Object | No | 3DS / fraud risk data (authentication_risk_data, shopper_account_risk_data, transaction_risk_data). | See Worldpay 3DS docs |
Store credential fields
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
stored_credential_usage | String | No | Credential usage. FIRST or USED. | USED |
stored_credential_initiated_reason | String | No | Reason code. RECURRING, INSTALMENT, or UNSCHEDULED. | UNSCHEDULED |
stored_credential_transaction_id | String | No | Original scheme transaction ID for subsequent MIT transactions. | 39270fd70be13aab55f84e28be45cad3 |
Refund/Void fields
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
bypass_authorization_status_check | Boolean | No | Skip authorization status inquiry before refund/capture. | true |
cancel_or_refund | Boolean | No | Use Worldpay cancelOrRefund instead of standard refund. | true |
refund_reference | String | No | Merchant reference sent with refund. | 12345abcde |
Store fields
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
customer_id | String | No | authenticatedShopperID when storing a payment method at Worldpay. | shopper_123 |
Sub-merchant data (payfac)
| Field Name | Type | Required | Description | Example |
|---|---|---|---|---|
pf_id | String | No | Payment facilitator ID. | 12345678901 |
sub_name | String | No | Sub-merchant name. | Example Shop |
sub_id | String | No | Sub-merchant ID. | 1234567 |
sub_street | String | No | Sub-merchant street address. | 123 Street |
sub_city | String | No | Sub-merchant city. | San Francisco |
sub_state | String | No | Sub-merchant state/province. | CA |
sub_country_code | String | No | Sub-merchant ISO numeric country code. | 840 |
sub_postal_code | String | No | Sub-merchant postal code. | 94101 |
sub_tax_id | String | No | Sub-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 identifierSecure 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 Name | Type | Required | Description | Example |
|---|---|---|---|---|
account_funding_transaction | Boolean | Yes (for AFT) | Enables account funding transaction flow. | true |
aft_type | String | Yes (for AFT) | AFT type sent to Worldpay. | A |
aft_payment_purpose | String | No | Payment purpose code. | 00 |
aft_sender_account_type | String | Yes (for AFT) | Sender account type. | 03 |
aft_sender_account_reference | String | Yes (for AFT) | Sender account reference. | GB29NWBK60161331926819 |
aft_sender_full_name | Object | Yes (for AFT) | Sender name (first, middle, last). | {"first": "John", "last": "Doe"} |
aft_sender_funding_address | Object | No | Sender address fields. | {"address1": "1 Main St", "city": "London", "country_code": "GB"} |
aft_recipient_account_type | String | Yes (for AFT) | Recipient account type. | 03 |
aft_recipient_account_reference | String | Yes (for AFT) | Recipient account reference. | GB29NWBK60161331926819 |
aft_recipient_full_name | Object | Yes (for AFT) | Recipient name. | {"first": "Jane", "last": "Doe"} |
aft_recipient_funding_address | Object | No | Recipient address fields. | {"address1": "2 High St", "city": "London", "country_code": "GB"} |
aft_recipient_funding_data | Object | No | Extra 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
statewill be"succeeded" - The
response.messagewill be"PARTIAL APPROVAL". This value will also be returned in the gateway specific response fieldiso8583_return_code_description. - The
response.error_codewill be"10". This value will also be returned in the gateway specific response fieldiso8583_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_type | initiator | Worldpay usage |
|---|---|---|
installment | cardholder | FIRST |
recurring | cardholder | FIRST |
unscheduled | cardholder | FIRST |
Subsequent use
reason_type | initiator | Worldpay usage |
|---|---|---|
installment | merchant | USED |
installment | cardholder | USED |
recurring | merchant | USED |
recurring | cardholder | USED |
unscheduled | merchant | USED |
unscheduled | cardholder | USED |
Additional resources
If you need support with this gateway, please contact Support at [email protected].
Worldpay Documentation: Reference, https://dtd.worldpay.com/v1/paymentService_v1.dtd.html
API Endpoint:https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp (Production)
Test Endpoint: https://securetest.worldpay.com/jsp/merchant/xml/paymentService.jsp (Sandbox)
Updated 24 days ago

