WorldPay Gateway Guide
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, Apple Pay, Google Pay
- Spreedly 3DS2 Global Supported
- Yes
- Gateway Specific 3DS2 Supported
- Yes
- Populate MIT GSF Support
- No
- 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:
- Issuer Id, Login, Org Unit Id, Hmac Secret, Password
- Additional steps needed to activate?
- Turn off the capture delay setting. (See notes)
Onboarding Merchants in:
-
Andorra
-
United Arab Emirates
-
Antigua and Barbuda
-
Anguilla
-
Albania
-
Armenia
-
Angola
-
Argentina
-
American Samoa
-
Austria
-
Australia
-
Aruba
-
Åland Islands
-
Azerbaijan
-
Bosnia and Herzegovina
-
Barbados
-
Bangladesh
-
Belgium
-
Burkina Faso
-
Bulgaria
-
Bahrain
-
Burundi
-
Benin
-
Bermuda
-
Brunei Darussalam
-
Bolivia (Plurinational State of)
-
Brazil
-
Bahamas
-
Bhutan
-
Botswana
-
Belarus
-
Belize
-
Canada
-
Cocos (Keeling) Islands
-
Central African Republic
-
Switzerland
-
Cook Islands
-
Chile
-
Cameroon
-
China
-
Colombia
-
Costa Rica
-
Cabo Verde
-
Christmas Island
-
Cyprus
-
Czechia
-
Germany
-
Djibouti
-
Denmark
-
Dominican Republic
-
Algeria
-
Ecuador
-
Estonia
-
Egypt
-
Western Sahara
-
Spain
-
Ethiopia
-
Finland
-
Fiji
-
Falkland Islands (Malvinas)
-
Micronesia (Federated States of)
-
Faroe Islands
-
France
-
Gabon
-
United Kingdom
-
Grenada
-
Georgia
-
French Guiana
-
Guernsey
-
Ghana
-
Gibraltar
-
Greenland
-
Gambia
-
Guinea
-
Guadeloupe
-
Equatorial Guinea
-
Greece
-
Guatemala
-
Guam
-
Guinea-Bissau
-
Guyana
-
Hong Kong
-
Heard Island and McDonald Islands
-
Honduras
-
Croatia
-
Haiti
-
Hungary
-
Indonesia
-
Ireland
-
Israel
-
Isle of Man
-
India
-
British Indian Ocean Territory
-
Iceland
-
Italy
-
Jersey
-
Jamaica
-
Jordan
-
Japan
-
Kenya
-
Kyrgyzstan
-
Cambodia
-
Kiribati
-
Comoros
-
Saint Kitts and Nevis
-
Korea (Republic of)
-
Kuwait
-
Cayman Islands
-
Kazakhstan
-
Lao People’s Democratic Republic
-
Saint Lucia
-
Liechtenstein
-
Sri Lanka
-
Lesotho
-
Lithuania
-
Luxembourg
-
Latvia
-
Morocco
-
Monaco
-
Moldova (Republic of)
-
Montenegro
-
Madagascar
-
Marshall Islands
-
Macedonia (the former Yugoslav Republic of)
-
Mali
-
Mongolia
-
Macao
-
Northern Mariana Islands
-
Martinique
-
Mauritania
-
Montserrat
-
Malta
-
Mauritius
-
Maldives
-
Malawi
-
Mexico
-
Malaysia
-
Mozambique
-
Namibia
-
New Caledonia
-
Niger
-
Norfolk Island
-
Nigeria
-
Nicaragua
-
Netherlands
-
Norway
-
Nepal
-
Nauru
-
Niue
-
New Zealand
-
Oman
-
Panama
-
Peru
-
French Polynesia
-
Philippines
-
Pakistan
-
Poland
-
Pitcairn
-
Puerto Rico
-
Portugal
-
Palau
-
Paraguay
-
Qatar
-
Réunion
-
Romania
-
Serbia
-
Russian Federation
-
Rwanda
-
Saudi Arabia
-
Solomon Islands
-
Seychelles
-
Sweden
-
Singapore
-
Slovenia
-
Slovakia
-
Sierra Leone
-
San Marino
-
Senegal
-
Sao Tome and Principe
-
El Salvador
-
Swaziland
-
Turks and Caicos Islands
-
Chad
-
French Southern Territories
-
Togo
-
Thailand
-
Tajikistan
-
Tokelau
-
Turkmenistan
-
Tonga
-
Turkey
-
Trinidad and Tobago
-
Tuvalu
-
Taiwan
-
Tanzania, United Republic of
-
Ukraine
-
Uganda
-
United States
-
Uruguay
-
Uzbekistan
-
Holy See
-
Saint Vincent and the Grenadines
-
Venezuela (Bolivarian Republic of)
-
Virgin Islands (U.S.)
-
Vietnam
-
Vanuatu
-
Wallis and Futuna
-
Samoa
-
Yemen
-
Mayotte
-
South Africa
-
Zambia
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.
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">false</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.
Spreedly Field | Worldpay Field |
---|---|
three_ds_version |
threeDSVersion |
ecommerce_indicator |
eci |
authentication_value |
cavv |
directory_server_transaction_id |
dsTransactionId |
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 singlel
)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.