Skip to main content

Worldpay WPG

Overview​

Gateway Website: https://dashboard.worldpay.com/
Developer Documentation: https://developerengine.fisglobal.com/apis/wpg/directintegration
Default Currency: USD

Request Objects: BillingAddress, CreditCard, Check, OrderInfo, ThreeDSecure

Gateway Endpoints
This implementation of Worldpay WPG forwards requests to the below endpoints.
Production: https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp
Sandbox: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp

Supported Request Parameters​

* denotes a required field
Field NameTypeWorldpay WPG MappingNotes
gateway*stringN/AWorldpayWPG
username*stringmerchantCode
Basic Auth username		Merchant's Worldpay WPG
Username
password*stringBase Auth passwordMerchant's Worldpay WPG
Password
orderId*stringorder.orderCode
orderModification.​orderCode		Must have a unique value per order- i.e. the order code must not have been used previously.
Can be up to 64 characters in length, or 25 characters if you are connecting to the US domestic acquiring platform. Recommend a minimum of 9 and a maximum of 20 for onward processing. Spaces, quotation marks, code brackets (< and >) and pipes ("|") are not allowed.
merchantId*stringpaymentService.​merchantCodeSame value as username.
amountintorder.amount.value
modify.capture.value
modify.​refund.​value		Transaction amount in whole units. Example: $10.00 USD should be sent as 1000.
currencyCodestringorder.amount.currencyCode
modify.capture.currencyCode
modify.​refund.​currencyCode		ISO 4217 three-letter alphabetic code for the currency.
Defaults to "USD".
creditCard.​numberstringpaymentDetails.​CARD-SSL.​cardNumberCard's PAN or TokenEx token
creditCard.​FullNamestringpaymentDetails.​CARD-SSL.​cardHolderNameCardholder's full name.
creditCard.​expYearintpaymentDetails.​CARD-SSL.​expiryDate.​date.​year4 digit year.
creditCard.​expMonthintpaymentDetails.​CARD-SSL.​expiryDate.​date.​month1 or 2 digit month.
creditCard.​CVVstringpaymentDetails.​CARD-SSL.​cvc3 or 4 digit Card Verification Code. If the CVV has been associated with a TokenEx token, send a non-numeric value here, such as "cvv". The CVV associated with the token will be retrieved and forwarded.
billingAddress.​address1stringpaymentDetails.​CARD-SSL.​cardAddress.​address.​address1First line of the street address.
billingAddress.​address2stringpaymentDetails.​CARD-SSL.​cardAddress.​address.​address2Second line of the street address.
billingAddress.​citystringpaymentDetails.​CARD-SSL.​cardAddress.​address.​cityCity or locality.
billingAddress.​statestringpaymentDetails.​CARD-SSL.​cardAddress.​address.​stateState or province.
billingAddress.​zipstringpaymentDetails.​CARD-SSL.​cardAddress.​address.​zipZIP code or postal code.
billingAddress.​countrystringpaymentDetails.​CARD-SSL.​cardAddress.​address.​countryCustomer country. Input Alpha 3. Is converted to Alpha 2.
orderInfo.​InvoiceNumberstringpurchase.​invoiceReferenceNumberInvoice number associated with a transaction.
orderInfo.​CustomerIdstringpurchase.​customerReferenceCustomer reference for the purchase
orderInfo.​DiscountAmountintpurchase.​discountAmount.​amount.​valueThe amount of discount for the order.
orderInfo.​ShippingAmountintpurchase.​shippingAmount.​amount.​valueThe shipping cost for the order.
orderInfo.​DutyAmountintpurchase.​dutyAmount.​amount.​valueThe duty on the total purchase amount for the order.
tax.​CardAcceptorTaxIdstringpurchase.​cardAcceptorTaxId9 digits for US domiciled merchants.
tax.​Amountintpurchase.​salesTax.​Amount.​ValueAmount of sales tax for the order.
tax.​Exemptbooleanpurchase.​taxExemptSet to true if salesTax is 0.
threeDSecure.​CAVVstringinfo3DSecure.​cavvCardholder authentication verification value returned by the 3DS authentication.
threeDSecure.​DSTransIdstringinfo3DSecure.​dsTransactionIdUnique transaction identifier assigned by the Directory Server (DS) to identify a single 3DS transaction.
threeDSecure.​ECIstringinfo3DSecure.​eciElectronic Commerce Indicator as returned by the 3DS authentication.
threeDSecure.​ThreeDSecureVersionstringinfo3DSecure.​threeDSVersionThe message version used for the 3DS authentication. Valid values: "2.1.0" or "2.2.0"

Example Requests​

{
  "testMode": true,
  "gateway": "WorldpayWPG",
  "username":"<Your Worldpay WPG API Login ID>",
  "password":"<Your Worldpay WPG Transaction Key>",
  "merchantId": "<Your Worldpay WPG API Login ID>",
  "amount": 900,
  "creditCard": {
    "number": "4111111111111111",
    "expMonth": 6,
    "expYear": 2024,
    "firstName": "John",
    "lastName": "Doe",
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "email": "[email protected]",
    "name": "John Doe",
    "company": "Test Co.",
    "address1": "123 Someplace Lane, Suite #40A",
    "city": "Edmond",
    "state": "OK",
    "zip": "74100",
    "country": "USA"
  },
  "orderInfo": {
    "invoiceNumber": "INV12233566",
    "customerId": "CUST00000001",
    "discountAmount": 0,
    "shippingAmount": 100,
    "dutyAmount": 0
  },
  "tax": {
    "cardAcceptorTaxId": "VAT1999292",
    "amount": 2400,
    "exempt": false
}

Gateway Response Parameters​

Field NameTypeWPG Response MappingNotes
ApprovedbooleanlastEventIf primary request returns "AUTHORISED" or OK element is present.
ProviderTransactionCodestringRequest's order.OrderCodeThe order code from the request is echoed in the response from WPG and is the value used for transaction modification.

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE paymentService PUBLIC \"-//WorldPay//DTD WorldPay PaymentService v1//EN\"\n                                \"http://dtd.worldpay.com/paymentService_v1.dtd\">\n<paymentService version=\"1.4\" merchantCode=\"<MerchantId>\"><reply><orderStatus orderCode=\"1c8ba10a-beb2-4488-b2d9-7a5411938293\"><payment><paymentMethod>VISA-SSL</paymentMethod><amount value=\"500\" currencyCode=\"USD\" exponent=\"2\" debitCreditIndicator=\"credit\"/><lastEvent>AUTHORISED</lastEvent><CVCResultCode description=\"NOT SENT TO ACQUIRER\"/><AVSResultCode description=\"NOT SENT TO ACQUIRER\"/><AAVAddressResultCode description=\"UNKNOWN\"/><AAVPostcodeResultCode description=\"UNKNOWN\"/><AAVCardholderNameResultCode description=\"UNKNOWN\"/><AAVTelephoneResultCode description=\"UNKNOWN\"/><AAVEmailResultCode description=\"UNKNOWN\"/><cardHolderName><![CDATA[Frank Walter]]></cardHolderName><issuerCountryCode>GB</issuerCountryCode><balance accountType=\"IN_PROCESS_AUTHORISED\"><amount value=\"500\" currencyCode=\"USD\" exponent=\"2\" debitCreditIndicator=\"credit\"/></balance><cardNumber>4444********1111</cardNumber><riskScore value=\"71\"/></payment></orderStatus></reply></paymentService>\n",
    "gatewayErrors": [],
    "tokenExTransactionCode": "MWM4YmExMGEtYmViMi00NDg4LWIyZDktN2E1NDExOTM4Mjkz",
    "approvalCode": "",
    "providerTransactionCode": "1c8ba10a-beb2-4488-b2d9-7a5411938293",
    "approved": true
  },
  "referenceNumber": "23120717270023140526",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on