Worldpay REST Gateway Guide

Worldpay REST fact sheet

Quick Start

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

1. Retrieve your Worldpay Rest credentials:
   1. Contact the Worldpay support team to obtain your Worldpay Access credentials: username, password, and entity.
   2. For gateway-specific 3DS2 on Worldpay REST, no additional credentials are required beyond the above — authentication requests use the same username/password/entity as payment requests.
2. Get familiar with the Spreedly API:
   1. Review Spreedly API basics.
   2. Review Gateways, Payment Methods, and Transactions.
3. Add an Worldpay Rest gateway to Spreedly in sandbox mode.

Adding a Worldpay Gateway

Required Credentials

• username: Your Worldpay Access username.
• password: Your Worldpay Access password.
• entity: Your Worldpay Access entity identifier.

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>worldpay_rest</gateway_type>
        <username>Your Worldpay Access Username</username>
        <password>Your Worldpay Access Password</password>
        <entity>Your Worldpay Access Entity</entity>
      </gateway>'

Response

<gateway>
  <token>IFEnzFllMG2bcTo7fWmVe6xHxyz</token>
  <gateway_type>worldpay_rest</gateway_type>
  <name>Worldpay REST</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <username>Your Worldpay Access Username</username>
  <entity>Your Worldpay Access Entity</entity>
  <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">false</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_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">true</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</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>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_partial_refund type="boolean">true</supports_partial_refund>
  </characteristics>
  <credentials>
    <credential>
      <name>username</name>
      <value>Your Worldpay Access Username</value>
    </credential>
    <credential>
      <name>entity</name>
      <value>Your Worldpay Access Entity</value>
    </credential>
  </credentials>
  <gateway_settings>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>channel</gateway_specific_field>
    <gateway_specific_field>reference</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
    <gateway_specific_field>namespace</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>level_2_data</gateway_specific_field>
    <gateway_specific_field>level_3_data</gateway_specific_field>
    <gateway_specific_field>instalments</gateway_specific_field>
    <gateway_specific_field>installment_type</gateway_specific_field>
    <gateway_specific_field>statement_narrative</gateway_specific_field>
    <gateway_specific_field>statement_narrative_line2</gateway_specific_field>
    <gateway_specific_field>accept_partial_amount</gateway_specific_field>
    <gateway_specific_field>partial_authorisation</gateway_specific_field>
    <gateway_specific_field>pf_id</gateway_specific_field>
    <gateway_specific_field>iso_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>sub_email</gateway_specific_field>
    <gateway_specific_field>sub_telephone</gateway_specific_field>
    <gateway_specific_field>exemption_type</gateway_specific_field>
    <gateway_specific_field>exemption_placement</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>third_party_apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>third_party_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.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>1000</amount>
        <currency_code>GBP</currency_code>
      </transaction>'

Stored Credentials

Worldpay REST supports Spreedly's native stored credential fields on Purchase and Authorize requests:

• stored_credential_initiator
• stored_credential_reason_type
  Spreedly maps these to Worldpay Access's customerAgreement element. Customer-initiated transactions (initiator: cardholder) are sent to Worldpay's customerInitiatedTransactions endpoint; merchant-initiated transactions (initiator: merchant) are sent to Worldpay's merchantInitiatedTransactions endpoint.

First / credential-on-file setup (CIT)

Subsequent use — customer-initiated (CIT)

Only cardOnFile can be combined with a subsequent stored-card transaction on the customer-initiated endpoint, regardless of the original reason_type.

Subsequent use — merchant-initiated (MIT)

Merchant-initiated requests omit storedCardUsage and the card CVC, and include customerAgreement.schemeReference (the original network/scheme transaction ID) when one is available.

Gateway Specific Fields

Common Fields

3DS Fields

Browser/device data used during gateway-specific 3DS2 (accept header, user agent, browser language, Java/JavaScript support, color depth, screen size, time zone, IP address, challenge window size) is supplied through Spreedly's standard 3DS2 browser_info options rather than a Worldpay REST gateway specific field — see 3DS2 gateway-specific below.

Store credential fields

Refund/Void fields

Worldpay REST does not expose separate refund- or void-only gateway specific fields. idempotency_key (documented under Common Fields above) applies to void and refund requests the same as any other request; reference applies only when capturing or refunding a partial amount.

Store fields

The stored token's description is taken from the transaction's description attribute (or the statement narrative fields, if set) when supplied.

Sub-merchant data

Level 2 / Level 3 data

The level_2_data and level_3_data gateway specific fields are merged together and mapped onto the Worldpay Access order object.

Each entry in items supports:

Network Tokenization

Worldpay REST accepts network-tokenized cards (payment methods provided to Spreedly as a network token) in addition to plain cards. The paymentInstrument.type sent to Worldpay depends on the token's source:

For a network token, tokenNumber carries the token PAN and expiryDate the token's expiration; cardHolderName is included when present. No cvc is sent for network tokens.
When the payment method carries a payment cryptogram and/or ECI value, Spreedly sends them as authentication.networkToken.{cryptogram, eci} on customer-initiated requests. This, like the rest of the authentication object, is omitted on merchant-initiated (MIT) requests.

3DS2 gateway-specific

Spreedly supports gateway specific 3DS2 via Worldpay REST (Worldpay Access). Authentication requests are made using the same username/password/entity credentials as payment requests — no separate HMAC secret, Issuer ID, or Org Unit ID is required.

3DS2 exemptions

When conducting 3DS2 transactions you may use the gateway specific fields exemption_type and exemption_placement (documented under 3DS Fields above). See Worldpay's SCA exemptions documentation for detailed descriptions of each exemption type.

Third-party 3DS2 auth data

Spreedly will automatically handle the field mapping for sending third-party 3DS2 authentication data to Worldpay REST. For more information about how to use this feature, see the 3DS2 third-party authentication guide. Spreedly fields map to the relevant Worldpay Access fields as follows:

General credit operation setup

Worldpay REST general credit (payout) transactions are sent to Worldpay Access's disbursement endpoint using a plain card payout instrument.

Store operation setup

Worldpay REST stores payment methods through Worldpay Access's tokens endpoint and returns a token that can be reused as the payment method on later Purchase/Authorize/Verify requests. Optionally scope the token to a namespace using the namespace gateway specific field (documented under Store fields above). If Worldpay returns an existing token for the same card, Spreedly still treats the store as successful and returns the existing token. Removing a stored payment method calls Worldpay's token deletion endpoint.

Gateway specific response fields

A response from the Worldpay REST gateway may contain some of the following fields, returned under gateway_specific_response_fields:

<transaction>
  <token>LgpTNGjsWQs9DwdxcbreUVz0xyz</token>
  <transaction_type>Authorization</transaction_type>
  <gateway_specific_response_fields>
     <worldpay_rest>
       <outcome>authorized</outcome>
       <payment_id>a1b2c3d4-e5f6-7890-aaaa-bbbbccccdddd</payment_id>
       <transaction_reference>spreedly-abc123</transaction_reference>
       <scheme>
         <reference>123456789012345</reference>
       </scheme>
       <amounts>
         <totalAuthorized>1000</totalAuthorized>
       </amounts>
       <authorised_amount>1000</authorised_amount>
     </worldpay_rest>
  </gateway_specific_response_fields>
</transaction>

Partial authorization

In order to enable partial authorization, set the gateway specific field accept_partial_amount (or partial_authorisation) to true on an Authorize transaction. Partial authorization is only applied when the transaction does not auto-settle, so it does not apply to Purchase.
If a partial amount is authorized, the transaction still succeeds normally (state: "succeeded"). You can detect a partial approval from the gateway specific response fields:

• authorised_amount — the amount (in minor currency units) that was actually authorized, from Worldpay's amounts.totalAuthorized.
• partial_authorization — Worldpay's amounts.partialAuthorization detail.
  When enabling partial authorization, keep track of the authorized amount and specify that value as the amount on your follow-up Capture request to Spreedly, should you choose to capture the partial amount.

Syncing transactions

Spreedly supports updating the status of transactions that have been initiated at the Worldpay REST gateway. Spreedly queries Worldpay's Payment Queries API using the stored payment_id (Worldpay paymentId), falling back to the transaction's transactionReference (Spreedly order_id) when no payment ID was captured for the transaction. Because Payment Queries data is aggregated asynchronously by Worldpay, a "payment not found" result is treated as inconclusive rather than a definitive failure.

Additional resources