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 Name | Type | cnpAPI Mapping | Notes |
---|---|---|---|
Gateway | string | N/A | VantivCNP |
Username | string | Authentication.User | The sandbox does not require registration. Populate with dummy values outside Prelive and Production. |
Password | string | Authentication.Password | The sandbox does not require registration. Populate with dummy values outside Prelive and Production. |
MerchantId | string | MerchantId | The sandbox does not require registration. Populate with dummy values outside Prelive and Production. |
VantivAPIVersion | string | Version | Defaults to 9.4. Versions below 9.4 may be functional but are not supported via this implementation. |
TransactionId | string | Id | Fall through assignment order: TransactionId , OrderInfo.OrderId , Random 25 digit string. |
ReportGroup | string | ReportGroup | Fall through assignment order: ReportGroup , MerchantId , "Default Report Group" |
OrderInfo.CustomerId | string | CustomerId | A value assigned by the merchant to identify the consumer. |
OrderInfo.OrderId | string | OrderId | If null, then the value assigned to Id is populated here. |
OrderInfo.OrderSource | string | OrderSource | Fall through assignment order: OrderInfo.OrderSource , "ecommerce" . |
Amount | numeric | Amount | The amount in minor units. For example, 2000 means USD 20.00. Max length: 12 characters. |
BillingAddress.FullName | string | BillToAddress.Name | If full name is null, then the values of BillingAddress.FirstName and BillingAddress.LastName will be space-separated and concatenated. |
BillingAddress.Company | string | BillToAddress.CompanyName | Company Name |
BillingAddress.Email | string | BillToAddress.Email | Customer Email |
BillingAddress.Phone | string | BillToAddress.Phone | Customer Phone |
BillingAddress.Address1 | string | BillToAddress.AddressLine1 | Customer Address Line 1 |
BillingAddress.Address2 | string | BillToAddress.AddressLine2 | Customer Address Line 2 |
BillingAddress.City | string | BillToAddress.City | Customer City |
BillingAddress.State | string | BillToAddress.State | Customer State - 2 characters |
BillingAddress.Zip | string | BillToAddress.Zip | Customer Postal Code |
BillingAddress.Country | string | BillToAddress.Country | Three-Character Country Code ISO country code. If provided, we convert this value to the Alpha 2 two-character country code. |
ShippingAddress.FullName | string | ShipToAddress.Name | If full name is null, then the values of ShippingAddress.FirstName and ShippingAddress.LastName will be space-separated and concatenated. |
ShippingAddress.Email | string | ShipToAddress.Email | Recipient Email |
ShippingAddress.Phone | string | ShipToAddress.Phone | Recipient Phone |
ShippingAddress.Address1 | string | ShipToAddress.AddressLine1 | Recipient Address Line 1 |
ShippingAddress.Address2 | string | ShipToAddress.AddressLine2 | Recipient Address Line 2 |
ShippingAddress.City | string | ShipToAddress.City | Recipient City |
ShippingAddress.State | string | ShipToAddress.State | Recipient State - 2 characters |
ShippingAddress.Zip | string | ShipToAddress.Zip | Recipient Postal Code |
ShippingAddress.Country | string | ShipToAddress.Country | Three-Character Country Code ISO country code. If provided, we convert this value to the Alpha 2 two-character country code. |
CreditCard.Brand | string | Card.Type | cnpAPI 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.Number | string | Card.Number | Card number or TokenEx Token - TokenEx will replace the Token with the Detokenized number |
CreditCard.ExpMonth | numeric | Card.ExpDate | The customer’s credit card expiration month. Format: 2 digits, zero-padded for single digits. Example: 03 = March, 11 = November |
CreditCard.ExpYear | numeric | Card.ExpDate | The customer’s credit card expiration year. Format: 4 digits. For example: 2030 |
CreditCard.CVV | string | Card.CardValidationNum | The card verification code. |
Check.AccountType | string | Echeck.AccType | Sending 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.AccountNumber | string | Echeck.AccNum | Bank account number or TokenEx Token - TokenEx will replace the Token with the Detokenized number |
Check.RoutingNumber | string | Echeck.RoutingNum | Routing number |
Check.CheckNumber | string | Echeck.CheckNum | The ABA routing number. |
CustomerIpAddress | string | CardholderAuthentication.CustomerIpAddress | Customer IP address of the purchaser. |
ThreeDSecure.CAVV | string | CardholderAuthentication.AuthenticationValue | The authentication value associated with the 3DS authentication |
ThreeDSecure.DSTransId | string | CarholderAuthentication.AuthenticationTransactionId | The Directory Server Transaction Id associated with the 3DS authenticaiton. |
ThreeDSecure.ProgramProtocol | string | CardholderAuthentication.AuthenticationProtocolVersion | Protocol of 3DS - Defaults to 2 as 1 has been sunset. |
SoftDescriptors.MerchantPhone | string | CustomBilling.Phone | Phone number to display on customer's statement |
SoftDescriptors.MerchantCity | string | CustomBilling.City | City to display on customer's statement |
SoftDescriptors.MerchantUrl | string | CustomBilling.Url | URL to display on customer's statement |
SoftDescriptors.Descriptor | string | CustomBilling.Descriptor (Card requests) CustomerIdentifier (Check requests) | Anything relevant to display on the customer's statement. |
Partial | bool | Partial | Used only on Capture requests |
ForeignRetailerIndicator | string | ForeignRetailerIndicator | Used 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": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"amount": 1000,
"tokenExTransactionCode": "<TokenExTransactionCode from a previous Authorize response>",
"ForeignRetailerIndicator":"F"
}
{
"gateway": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"amount":1000,
"tokenExTransactionCode": "<TokenExTransactionCode from a previous Capture or Purchase response>"
}
{
"gateway": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"tokenExTransactionCode": "<TokenExTransactionCode from a previous Authorize, Capture, or Purchase response>"
}
{
"gateway": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"Amount": 10000, // amount causes the success
"Check": {
"AccountNumber": "91243784",
"RoutingNumber": "314074269",
"AccountType": "savings"
},
"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": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"tokenExTransactionCode": "<TokenExTransactionCode from a previous Purchase response>"
}
{
"gateway": "VantivCNP",
"username": "Example",
"password": "Example",
"merchantId": "Example",
"tokenExTransactionCode": "<TokenExTransactionCode from a previous Purchase or Refund response>"
}
Gateway Response Parameters
Field Name | Type | cnpAPI Mapping | Notes |
---|---|---|---|
Approved | string | XmlAttribute 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. |
ApprovalCode | string | AuthorizationResponse.AuthCode SaleResponse.AuthCode | Transaction types that are not a Card Authorization or Card Purchase will not display a value for this parameter. |
ProviderTransactionCode | string | LitleTxnId or CnpTxnId | Versions 12+ are CnpTxnId, Versions less than 12 are LitleTxnId. |
TokenExTransactionCode | string | LitleTxnId 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].Code | string | XmlAttribute 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].Message | string | XmlAttribute message ,XmlElement message . | When the XmlAttribute response is not 0, themessage 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].Source | string | See notes. | If there was an issue deserializing the XML: TokenEx When the XmlAttribute response is not 0: GatewayWhen 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"
}
{
"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 <saleResponse id=\"8772791531805768303072535\" reportGroup=\"whatever\">\r\n <litleTxnId>247725905039698827</litleTxnId>\r\n <orderId>8772791531805768303072535</orderId>\r\n <response>000</response>\r\n <message>Approved</message>\r\n <responseTime>2024-05-08T20:50:41.542</responseTime>\r\n <authCode>50809</authCode>\r\n </saleResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "MjQ3NzI1OTA1MDM5Njk4ODI3OzI=",
"approvalCode": "50809",
"providerTransactionCode": "247725905039698827",
"approved": true
},
"referenceNumber": "24050815392796562309",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <captureResponse id=\"9408131457963676472375811\" reportGroup=\"Example\">\r\n <litleTxnId>879429199258342890</litleTxnId>\r\n <orderId />\r\n <response>000</response>\r\n <responseTime>2024-05-08T20:51:32.706</responseTime>\r\n <message>Approved</message>\r\n </captureResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "ODc5NDI5MTk5MjU4MzQyODkwOzM=",
"approvalCode": "",
"providerTransactionCode": "879429199258342890",
"approved": true
},
"referenceNumber": "24050815401975655217",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <creditResponse id=\"7428872428101282612278281\" reportGroup=\"Example\">\r\n <litleTxnId>434456361896843396</litleTxnId>\r\n <orderId />\r\n <response>000</response>\r\n <responseTime>2024-05-08T20:51:39.707</responseTime>\r\n <message>Approved</message>\r\n </creditResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "NDM0NDU2MzYxODk2ODQzMzk2OzQ=",
"approvalCode": "",
"providerTransactionCode": "434456361896843396",
"approved": true
},
"referenceNumber": "24050815402684506238",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <authReversalResponse id=\"7523862008558871422012774\" reportGroup=\"Example\">\r\n <litleTxnId>045666219656553510</litleTxnId>\r\n <orderId />\r\n <response>000</response>\r\n <responseTime>2024-05-08T20:51:51.067</responseTime>\r\n <message>Approved</message>\r\n </authReversalResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "MDQ1NjY2MjE5NjU2NTUzNTEwOzU=",
"approvalCode": "",
"providerTransactionCode": "045666219656553510",
"approved": true
},
"referenceNumber": "24050815403756081678",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <echeckSalesResponse id=\"8275901544583989549638546\" reportGroup=\"Example\">\r\n <litleTxnId>430626529229864486</litleTxnId>\r\n <orderId>8275901544583989549638546</orderId>\r\n <response>000</response>\r\n <responseTime>2024-05-08T20:57:33.885</responseTime>\r\n <message>Approved</message>\r\n </echeckSalesResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "NDMwNjI2NTI5MjI5ODY0NDg2OzY=",
"approvalCode": "",
"providerTransactionCode": "430626529229864486",
"approved": true
},
"referenceNumber": "24050815462046623336",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <echeckCreditResponse id=\"0324247985691314093343825\" reportGroup=\"Example\">\r\n <litleTxnId>035370170144769361</litleTxnId>\r\n <orderId />\r\n <response>000</response>\r\n <responseTime>2024-05-08T21:44:58.616</responseTime>\r\n <message>Approved</message>\r\n </echeckCreditResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "MDM1MzcwMTcwMTQ0NzY5MzYxOzc=",
"approvalCode": "",
"providerTransactionCode": "035370170144769361",
"approved": true
},
"referenceNumber": "024050816482188215415",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <echeckVoidResponse id=\"6575647767934537637712102\" reportGroup=\"Example\">\r\n <litleTxnId>641893858408209356</litleTxnId>\r\n <response>000</response>\r\n <responseTime>2024-05-08T20:54:13.245</responseTime>\r\n <postDate>2024-05-08</postDate>\r\n <message>Approved</message>\r\n </echeckVoidResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [],
"tokenExTransactionCode": "NjQxODkzODU4NDA4MjA5MzU2Ozg=",
"approvalCode": "",
"providerTransactionCode": "641893858408209356",
"approved": true
},
"referenceNumber": "24050815425943956983",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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 <captureResponse id=\"9661757399648823018610470\" reportGroup=\"Example\">\r\n <litleTxnId>704387086796118342</litleTxnId>\r\n <orderId />\r\n <response>000</response>\r\n <responseTime>2024-05-09T14:16:18.735</responseTime>\r\n <message>Approved</message>\r\n </captureResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [
{
"code": "8012",
"message": "Could not parse gateway response",
"source": "TokenEx"
}
],
"tokenExTransactionCode": "",
"approvalCode": "",
"providerTransactionCode": "",
"approved": false
},
"referenceNumber": "24050909050490601558",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"gatewayResponse": {
"rawResponse": "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\r\n<litleOnlineResponse xmlns=\"http://www.litle.com/schema\" version=\"9.4\" response=\"1\" message=\"Error validating xml data against the schema: cvc-maxLength-valid: Value '12356' with length = '5' is not facet-valid with respect to maxLength '4' for type 'cvNumType'.\" />\r\n",
"gatewayErrors": [
{
"code": "1",
"message": "Error validating xml data against the schema: cvc-maxLength-valid: Value '12356' with length = '5' is not facet-valid with respect to maxLength '4' for type 'cvNumType'.",
"source": "Gateway"
}
],
"tokenExTransactionCode": "",
"approvalCode": "",
"providerTransactionCode": "",
"approved": false
},
"referenceNumber": "24050815275988539202",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"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=\"9347230991882538679764619\" reportGroup=\"Example\">\r\n <litleTxnId>445792283125872902</litleTxnId>\r\n <orderId>9347230991882538679764619</orderId>\r\n <response>110</response>\r\n <message>Insufficient Funds</message>\r\n <responseTime>2024-05-08T20:37:00.293</responseTime>\r\n <authCode>41010</authCode>\r\n </authorizationResponse>\r\n</litleOnlineResponse>\r\n",
"gatewayErrors": [
{
"code": "110",
"message": "Insufficient Funds",
"source": "Processor"
}
],
"tokenExTransactionCode": "",
"approvalCode": "41010",
"providerTransactionCode": "445792283125872902",
"approved": false
},
"referenceNumber": "24050815254681834429",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
Updated 3 months ago