Worldpay

Notes

  • The processorTransactionId is used to:

    • capture authorized transactions

    • refund sales

    • void transactions

  • The multi-capture call can be used to capture a single authorization in multiple stages.

Action

Standard Action

Worldpay Action

sale

sale

auth

authorization

offline

captureGivenAuth <not available>

capture

capture (full amount)

multi-capture

capture (requested amount)

refund

credit

credit

credit

create token

create token

verify

verify

void auth

authReversal

void capture

void

void refund

void

void sale

void

void credit

void

void force capture

void

Note

The capture action captures the entire authorized amount. Any passed-in amount is ignored.

The multi-capture action captures the requested amount, up to the full amount originally authorized.

Commerce Indicator

Maps to the orderSource field.

Standard Value

Worldpay Value

ecommerce

ecommerce

installment

installment

mailorder

mailorder

recurring

recurring

retail

(not supported)

telephone

telephone

IVR

(not supported)

initialCardOnFile

ecommerce

initialInstallment

installment

initialMailOrder

mailorder

initialRecurring

recurring

initialTelephone

telephone

initialIVR

(not supported)

cardOnFileEcommerce

ecommerce

cardOnFileMailOrder

mailorder

cardOnFileTelephone

telephone

3dsAttempted

3dsAttempted

3dsAuthenticated

3dsAuthenticated

initial3dsAttempted

3dsAttempted

initial3dsAuthenticated

3dsAuthenticated

Request Fields

Standard Field Name

Worldpay Field Name

account

card:number

action

action

affiliate

merchantData:affiliate

amount

amount

authorizationCode

authInformation:authCode

billToAddress_1

billToAddress:addressLine1

billToAddress_2

billToAddress:addressLine2

billToAddress_3

billToAddress:addressLine3

billToCity

billToAddress:city

billToCompany

billToAddress:companyName

billToCountry

billToAddress:country

billToEmail

billToAddress:email

billToFirstName

billToAddress:firstName

billToLastName

billToAddress:lastName

billToMiddleInitial

billToAddress:middleInitial

billToPhoneNumber

billToAddress:phone

billToPostalCode

billToAddress:zip

billToStateProvince

billToAddress:state

campaign

campaign

clientReferenceNumber

enhancedData:customerReference

commerceIndicator

orderSource

customerId

customerId

customerIp

cardholderAuthentication:customerIpAddr

cvv2

card:cardValidationNumber

expirationDate

card:expDate

invoiceNumber

invoiceReferenceNumber

merchantTaxId

enhancedData:detailTax:cardAcceptorTaxId

mop

card:type

orderNumber

orderId

processorDivision

merchantId

processorId

authentication:user

processorPassword

authentication:password

processorReportGroup

reportGroup

processorToken

litleToken

processorTransactionId

litleTxnId

processorUserId

authentication:user

requestPartialAuthorization

allowPartialAuth

requestProcessorTransaction

requestProcessorTransaction

reversalReason

authReversal:actionReason

shipToAddress_1

shipToAddress:addressLine1

shipToAddress_2

shipToAddress:addressLine2

shipToAddress_3

shipToAddress:addressLine3

shipToCity

shipToAddress:city

shipToCountry

shipToAddress:country

shipToEmail

shipToAddress:email

shipToPhoneNumber

shipToAddress:phone

shipToPostalCode

shipToAddress:zip

shipToStateProvince

shipToAddress:state

taxAmount

enhancedData:salesTax

taxExempt

enhancedData:taxExempt

Response Fields

Worldpay Field Name

Standard Field Name

auth_code

authorizationCode

auth_response_text

processorResponseText

TBD

processorAvsResponse

TBD

processorCvv2Response

TBD

processorResponseCode

TBD

partialAuthAmount

TBD

processorResponseCode

TBD

processorResponseText

litleToken

processorTransactionId

litleTxnId

processorTransactionId

Card Type Indicator Response

Worldpay Field Name

Standard Field Name

commercial

ctiCommercialCard

durbin_regulated

ctiDurbinExemptionCard

healthcare

ctiHealthcareCard

country_of_issuance

ctiIssuingCountry

payroll

ctiPayrollCard

debit

ctiPinlessDebitCard

prepaid

ctiPrepaidCard

Level 2 Data Requirements

The Mastercard and Visa card brands support Level 2 data elements, typically tax information. The standard amount field indicates the total transaction value, including tax. The taxAmount field contains the amount of tax included in the amount field.

Card Brand

Field

MC & VI

taxAmount

MC & VI

taxExempt

MC

merchantTaxId

MC

clientReferenceNumber (optional)

Set the taxExempt field to true or false depending on whether the individual transaction is tax exempt. Whenever you set the taxAmount value to 0.00, you must set the taxExempt field to true.

Level 2 data can be sent for the following transaction actions:

  • sale

  • auth

  • capture

  • multi-capture

  • refund

  • credit

Field Limits

Processor-specific field limits. Refer to the Payments Passthrough API Limits section for the general limits.

Min/Max

Field Name

Min

Max

amount

0.01

100000.00

Max Length

A “T” in the following table indicates the field is automatically trimmed to this length.

Field Name

Max #bytes

invoiceNumber

<ignored>

orderNumber

25 (required)

clientReferenceNumber

17T

billToFirstName

100T

billToLastName

100T

<bill to first + last name>

100T

billToAddress_1

35T

billToAddress_2

35T

billToCity

35T

billToPostalCode

20

shipToFirstName

100T

shipToLastName

100T

<ship to first + last name>

100T

shipToAddress_1

35T

shipToAddress_2

35T

shipToCity

35T

shipToPostalCode

20

Sample Transactions

Authorization

Request
{
    "id": 37,
    "method": "process_payment",
    "configurationId": "xyz",
    "mtid": "123",
    "utcTimestamp": "1477321809",
    "transaction": {
        "action": "auth",
        "amount": "101",
        "auvToken": "jQiI2m0Ii10ZAHW0009",
        "billToAddress_1": "1 Main St.",
        "billToCity": "Burlington",
        "billToCountry": "US",
        "billToFirstName": "John & Mary",
        "billToLastName": "Smith",
        "billToPostalCode": "01803-3747",
        "billToStateProvince": "MA",
        "commerceIndicator": "ecommerce",
        "currency": "USD",
        "cvv2": "349",
        "expirationDate": "2021-01",
        "mop": "VI",
        "orderNumber": "auth-sample",
        "processorDivision": "7103111",
        "processorId": "vantivLitle",
        "processorPassword": "certzg3y",
        "processorUserId": "AURIC",
        "requestProcessorTransaction": "true"
    }
}
Response
{
    "error": null,
    "elapsedTime": "2.2487",
    "id": 37,
    "version": "2.0",
    "traceUid": "Trace5X8hen1",
    "response": {
        "processorCvv2Response": "M",
        "avsResponse": "M01",
        "processorToken": "1111000274130009",
        "processorAvsResponse": "01",
        "cvv2Response": "M",
        "responseText": "Approved",
        "authorizationCode": "11111",
        "authorizationDateTime": "2016-10-24T15:10:11",
        "processorResponseCode": "000",
        "processorTransactionId": "82919144492728757",
        "processorResponseText": "Approved",
        "responseCode": "100",
        "elapsedProcessorTime": "2.1969"
    }
}

Capture

Capture entire amount originally authorized.

Request
{
    "id": 41,
    "method": "process_payment",
    "mtid": "12345678",
    "utcTimestamp": "1477321811",
    "configurationId": "TestConfiguration",
    "transaction": {
        "processorUserId": "AURIC",
        "processorPassword": "certzg3y",
        "requestProcessorTransaction": "true",
        "processorDivision": "7103111",
        "processorTransactionId": "82919144492728757",
        "action": "capture",
        "processorId": "vantivLitle"
    }
}
Response
{
    "error": null,
    "elapsedTime": "0.2883",
    "id": 41,
    "version": "2.0",
    "traceUid": "TraceR6CmlU1",
    "response": {
        "processorTransactionId": "82919144492728864",
        "processorResponseText": "Approved",
        "responseCode": "100",
        "responseText": "Approved",
        "elapsedProcessorTime": "0.2580",
        "processorResponseCode": "000"
    }
}

Multi-Capture

Capture part of amount originally authorized. Amount can be up to full original amount authorized.

Request
{
    "id": 41,
    "method": "process_payment",
    "mtid": "12345678",
    "utcTimestamp": "1477321811",
    "configurationId": "TestConfiguration",
    "transaction": {
        "processorUserId": "AURIC",
        "processorPassword": "certzg3y",
        "requestProcessorTransaction": "true",
        "processorDivision": "7103111",
        "processorTransactionId": "82919144492728757",
        "action": "multi-capture",
        "amount": "10.00",
        "processorId": "vantivLitle"
    }
}
Response
{
    "error": null,
    "elapsedTime": "0.2883",
    "id": 41,
    "version": "2.0",
    "traceUid": "TraceR6CmlU1",
    "response": {
        "processorTransactionId": "82919144492728864",
        "processorResponseText": "Approved",
        "responseCode": "100",
        "responseText": "Approved",
        "elapsedProcessorTime": "0.2580",
        "processorResponseCode": "000"
    }
}

Refund

Refund a sale or capture transaction. If the amount field is blank, the entire transaction is refunded. If the request includes the amount field then only that amount is refunded. Refunds require a processorTransactionId from a sale or capture transaction.

Request
{
    "method": "process_payment",
    "id": 64,
    "transaction": {
        "amount": "100.22",
        "processorId": "vantivLitle",
        "processorUserId": "AURIC",
        "processorPassword": "certzg3y",
        "action": "refund",
        "requestProcessorTransaction": "true",
        "processorTransactionId": "82919144548435712",
        "processorDivision": "7103111"
    },
    "utcTimestamp": "1477322497",
    "mtid": "12345678",
    "configurationId": "TestConfiguration"
}
Response
{
    "error": null,
    "id": 64,
    "traceUid": "TraceiKhyhh1",
    "elapsedTime": "0.2644",
    "version": "2.0",
    "response": {
        "responseCode": "100",
        "processorResponseText": "Approved",
        "processorResponseCode": "000",
        "elapsedProcessorTime": "0.2399",
        "responseText": "Approved",
        "processorTransactionId": "82919144548435753"
    }
}

Void

Since different payment processors have different void mappings, the service requires each type of transaction be voided by type. Refer to your {Vantiv} representative regarding time limits on any of these transactions.

Acceptable void transactions are:

  • void auth

  • void sale

  • void refund

  • void capture

  • void credit

  • void force capture

Request
{
    "method": "process_payment",
    "id": 68,
    "transaction": {
        "amount": "100",
        "processorId": "vantivLitle",
        "processorUserId": "AURIC",
        "processorPassword": "certzg3y",
        "action": "void refund",
        "requestProcessorTransaction": "true",
        "processorTransactionId": "82919144548435753",
        "processorDivision": "7103111"
    },
    "utcTimestamp": "1477322497",
    "mtid": "12345678",
    "configurationId": "TestConfiguration"
}
Response
{
    "error": null,
    "id": 68,
    "traceUid": "TraceIruABP1",
    "elapsedTime": "0.3824",
    "version": "2.0",
    "response": {
        "responseCode": "100",
        "processorResponseText": "Approved",
        "processorResponseCode": "000",
        "elapsedProcessorTime": "0.3580",
        "responseText": "Approved",
        "processorTransactionId": "82919144548435829"
    }
}

Void Authorization

Also called Authorization Reversal. Send only the processorTransactionId without an amount to void the entire authorization.

Request
{
    "utcTimestamp": "1477324018",
    "configurationId": "TestConfiguration",
    "method": "process_payment",
    "mtid": "12345678",
    "id": 78,
    "transaction": {
        "requestProcessorTransaction": "true",
        "processorUserId": "AURIC",
        "processorPassword": "certzg3y",
        "processorTransactionId": "82919144668120243",
        "action": "void auth",
        "processorDivision": "7103111",
        "processorId": "vantivLitle"
    }
}
Response
{
    "response": {
        "processorResponseText": "Approved",
        "responseText": "Approved",
        "elapsedProcessorTime": "0.8331",
        "processorTransactionId": "82919144672134461",
        "responseCode": "100",
        "processorResponseCode": "000"
    },
    "elapsedTime": "0.8567",
    "traceUid": "TraceQxlSOK1",
    "version": "2.0",
    "id": 78,
    "error": null
}

Partial Void

Also called Partial Authorization Reversal. Voids (reverses) the amount included in the transaction.

Request
{
    "transaction": {
        "processorPassword": "certzg3y",
        "processorTransactionId": "82919144692778255",
        "processorUserId": "AURIC",
        "processorId": "vantivLitle",
        "amount": "12.00",
        "requestProcessorTransaction": "true",
        "processorDivision": "7103111",
        "action": "void auth"
    },
    "configurationId": "TestConfiguration",
    "mtid": "12345678",
    "id": 88,
    "utcTimestamp": "1477324322",
    "method": "process_payment"
}
Response
{
    "error": null,
    "response": {
        "processorTransactionId": "82919144697202582",
        "elapsedProcessorTime": "2.0680",
        "processorResponseText": "Approved",
        "responseCode": "100",
        "responseText": "Approved",
        "processorResponseCode": "000"
    },
    "version": "2.0",
    "id": 88,
    "traceUid": "TraceLytbLO1",
    "elapsedTime": "2.0908"
}

Verify Only

Request
{
    "mtid": "12345678",
    "configurationId": "TestConfiguration",
    "method": "process_payment",
    "id": 94,
    "utcTimestamp": "1477326370",
    "transaction": {
        "processorPassword": "certzg3y",
        "currency": "USD",
        "cvv2": "349",
        "processorUserId": "AURIC",
        "auvToken": "f2jSkxXZBi0EiFj0009",
        "orderNumber": "verify",
        "expirationDate": "2021-01",
        "processorId": "vantivLitle",
        "processorDivision": "7103111",
        "billToCity": "Burlington",
        "billToAddress_1": "1 Main St.",
        "billToStateProvince": "MA",
        "billToCountry": "US",
        "billToPostalCode": "01803-3747",
        "billToLastName": "Smith",
        "action": "verify",
        "mop": "VI",
        "billToFirstName": "John & Mary",
        "commerceIndicator": "ecommerce",
        "requestProcessorTransaction": "true",
        "amount": "101"
    }
}
Response
{
    "error": null,
    "elapsedTime": "1.6844",
    "id": 94,
    "traceUid": "TraceWfRK1v1",
    "version": "2.0",
    "response": {
        "cvv2Response": "M",
        "processorCvv2Response": "M",
        "elapsedProcessorTime": "1.6329",
        "processorTransactionId": "82919144865875060",
        "authorizationCode": "11111",
        "processorResponseCode": "000",
        "processorAvsResponse": "01",
        "authorizationDateTime": "2016-10-24T16:26:12",
        "responseText": "Approved",
        "processorResponseText": "Approved",
        "processorToken": "1111000274130009",
        "avsResponse": "M01",
        "responseCode": "100"
    }
}

Token Swap

Request
{
    "mtid": "12345678",
    "configurationId": "TestConfiguration",
    "method": "process_payment",
    "id": 100,
    "utcTimestamp": "1477326372",
    "transaction": {
        "processorPassword": "certzg3y",
        "currency": "USD",
        "cvv2": "349",
        "processorUserId": "AURIC",
        "auvToken": "mFVnZVihW00O1fU0009",
        "orderNumber": "tokenize",
        "expirationDate": "2021-01",
        "processorId": "vantivLitle",
        "processorDivision": "7103111",
        "billToCity": "Burlington",
        "billToAddress_1": "1 Main St.",
        "billToStateProvince": "MA",
        "billToCountry": "US",
        "billToPostalCode": "01803-3747",
        "billToLastName": "Smith",
        "action": "create token",
        "mop": "VI",
        "billToFirstName": "John & Mary"
    }
Response
{"elapsedTime": "0.3589",
 "error": null,
 "id": 100,
 "response": {"elapsedProcessorTime": "0.3237",
              "processorResponseCode": "802",
              "processorResponseText": "Account number was previously registered",
              "processorToken": "1111000274130009",
              "processorTransactionId": "82919144865875276",
              "responseCode": "100",
              "responseText": "Approved"},
 "traceUid": "TraceJn0XXq1",
 "version": "2.0"}