Menu

Note: This API is for preview purposes only and is subject to change.

Verified Payments

API v1
Last updated April 2023

Note: Make yourself familiar with ourAPI Principlesto ensure a resilient integration.

Set your headers

Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.

Please use the latest version: v1

Copied!
Authorization: {your_credentials}
Content-Type: application/vnd.worldpay.verifiedpayments-v1.hal+json
Accept: application/vnd.worldpay.verifiedpayments-v1.hal+json
HeaderDescription
AuthorizationWe use the Authorization header to identify and authenticate you within Access Worldpay. You must use the Authorization header for any request you send to our Verified Payments API.
Content-TypeWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT.
AcceptWe use the Accept header to identify which version of our Verified Payments API you are using. You must use the Accept header for any request you send to our Verified Payments API.

If you're using both the Content-Type and Accept headers, they must match.

Note: Replace {your_credentials} with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.

Request

Take a payment using a card number or a mobile wallet.

POST your request to the service:verifiedPayments action link.

POST https://try.access.worldpay.com/verifiedPayments/

See full API schema and examples in ourAPI Reference

Copied!
{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "MindPalaceLtd",
    "3ds": "enabled",
    "fraud": "fraudSight",
    "createToken": { 
      "type": "WorldPay",
      "namespace": "SHOPPER_ID_1234567890",
      "description": "Test Token Description"
   }
  },
  "instruction": {
    "paymentInstrument": {
      "cvc": "123",
      "type": "card/plain",
      "cardHolderName": "Sherlock Holmes",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    },
    "narrative": {
      "line1": "trading name",
      "line2": "order number"
    }
  },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
    "browserLanguage": "en-GB",
    "ipAddress": "176.80.113.83"
  },
  "challenge": {
    "returnUrl": "http://payment.example.com"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "00000000000"
    },
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "address1": "Durham University",
        "address2": "The Palatine Centre",
        "address3": "Stockton Road",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB"
      }
    }
  }
}
{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "entity1",
    "fraud": "fraudSight"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/wallet+googlepay",
      "walletToken": "{\"protocolVersion\":\"ECv2\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\": \"{\\\"keyExpiration\\\":\\\"1542323393147\\\",\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\\\u003d\\\\u003d\\\"}\",\"signatures\": [\"MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v\"]},\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}"
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    },
    "narrative": {
      "line1": "trading name",
      "line2": "order number"
    },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
    "browserLanguage": "en-GB",
    "ipAddress": "176.80.113.83"
  },
  "challenge": {
    "returnUrl": "http://payment.example.com"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "00000000000"
    },
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "address1": "Durham University",
        "address2": "The Palatine Centre",
        "address3": "Stockton Road",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB"
      }
    }
  }
}
{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "entity1",
    "fraud": "fraudSight"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/wallet+applepay",
      "walletToken": "{\"protocolVersion\":\"ECv2\",\"signature\":\"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\": \"{\\\"keyExpiration\\\":\\\"1542323393147\\\",\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\\\u003d\\\\u003d\\\"}\",\"signatures\": [\"MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v\"]},\"signedMessage\":\"{\\\"tag\\\":\\\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\\\u003d\\\",\\\"encryptedMessage\\\":\\\"mKOoXwi8OavZ\\\"}\"}"
      },
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "London",
        "state": "Greater London",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    },
    "narrative": {
      "line1": "trading name",
      "line2": "order number"
    },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
    "browserLanguage": "en-GB",
    "ipAddress": "176.80.113.83"
  },
  "challenge": {
    "returnUrl": "http://payment.example.com"
  },
  "riskData": {
    "account": {
      "email": "sherlock.holmes@example.com"
    },
    "transaction": {
      "firstName": "Sherlock",
      "lastName": "Holmes",
      "phoneNumber": "00000000000"
    },
    "shipping": {
      "firstName": "James",
      "lastName": "Moriarty",
      "address": {
        "address1": "Durham University",
        "address2": "The Palatine Centre",
        "address3": "Stockton Road",
        "postalCode": "DH1 3LE",
        "city": "Durham",
        "state": "County Durham",
        "countryCode": "GB"
      }
    }
  }
}

Merchant configuration

You can configure how the Verified Payments flow works in terms of Fraud assessment, 3DS and token creation.

merchant.3dsenabled / disabled

Always attempt 3DS or disable
merchant.fraudfraudsight / fraudSightSilentMode / disabled

Use FraudSight, set fraudSight to learning only or disable
merchant.createToken.typeworldpay
A token will be created following the payment

See a full list of key:values in ourAPI Reference

Responses

Copied!
{
  "outcome": "fraudHighRisk",
  "transactionReference": "Memory265-13/08/1876",
  "reason": [
    "Recent unexpected card activity"
  ],
  "score": 97.4
}
{
	"outcome": "3dsDeviceDataRequired",
	"transactionReference": "Memory265-13/08/1876",
	"deviceDataCollection": {
		"jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI1ZmI1NDA5MzlkMzFjNzc4YzVhMTJiOGQiLCJpc3MiOiI1ZmI1NDA5MjgyMGZmNDRkOGIwY2RmOGYiLCJleHAiOjE2Njg2NDI4MjcsImlhdCI6MTY2ODY0MjIyNywianRpIjoiNmIxOTllMmMtZjY4My00Mzk2LTk4MjYtMzU4MTAwNmIwZWYzIn0.hf6O96olL1HyRM5m8cu6zfcYXnMja0OoXLwjQvw4Tvc",
		"url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
		"bin": "400000"
	},
	"_links": {
		"verifiedPayments:3dsDeviceData": {
			"href": "https://try.access.worldpay.com/verifiedPayments/3dsDeviceData/eyJrIjoxLCJkIjoidFAxbzA5YVdEb0duOE11amozTENJMEFTRGNKN3QxY1p5Mm5CM2Q0V0oxaElIdGlIaEE5VVlwdTlwVmg5UTJLYiJ9"
		},
		"curies": [
			{
				"href": "https://try.access.worldpay.com/rels/verifiedPayments/{rel}",
				"name": "verifiedPayments",
				"templated": true
			}
		]
	}
}
{
  "outcome": "sentForSettlement",
  "transactionReference": "Memory265-13/08/1876",
  "fraud": {
    "score": "78",
    "outcome": "lowRisk"
  },
  "3ds": {
    "outcome": "authenticated",
    "issuerResponse": "frictionless"
  },
  "_links": {
    "payments:refund": {
      "href": "https://try.access.worldpay.com/payments/settlements/refunds/full/eyJrIjoiazNhYjYzMiIsI"
    },
    "payments:partialRefund": {
      "href": "https://try.access.worldpay.com/payments/settlements/refunds/partials/eyJrIjoiazNhYjYzMiIsI"
    },
    "payments:events": {
      "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiIsI"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/payments/{rel}",
        "name": "payments",
        "templated": true
      }
    ]
  }
}
{
  "outcome": "sentForCancellation",
  "transactionReference": "Memory265-13/08/1876",
  "riskFactors": [
    {
      "risk": "not_matched",
      "type": "cvc"
    },
    {
      "risk": "not_matched",
      "detail": "address",
      "type": "avs"
    }
  ],
  "fraud": {
    "score": "78",
    "outcome": "lowRisk"
  },
  "3ds": {
    "outcome": "authenticated",
    "issuerResponse": "frictionless"
  },
  "_links": {
    "payments:events": {
      "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiIsI"
    },
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/verifiedPayments/{rel}",
        "templated": true,
        "name": "verifiedPayments"
      }
    ]
  }
}
{
  "outcome": "refused",
  "description": "CARD EXPIRED",
  "code": "33",
  "transactionReference": "Memory265-13/08/1876",
  "riskFactors": [
    {
      "risk": "not_matched",
      "type": "cvc"
    },
    {
      "risk": "not_matched",
      "detail": "address",
      "type": "avs"
    }
  ],
  "fraud": {
    "score": "78",
    "outcome": "lowRisk"
  },
  "3ds": {
      "outcome": "authenticated",
      "issuerResponse": "frictionless"
  },
  "_links": {
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/verifiedPayments/{rel}",
        "templated": true,
        "name": "verifiedPayments"
      }
    ]
  }
}

List ofrefusal codes

fraudHighRisk - halts the transaction before proceeding any further to 3DS or payment.

3DS

If the outcome is 3dsDeviceDataRequired the payment won't proceed until device data collection (fingerprinting) is performed on the customers browser. This may also prompt an issuer challenge screen as a form of identity check.