WorldPay

Supports in this guide: Payments, Payouts

Provider website: worldpay.com

What you need to do for start processing transactions (brief summary)

1. Choose account type
2. Get your credentials (from WorldPay)
3. Connect in Dashboard
4. Send an API request

Choose account type

WorldPay can be connected in different ways (depending on your needs):

• If you do payouts (card disbursements) -> choose Provider account
• If you do payments (card data sent directly, H2H) -> choose H2H Merchant account

If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from WorldPay

To get connected, submit a request at worldpay.com/global/solutions-contact or contact your WorldPay manager directly, and complete the account verification/underwriting they require.

Get the following values for your WorldPay project/account. The same core credentials apply to both connection types below, but are entered separately when connecting each account type in the Dashboard.

• Username -> Corefy field username -> HTTP Basic Auth user for every WorldPay XML API request -> where to find: WorldPay merchant back-office / issued by WorldPay.
• Merchant code -> Corefy field merchant_code -> identifies your WorldPay merchant in the paymentService XML envelope -> where to find: WorldPay merchant back-office.
• Xml password -> Corefy field xml_password -> HTTP Basic Auth password, paired with Username -> where to find: WorldPay merchant back-office.
• Api ID (H2H Merchant account only) -> Corefy field api_id -> the iss claim used when signing the JWT for WorldPay's 3-D Secure device-fingerprinting step (Cardinal Cruise) -> where to find: WorldPay/Cardinal onboarding.
• Api key (H2H Merchant account only) -> Corefy field api_key -> secret used to sign that same JWT -> where to find: WorldPay/Cardinal onboarding.
• Id organization (H2H Merchant account only) -> Corefy field org_unit_id -> the OrgUnitId sent to Cardinal during the 3-D Secure device-fingerprinting step -> where to find: WorldPay/Cardinal onboarding.

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 26.9,
      "gateway_options": {
        "cardgate": {
          "tokenize": ""
        }
      },
      "customer": {
        "reference_id": "cus_123"
      }
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 32,
      "gateway_options": {
        "cardgate": {
          "tokenize": ""
        }
      },
      "customer": {
        "reference_id": "cus_123",
        "name": "John Wick",
        "email": "test@test.com",
        "phone": "445556667788",
        "date_of_birth": "2000-02-01",
        "address": {
          "full_address": "Address",
          "country": "AW",
          "region": "Region",
          "city": "City",
          "street": "Street",
          "post_code": "Postcode"
        }
      }
    }
  }
}

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "service": "payment_card_gbp",
      "currency": "GBP",
      "amount": 53.87,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Wick"
      },
      "fields": {
        "card_number": "4444333322221111"
      }
    }
  }
}

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "service": "payment_card_gbp",
      "currency": "GBP",
      "amount": 53.87,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Wick",
        "address": {
          "country": "GB",
          "city": "London",
          "street": "10 Downing Street"
        }
      },
      "fields": {
        "card_number": "4444333322221111"
      }
    }
  }
}

Additional info

H2H Merchant account:

1. Common vs Raft backend. These are two entirely different WorldPay APIs (XML "Payment Service" vs. JSON Vantiv/Litle) selected by one toggle on the account, not per request - see the callout above. If you need USD, your account must be connected with RAFT API enabled and the Raft-specific fields filled in; the Common-API fields still exist on the form but aren't used in that mode.

2. 3-D Secure (Common backend). Card sales that require 3-D Secure go through WorldPay's Cardinal Cruise device-fingerprinting flow (collect -> render -> method notification -> redirect -> challenge) before the sale completes; this is handled by Corefy automatically using the Api ID/Api key/Id organization credentials - no separate action is needed on your side beyond supplying them.

3. Digital wallets. Apple Pay and Google Pay are enabled per-connection: pick the corresponding Method when connecting the H2H Merchant account, and fill in the wallet-specific fields the form then shows (Apple Merchant ID, Apple Display Name, Apple Certificate + password for Apple Pay; GooglePay gateway merchant ID + GooglePay gateway for Google Pay). Contact your Corefy account manager to enable a wallet method for your account.

4. Recurring/stored-credential payments. Enable Save Instant Token to have Corefy request a reusable token on the first sale, and set COF Type (cardholder-initiated vs merchant-initiated) to control how subsequent token-based charges are flagged to WorldPay.

5. Callback routing. Callback routing is handled automatically: WorldPay calls back a notification URL Corefy generates per transaction. There's no fixed callback URL to configure in WorldPay's back-office. WorldPay callbacks don't carry a signature - if a callback doesn't report the final AUTHORISED/settled state, Corefy reconciles the payment directly with WorldPay instead of trusting the callback body.

FAQ / Troubleshooting

• Invalid credentials / auth error -> verify Username/Merchant code/Xml password (and, for H2H, Api ID/Api key/Id organization or the Raft fields) match the selected environment (sandbox vs production) and account type
• USD payments are rejected -> USD is only available on the H2H Merchant account with RAFT API enabled and the Raft-specific fields filled in - it isn't available on the Common backend or for payouts
• 3-D Secure step isn't completing -> confirm Api ID/Api key/Id organization are correct; these drive the Cardinal Cruise device-fingerprinting step
• Not sure which account type to use? -> ask your Corefy account manager