WorldPay Gateway Guide

Additional notes

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.

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

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>

To learn more about creating and managing gateways in our Marketplace, review the Gateway user guide. For gateways not included in the Marketplace, review the steps below.

Create a gateway

Visit your Connections area to review all gateways and add new ones. When creating your gateways, select the gateway name and authentication mode (if prompted) before completing required fields. Select ☑️Sandbox to create a gateway in Sandbox mode, for processing test card data and transactions in your Spreedly environment.

Supply your issuer_id, and hmac_secret into their respective fields. Enter your Merchant code (merchant ID) into the login field, your XML password to the password field, and your Organization unit ID to the org_unit_id field to create a new Worldpay gateway.

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.

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`

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.

Account Funding Transaction

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.

Spreedly Gateway Specific Field
`aft_type`	Is a mandatory field that takes in a single letter from a list of accepted values (A, C, D, F, P, R, S, T, O, Q, G, W, U).
`aft_payment_purpose`	Is an optional field that can only take a value containing two alphanumeric characters, no spaces allowed. Example: 00, 01, 02, M1, M2, ...
`aft_sender_account_type` `aft_recipient_account_type`	The respective field must be present whenever aft_sender_account_reference or aft_recipient_account_reference are passed. It has a fixed length of two characters, numeric values. Example: 02, 04…
`aft_sender_account_reference` `aft_recipient_account_reference`	aft_sender_account_reference is optional but aft_recipient_account_reference is mandatory
`aft_sender_full_name` `aft_recipient_full_name`	This is a mandatory object which can contain first, middle and last.
`aft_send_funding_address` `aft_recipient_funding_address`	This is a mandatory object which can contain address1, address2, postal_code, city, state and country_code.
`aft_recipient_funding_data`	Is an optional object which can contain telephone_number and birth_date. The telephone_number can have a minimum length three / maximum length 30. Allowed characters: "0123456789 ()+-/.x The birth_data is an object that can contain day_of_month, month and year.

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 single l)
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 Spreedly 3DS Solutions 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 facilitator - Mandatory
sub_name - Sub-merchant name, supplied by payment facilitator - 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>[email protected]</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>'

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>[email protected]</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>

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

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.