Skip to main content

Worldpay eComm cnpAPI

Overview​

Gateway Website: https://dashboard.worldpay.com/
Developer Documentation: http://support.worldpay.com/support/CNP-API/content/introduction.htm
Sandbox documentation: https://vantiv.github.io/sandbox

Default Currency: Currency determined by Worldpay merchant configuration

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

Gateway Endpoints
This implementation of the eComm cnpAPI forwards requests to the below endpoints.
Production:https://payments.vantivcnp.com/vap/communicator/online
Prelive: https://payments.vantivprelive.com/vap/communicator/online
Sandbox: https://www.testvantivcnp.com/sandbox/communicator/online

Supported Request Parameters​

Field NameTypecnpAPI MappingNotes
GatewaystringN/AVantivCNP
UsernamestringAuthentication.​UserThe sandbox does not require registration. Populate with dummy values outside Prelive and Production.
PasswordstringAuthentication.​PasswordThe sandbox does not require registration. Populate with dummy values outside Prelive and Production.
MerchantIdstringMerchantIdThe sandbox does not require registration. Populate with dummy values outside Prelive and Production.
VantivAPIVersionstringVersionDefaults to 9.4. Versions below 9.4 may be functional but are not supported via this implementation.
TransactionIdstringIdFall through assignment order: TransactionId, OrderInfo.OrderId, Random 25 digit string.
ReportGroupstringReportGroupFall through assignment order: ReportGroup, MerchantId, "Default Report Group"
OrderInfo.​CustomerIdstringCustomerIdA value assigned by the merchant to identify the consumer.
OrderInfo.​OrderIdstringOrderIdIf null, then the value assigned to Id is populated here.
OrderInfo.​OrderSourcestringOrderSourceFall through assignment order: OrderInfo.OrderSource, "ecommerce".
AmountnumericAmountThe amount in minor units. For example, 2000 means USD 20.00. Max length: 12 characters.
BillingAddress.​FullNamestringBillToAddress.​NameIf full name is null, then the values of BillingAddress.FirstName and BillingAddress.LastName will be space-separated and concatenated.
BillingAddress.​CompanystringBillToAddress.​CompanyNameCompany Name
BillingAddress.​EmailstringBillToAddress.​EmailCustomer Email
BillingAddress.​PhonestringBillToAddress.​PhoneCustomer Phone
BillingAddress.​Address1stringBillToAddress.​AddressLine1Customer Address Line 1
BillingAddress.​Address2stringBillToAddress.​AddressLine2Customer Address Line 2
BillingAddress.​CitystringBillToAddress.​CityCustomer City
BillingAddress.​StatestringBillToAddress.​StateCustomer State - 2 characters
BillingAddress.​ZipstringBillToAddress.​ZipCustomer Postal Code
BillingAddress.​CountrystringBillToAddress.​CountryThree-Character Country Code ISO country code.
If provided, we convert this value to the Alpha 2 two-character country code.
ShippingAddress.​FullNamestringShipToAddress.​NameIf full name is null, then the values of ShippingAddress.FirstName and ShippingAddress.LastName will be space-separated and concatenated.
ShippingAddress.​EmailstringShipToAddress.​EmailRecipient Email
ShippingAddress.​PhonestringShipToAddress.​PhoneRecipient Phone
ShippingAddress.​Address1stringShipToAddress.​AddressLine1Recipient Address Line 1
ShippingAddress.​Address2stringShipToAddress.​AddressLine2Recipient Address Line 2
ShippingAddress.​CitystringShipToAddress.​CityRecipient City
ShippingAddress.​StatestringShipToAddress.​StateRecipient State - 2 characters
ShippingAddress.​ZipstringShipToAddress.​ZipRecipient Postal Code
ShippingAddress.​CountrystringShipToAddress.​CountryThree-Character Country Code ISO country code.
If provided, we convert this value to the Alpha 2 two-character country code.
CreditCard.​BrandstringCard.​TypecnpAPI Type Documentation
Sending Visa results in VI being forwarded. Any value not listed below is forwarded unchanged.
‘Visa’ -> ‘VI’
‘Mastercard’ -> ‘MC’
‘AmericanExpress’ -> ‘AX’
‘DinersClub’ -> ‘DC’
‘Discover’ -> ‘DI’
‘Paypal’ -> ‘PP’
‘JCB’ -> ‘JC’
‘DirectDebit’ -> ‘EC’
‘Giftcard’ -> ‘GC’
‘Interac’ -> ‘IC’
CreditCard.​NumberstringCard.​NumberCard number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
CreditCard.​ExpMonthnumericCard.​ExpDateThe customer’s credit card expiration month. Format: 2 digits, zero-padded for single digits. Example: 03 = March, 11 = November
CreditCard.​ExpYearnumericCard.​ExpDateThe customer’s credit card expiration year. Format: 4 digits. For example: 2030
CreditCard.​CVVstringCard.​CardValidationNumThe card verification code.
Check.​AccountTypestringEcheck.​AccTypeSending the below values (left) results in the corresponding value (right) being forwarded. Values not listed below will return an error.
'Checking' -> 'Checking'
'Savings' -> 'Savings'
'CorporateChecking' ->'Corporate'
'CorporateSavings' -> 'Corp Savings'
Check.​AccountNumberstringEcheck.​AccNumBank account number or TokenEx Token - TokenEx will replace the Token with the Detokenized number
Check.​RoutingNumberstringEcheck.​RoutingNumRouting number
Check.​CheckNumberstringEcheck.​CheckNumThe ABA routing number.
CustomerIpAddressstringCardholderAuthentication.​CustomerIpAddressCustomer IP address of the purchaser.
ThreeDSecure.​CAVVstringCardholderAuthentication.​AuthenticationValueThe authentication value associated with the 3DS authentication
ThreeDSecure.​DSTransIdstringCarholderAuthentication.​AuthenticationTransactionIdThe Directory Server Transaction Id associated with the 3DS authenticaiton.
ThreeDSecure.​ProgramProtocolstringCardholderAuthentication.​AuthenticationProtocolVersionProtocol of 3DS - Defaults to 2 as 1 has been sunset.
SoftDescriptors.​MerchantPhonestringCustomBilling.​PhonePhone number to display on customer's statement
SoftDescriptors.​MerchantCitystringCustomBilling.​CityCity to display on customer's statement
SoftDescriptors.​MerchantUrlstringCustomBilling.​UrlURL to display on customer's statement
SoftDescriptors.​DescriptorstringCustomBilling.​Descriptor (Card requests)
CustomerIdentifier (Check requests)		Anything relevant to display on the customer's statement.
PartialboolPartialUsed only on Capture requests
ForeignRetailerIndicatorstringForeignRetailerIndicatorUsed only Capture and Sale requests for versions 12.31+

Example Requests​

{
  "gateway": "VantivCNP",
  "username": "Example",
  "password": "Example",
  "merchantId": "Example",
  "amount": 1000,
  "creditCard": {
    "number": "4470330769941000",
    "expMonth": 6,
    "expYear": 2028,
    "cvv": "123"
  },
  "billingAddress": {
    "phone": "555-555-5555",
    "email": "[email protected]",
    "fullName": "John > Doe",
    "company": "Test Co.",
    "address1": "123 & Someplace Lane",
    "address2": "Some Place",
    "city": "Tulsa",
    "state": "OK",
    "zip": "74111",
    "country": "USA"
  }
}

Gateway Response Parameters​

Field NameTypecnpAPI MappingNotes
ApprovedstringXmlAttribute response, XmlElement response.When the XmlAttribute response is not 0, then false. When XmlElement response is 000 or 010, then true. If the version is greater than or equal to 10.0 and less than 11.0, then 001 also equates true.
ApprovalCodestringAuthorizationResponse.AuthCode
SaleResponse.AuthCode		Transaction types that are not a Card Authorization or Card Purchase will not display a value for this parameter.
ProviderTransactionCodestringLitleTxnId or CnpTxnIdVersions 12+ are CnpTxnId, Versions less than 12 are LitleTxnId.
TokenExTransactionCodestringLitleTxnId or CnpTxnId plus the PS v2 TransactionType.Base 64 encoded concatenation of the transaction id and an internal transaction type mapping. For use with payment modifications.
GatewayErrors[0].CodestringXmlAttribute response, XmlElement response.When the XmlAttribute response is not 0, the code will be the value.
When the XmlAttribute response is 0 and approved is not true, the code will be the XmlElement response value.
GatewayErrors[0].MessagestringXmlAttribute message,
XmlElement message.		When the XmlAttribute response is not 0, the
message will be the value of the XmlElement message.
When the XmlAttribute response is 0 and approved is not true, the message will be the value of the XmlElement message.
GatewayErrors[0].SourcestringSee notes.If there was an issue deserializing the XML: TokenEx
When the XmlAttribute response is not 0: Gateway
When the XmlAttribute response is 0 and approved is not true: Processor

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\r\n<litleOnlineResponse xmlns=\"http://www.litle.com/schema\" version=\"9.4\" response=\"0\" message=\"Valid Format\">\r\n  <authorizationResponse id=\"8872540754908664656267734\" reportGroup=\"Example\">\r\n    <litleTxnId>370278980609125975</litleTxnId>\r\n    <orderId>8872540754908664656267734</orderId>\r\n    <response>000</response>\r\n    <message>Approved</message>\r\n    <responseTime>2024-05-08T20:33:30.906</responseTime>\r\n    <authCode>83341</authCode>\r\n  </authorizationResponse>\r\n</litleOnlineResponse>\r\n",
    "gatewayErrors": [],
    "tokenExTransactionCode": "MzcwMjc4OTgwNjA5MTI1OTc1OzE=",
    "approvalCode": "83341",
    "providerTransactionCode": "370278980609125975",
    "approved": true
  },
  "referenceNumber": "24050815221719567401",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on