Menu

Orders

Example card order

Copied!
{
    "token": "your-token",
    "orderDescription": "your-order-description",
    "amount": 500,
    "authorizedAmount": 500,
    "currencyCode": "GBP",
    "currencyCodeExponent": 2,
    "settlementCurrency":"EUR",
    "settlementCurrencyExponent":2,
    "authorizeOnly": true,
    "is3DSOrder": true/false,
    "orderType": "ECOM",
    "orderCode": "worldpay-order-code",
    "orderCodePrefix": "prefix-string",
    "orderCodeSuffix": "suffix-string",
    "customerOrderCode": "your-customer-order-code",
    "paymentStatus": "SUCCESS",
    "paymentStatusReason": "reason",
    "paymentResponse": {
        "type": "ObfuscatedCard",
        "name": "name",
        "expiryMonth": 2,
        "expiryYear": 2015,
        "issueNumber": 2,
        "startMonth": 8,
        "startYear": 2013,
        "cardType": "VISA_CREDIT",
        "maskedCardNumber": "  ** 1111",
        "billingAddress": {
            "address1": "address1",
            "address2": "address2",
            "address3": "address3",
            "postalCode": "postCode",
            "city": "Reading",
            "state": "Berkshire",
            "countryCode": "GB",
            "telephoneNumber": "02079460761"
        },
        "cardSchemeType": "consumer",
        "cardSchemeName": "VISA CREDIT",
        "cardIssuer": "LLOYDS BANK PLC",
        "countryCode": "GB",
        "cardClass": "credit",
        "cardProductTypeDescNonContactless": "unknown",
        "cardProductTypeDescContactless": "unknown",
        "prepaid": "false",
        "apmFields": {
          "attribute1": "value1"
        }
    },
    "deliveryAddress": {
        "firstName": "John",
        "lastName": "Smith",
        "address1": "address1",
        "address2": "address2",
        "address3": "address3",
        "postalCode": "postCode",
        "city": "Reading",
        "state": "Berkshire",
        "countryCode": "GB",
        "telephoneNumber": "02079460761"
    },
    "shopperLanguageCode": "en",
    "shopperEmailAddress": "email address",
    "shopperIpAddress": "195.35.90.111",
    "shopperSessionId": "123",
    "shopperUserAgent": "user agent 1",
    "shopperAcceptHeader": "acceptheader",
    "redirectURL": "https://www.card-issuer.com/3DSecureAuthentication",
    "oneTime3DsToken": "value of PaReq",
    "threeDSResponseCode": "value of PaRes",
    "customerIdentifiers": {
        "key1": "my-value1" ,
        "key2": "my-value2" ,
        "key3": "my-value3" ,
        "key4": "my-value4" ,
        "key5": "my-value5"
    },
    "environment": "TEST",
    "riskScore":: {
        "value": "1"
    },
    "resultCodes": {
      "avsResultCode": "APPROVED",
      "cvcResultCode": "APPROVED"
    },
    "history": [
    {
       "modificationDate": "2014-05-07T09:26:27.658+0000",
       "state": "SUCCESS",
       "amount": 500,
       "currencyCode": "GBP",
       "currencyCodeExponent": 2
    },
    {
       "modificationDate": "2014-05-11T11:56:45.658+0000",
       "state": "SETTLED",
       "amount": 500,
       "currencyCode": "GBP",
       "currencyCodeExponent": 2,
       "netAmount": 490,
       "commission": 10,
       "settlementCurrency": "GBP",
       "settlementCurrencyExponent": 2
    },
     ],
    "disputes":[
    {
       "id":"documentId",
       "documentName":"document1.txt",
       "creationDate":"2015-05-06T14:14:03.684+0000"
    }
    ]
}

Order States

Worldpay uses the following Order States:

SUCCESS: The order was created successfully and the funds were charged to the customer's account

FAILED: The order was not successful

SENT_FOR_REFUND: A full or part refund has been requested for the order and is being processed

REFUNDED: The order has been wholly refunded to the customer

PARTIALLY_REFUNDED: Part of the order value has been refunded to the customer

AUTHORIZED: The order was authorised by the payment provider and the funds are reserved on the customer's account awaiting capture

CANCELLED: The authorization has been cancelled and the funds released to the customer's account

EXPIRED: The authorization expired and the funds released on the customer's account

SETTLED: The order value has been received from the payment provider

CHARGED_BACK: The customer disputed this order and the money was returned

INFORMATION_REQUESTED: When WorldPay disputes a charge-back, we will ask you for supporting information and doumentation

INFORMATION_SUPPLIED: You have supplied us information with which to dispute the charge-back

For further information please go to Order States

Order Types

Worldpay uses the following Order Types:

ECOM: the default value for an order

RECURRING: set the order to be of type recurring

MOTO: set the order to be of type Mail Order Telephone Order / Virtual Terminal

Card Types

Worldpay returns the following Card Types:

VISA_CREDIT: Visa Credit

VISA_DEBIT: Visa Debit

VISA_CORPORATE_CREDIT: Visa Corporate Credit

VISA_CORPORATE_DEBIT: Visa Corporate Debit

MASTERCARD_CREDIT: Mastercard Credit

MASTERCARD_DEBIT: Mastercard Debit

MASTERCARD_CORPORATE_CREDIT: Mastercard Corporate Credit

MASTERCARD_CORPORATE_DEBIT: Mastercard Corporate Debit

MAESTRO: Maestro

AMEX: American Express

CARTEBLEUE: Cartebleue

JCB: JCB

DINERS: Diners

AVS Result Codes

Worldpay returns these AVS Result Codes:

APPROVED: The supplied street and postal code details fully matched the payment provider's records

PARTIAL APPROVED: One of the supplied street or postal code details did not match the payment provider's records

NOT SENT TO ACQUIRER: Problem with acquirer - possibly no AVS support

NO RESPONSE FROM ACQUIRER: Problem with acquirer - possibly no AVS support

NOT CHECKED BY ACQUIRER: The acquirer did not check the address details

NOT SUPPLIED BY SHOPPER: Missing, incomplete or invalid address details in the order prevented the address from being checked

FAILED: Both street and postal code details did not match the payment provider's records

CVC Result Codes

Worldpay returns these CVC Result Codes:

APPROVED: The supplied CVC details matched the payment provider's records

NOT SENT TO ACQUIRER: Problem with acquirer - possibly no CVC support

NO RESPONSE FROM ACQUIRER: Problem with acquirer - possibly no CVC support

NOT CHECKED BY ACQUIRER: The acquirer did not check the CVC details

NOT SUPPLIED BY SHOPPER: Missing, or invalid CVC in the payment details prevented the CVC from being checked

FAILED: The supplied CVC did not match the payment provider's records

Attributes

tokenString, Optional
A unique token which the WorldPay.js library added to your checkout form, or obtained via the token API. This token represents the customer's card details/payment method which was stored on our server. One of token or paymentMethod must be specified
paymentMethodJSON
Object containing all payment details, contents vary by token type

Common paymentMethod / paymentResponse Attributes

typeString
String defining the payment type - either "Card" or "APM" in a request, "ObfuscatedCard" or "APM" in a response
nameString, optional
The name of the cardholder or payee

Card-specific paymentMethod / paymentResponse Attributes

expiryMonthString
Expiry month of the card
expiryYearString
Expiry year of the card
issueNumberString, optional
Issue number on the card.
startMonthString, optional
Start month of the card. This field is only used for some types of debit cards
startYearString, optional
Start year of the card. This field is only used for some types of debit cards
cardNumberString
Number of the card to be charged
cvcString
Security code of the card to be charged. This is also known as CVV or CV2. It is the 3-digit number at the back of the card. In the case of Amex, the 4-digit number at the front of the card
cardTypeString, only included in response
Type of the card that was used. Please seeherefor a list of supported card types
maskedCardNumberString, only included in response
The last four digits of the card number with all other numbers masked
cardSchemeTypeString, only included in response
Indicates the card is either 'consumer' or 'corporate'
cardSchemeNameString, only included in response
Type of the card that was used. Please seeherefor a list of supported card types
cardIssuerString, only included in response
The financial institution that issued the card
countryCodeString, only included in response
The issuer country code in ISO 3166 2-letter format
cardClassString, only included in response
Indicates whether the card is 'credit' or 'debit'
cardProductTypeDesc NonContactlessString, only included in response
Product type detail for non-contactless cards
cardProductTypeDesc ContactlessString, only included in response
Product type detail for contactless cards
prepaidString, only included in response
Indicates whether the card is prepaid

WPM/APM-specific paymentMethod / paymentResponse Attributes

apmNameString
The specific WPM/APM that this token represents
shopperCountryCodeString
Indicates to the payment provider which locale to present to the shopper in ISO 3166 2-letter format. Mandatory for WPM/APMs, unless a default country code is defined in Order Settings. Where both are defined this attribute's value will take precedence
apmFieldsJSON, optional
Allows supply of Payment Provider-specific attribute/value pairs e.g. shopper's Bank Code

Common Order Attributes

shopperLanguageCodeString, optional
ISO ISO 639-1 language code indicating the preferred language of the shopper, where supported by the Payment Provider.
orderDescriptionString, Mandatory
The description of the order provided by you
amountInteger, Mandatory
The amount to be charged in pennies/cents (or whatever the smallest unit is of the currencyCode that you specified, see currencyCodeExponent below)
authorizedAmountInteger, only included in response
The amount that has been authorized for this order in cents
currencyCodeString, Mandatory
The ISO currency code of the currency you want to charge your customer in. A list of ISO currency codes can be foundhere
currencyCodeExponentString, only included in response
The number of decimals after the dot for this currency. This is important to know as 'amount' has to be specified in the smallest unit of the currencyCode. The value will be 2 for most currencies but can sometimes be 3
settlementCurrencyString, Optional/Mandatory
The ISO currency code of the currency you want to be settled in in. This field is mandatory only if you have enabled multiple settlement currencies in currency settings (this setting is only available when you have activated your account). More information about settlement currencies can be foundhere
settlementCurrencyExponentString, only included in response
The number of decimals after the dot for this currency. This is important to know as 'amount' has to be specified in the smallest unit of the currencyCode. The value will be 2 for most currencies but can sometimes be 3
authorizeOnlyBoolean, Optional
Indicates the order must only authorize the funds, and not take payment. To take payment a Capture request must be sent. Not all payment methods support this feature.
is3DSOrderBoolean, Optional
Indicates that a card order should use 3D Secure if available. If this field is not specified 3D Secure will not be used
orderTypeString, Optional
Indicates the type of order you will be placing. See full list of order types in the right hand column. If this field is not specified the default value is ECOM
orderCodeString, only included in response
A WorldPay generated unique order code. This order code will be referred to in all of our reports. A prefix can be specified using the orderCodePrefix attribute.
orderCodePrefixString
Allows the automatically generated orderCode to be prefixed with a specified string. This prefix can be up to 20 characters long, and may only include alphanumeric (a-z A-Z 0-9) characters and - minus and _ underscore symbols.
orderCodeSuffixString
Allows the automatically generated orderCode to be suffixed with a specified string. This suffix can be up to 20 characters long, and may only include alphanumeric (a-z A-Z 0-9) characters and - minus and _ underscore symbols.
customerOrderCodeString, Optional
The code or ID under which this order is known in your systems
paymentStatusString, only included in response
The current status of the Order. See a list of possible states on the right hand side below the JSON
paymentStatusReasonString, only included in response
Payment Status Reason is an optional field available only when paymentStatus is FAILED
paymentResponseJSON, only included in response
Object containing all payment details
nameString, Optional
Name of the payee/cardholder. In the request this is passed at the top-level of the JSON. In the response it will be embedded in paymentResponse
expiryMonthString, only included in response
Expiry month of the card - card orders only
expiryYearString, only included in response
Expiry year of the card - card orders only
issueNumberString, only included in response
Issue number on the card. Note: This field is only used for some types of cards
startMonthString, only included in response
Start month of the card. This field is only used for some types of cards
startYearString, only included in response
Start year of the card. This field is only used for some types of cards
cardTypeString, only included in response
Type of the card that was used. Refer the Card Types in the section on the right, for supported card types. For many cards more detailed information about the card used including whether it was a debit or a credit card and the country it is registered in can be obtained via the Token API.
maskedCardNumberString, only included in response
the last four digits of the card number with all other numbers masked
billingAddressJSON, Optional
Object containing the address where the customer's card is registered. This object will be used for AVS address verification and other fraud checks, and is strongly recommended to be set. If any of (address1, city, postalCode or countryCode) are unset this object will be silently ignored. In the request this object is passed at the top-level of the JSON. In the response it will be embedded in paymentResponse
deliveryAddressJSON, Optional
Object containing the address where the goods/services are to be delivered/invoiced. This object will be used for fraud checks, and is strongly recommended to be set. If any of (address1, city, postalCode or countryCode) are unspecified this object will be silently ignored
firstNameString
The first name of the deliveree
lastNameString
The family name of the deliveree
address1String
The first line of the address. Note: This attribute must be specified and non-null for any address to be valid
address2String
The second line of the address
address3String
The third line of the address
postalCodeString
The postcode or ZIP code. Note: This attribute must be specified and non-null for any address to be valid
cityString
The postal town or city. Note: This attribute must be specified and non-null for any address to be valid
stateString
Subdivision of a country e.g. Schleswig-Holstein, Queensland
countryCodeString
The ISO 3166 alpha-2 2-letter country code. ISO country codes are definedhere. Note: This attribute must be specified and non-null for any address to be valid
telephoneNumberString
The telephone number associated with the address.
cardSchemeTypeString, only included in response
Indicates the card is either 'consumer' or 'corporate'
cardSchemeNameString, only included in response
Type of the card that was used. Please seeherefor a list of supported card types.
cardIssuerString, only included in response
The financial institution that issued the card
countryCodeString, only included in response
The issuer country code in ISO 3166 2-letter format
cardClassString, only included in response
Indicates whether the card is 'credit' or 'debit'
cardProductTypeDescNonContactlessString, only included in response
Product type detail for non-contactless cards
cardProductTypeDescContactless:String, only included in response
Product type detail for contactless cards
prepaidString, only included in response
Indicates whether the card is prepaid
shopperEmailAddressString, Optional
The email address supplied by the shopper
shopperIpAddressString, Optional
The customer's IP address e.g. "188.102.39.120". This must NOT be your server IP. Required for 3D Secure Orders
shopperSessionIdString, Optional
Set to the shopper's unique session identifier. Required for 3D Secure Orders
shopperUserAgentString, Optional
Set to the shopper's browser user agent. Required for 3D Secure Orders
shopperAcceptHeaderString, Optional
Accept header of the shopper's browser. Required for 3D Secure Orders
redirectURLString, only included in response
The URL of the payment provider or 3D Secure card issuer hosted page where your customer needs to authenticate their details. You should redirect the customer to this page
oneTime3DsTokenString, only included in response
3D Secure Orders only: Token to use when redirecting your customer to the card issuer hosted page where your customer needs to enter their 3D Secure password
threeDSResponseCodeString, Mandatory for 3DS
3D Secure Orders only: Response code you will receive from the card issuer after shopper authentication. This code must be provided in your order update when completing a 3D Secure order
successUrlString, Optional
The URL you require the shopper to be sent to after they authenticate successfully on the payment provider's site. Mandatory for APM orders, unless a default success URL is defined in Order Settings. Where both are defined this attribute's value will take precedence
failureUrlString, Optional
The URL you require the shopper to be sent to after they authenticate unsuccessfully on the payment provider's site. Mandatory for APM orders, unless a default failure URL is defined in Order Settings. Where both are defined this attribute's value will take precedence
pendingUrlString, Optional
The URL you require the shopper to be sent to when the payment approval is pending/not finalised. Mandatory for APM orders, unless a default pending URL is defined in Order Settings. Where both are defined this attribute's value will take precedence
cancelUrlString, Optional
The URL you require the shopper to be sent to after they cancel authentication on the payment provider's site. Mandatory for APM orders, unless a default cancel URL is defined in Order Settings. Where both are defined this attribute's value will take precedence
customerIdentifiersString, Optional
A set of custom attributes for your own use - up to 5 can be specified
key1String
Key for first custom identifier. You can specify any value for both the name and value of this attribute
key2String
Key for second custom identifier. You can specify any value for both the name and value of this attribute
key3String
Key for third custom identifier. You can specify any value for both the name and value of this attribute
key4String
Key for fourth custom identifier. You can specify any value for both the name and value of this attribute
key5String
Key for fifth custom identifier. You can specify any value for both the name and value of this attribute
environmentString, only included in response
Indicates whether this order was made in the TEST or LIVE environment
riskScoreJSON, only included in response
Contains feedback from the Worldpay fraud detection services which you can optionally use to complement scoring of your own risk management systems
valueString, only included in response
Worldpay assigned risk score for this order. Orders with a risk score of >=100 will be declined by Worldpay.
resultCodesJSON, only included in response
Contains feedback from the payment issuer which indicates the status of various checks on the payment details
avsResultCodeString, only included in response
Indicates the issuer-supplied outcome of the check between issuer-known and shopper-supplied billing address details, where available.
cvcResultCodeString, only included in response
Indicates the issuer-supplied outcome of the check between issuer-known and shopper-supplied security code details, where available.
historyJSON, only included in response
The history of paymentStatuses that this order has gone through. Please note: only fields not already covered in the list above will be explained again here. The full list of fields included in the history field is shown on the right
modificationDateString
Date when the paymentStatus change occurred
stateString
Value of paymentStatus after the change
netAmountInteger, only included in response
The amount that will be settled to you after commissions have been deducted in cents
commissionInteger, only included in response
The amount that will be deducted as fees in cents
disputesJSON, only included in response
Object containing details of documents that have been uploaded to defend against a disputed order
idString, only included in response
A Worldpay assigned identifier for this document
documentNameString, only included in response
The name for this document as assigned by you during document upload
creationDateString, only included in response
The date the document was uploaded