openapi: 3.0.1
info:
title: 3DS 3DS actions Payment API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n
\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe 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`.\n
\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Payment
description: Take a payment
paths:
/api/payments:
post:
tags:
- Payment
summary: Payment request
description: Initiate payment
operationId: payment
parameters:
- name: WP-Api-Version
in: header
description: The API version
required: true
schema:
type: string
description: The API version
enum:
- '2024-06-01'
example: '2024-06-01'
example: '2024-06-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
examples:
Card - ecom:
$ref: '#/components/examples/card-payment'
Card - moto:
$ref: '#/components/examples/card-payment_moto'
Card - auto settlement:
$ref: '#/components/examples/card-payment-auto-settlement'
Card - integrated 3DS authentication:
$ref: '#/components/examples/card-payment-integrated-3ds'
Card - external 3DS authentication:
$ref: '#/components/examples/card-payment-external-3ds'
Card - SCA exemption:
$ref: '#/components/examples/card-payment-exemption'
Card - Fraud assessment:
$ref: '#/components/examples/card-payment-fraud'
Card - Payment facilitator:
$ref: '#/components/examples/card-payment-payfac'
Card - Account funding transaction (AFT):
$ref: '#/components/examples/card-payment-fundsTransfer'
Card - Preferred card brand:
$ref: '#/components/examples/card-payment-cobranded'
Card - Checkout SDK session:
$ref: '#/components/examples/card-payment-checkout'
Card - Delegate token:
$ref: '#/components/examples/card-payment-delegate'
Card - payment & store (Worldpay Token):
$ref: '#/components/examples/store-card-token'
Card - Store card (no payment):
$ref: '#/components/examples/store-card-only-token'
Stored - Worldpay Token (href):
$ref: '#/components/examples/use-stored-card-token-href'
Stored - Worldpay Token (tokenId & namespace):
$ref: '#/components/examples/use-stored-card-token-tokenId-namespace'
Stored - Network Token:
$ref: '#/components/examples/use-stored-card-network-token'
Stored - Worldpay Token & Checkout CVC session:
$ref: '#/components/examples/use-stored-card-checkout-cvc'
Apple Pay - encrypted:
$ref: '#/components/examples/apple-pay-encrypted'
Apple Pay - decrypted:
$ref: '#/components/examples/apple-pay-decrypted'
Google Pay - encrypted:
$ref: '#/components/examples/google-pay-encrypted'
Google Pay - decrypted (CRYPTOGRAM_3DS):
$ref: '#/components/examples/google-pay-decrypted-cryptogram-3ds'
Google Pay - decrypted (PAN_ONLY):
$ref: '#/components/examples/google-pay-decrypted-pan-only'
Subscription - setup:
$ref: '#/components/examples/setup-recurring-subscription'
Subscription - setup - (no payment):
$ref: '#/components/examples/setup-recurring-subscription-zero'
Subscription - subsequent:
$ref: '#/components/examples/subsequent-recurring-subscription'
Installment - setup (merchant):
$ref: '#/components/examples/setup-recurring-installment-merchant'
Installment - subsequent (merchant):
$ref: '#/components/examples/subsequent-recurring-installment-merchant'
Installment - setup (Latin America):
$ref: '#/components/examples/setup-recurring-installment-latam'
Unscheduled:
$ref: '#/components/examples/recurring-unscheduled'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsResponse201'
examples:
authorized (basic):
$ref: '#/components/examples/authorized-201-basic'
authorized (full):
$ref: '#/components/examples/authorized-201-full'
3dsDeviceDataRequired:
$ref: '#/components/examples/3ds-device-data-required-201'
fraudHighRisk:
$ref: '#/components/examples/fs-highrisk'
refused:
$ref: '#/components/examples/refused-201'
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentsResponse202'
examples:
sentForSettlement (basic):
$ref: '#/components/examples/sent-for-settlement-202-basic'
sentForSettlement (full):
$ref: '#/components/examples/sent-for-settlement-202-full'
sentForCancellation:
$ref: '#/components/examples/sent-for-cancellation-202'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
examples:
Bad request:
$ref: '#/components/examples/400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized:
$ref: '#/components/examples/401'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Not found:
$ref: '#/components/examples/404'
'406':
description: Not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/HeaderErrorResponse'
examples:
Not acceptable:
$ref: '#/components/examples/406'
'415':
description: Unsupported media type
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unsupported media type:
$ref: '#/components/examples/415'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal server error:
$ref: '#/components/examples/500'
x-orderingPosition: '1'
components:
examples:
store-card-token:
description: 'Card payment using a plain card number that will also create a Worldpay Token for use with future customer initiated transactions (CIT)
'
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
tokenCreation:
type: worldpay
customerAgreement:
type: cardOnFile
storedCardUsage: first
narrative:
line1: trading name
value:
currency: GBP
amount: 42
refused-201:
description: 'Example of a refused response.
'
value:
outcome: refused
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: Memory265-13/08/1876
refusalDescription: REFUSED
refusalCode: '5'
advice:
code: '01'
riskFactors:
- risk: notChecked
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
google-pay-decrypted-pan-only:
description: Provide the decrypted PAN_ONLY Google Pay payload
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: googlepay
paymentInstrument:
type: decrypted
number: '4444333322221111'
expiryDate:
month: 5
year: 2035
threeDS:
type: integrated
mode: always
exemptionOnOutage: true
deviceData:
acceptHeader: text/html
userAgentHeader: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)
browserLanguage: en-GB
browserScreenWidth: 900
browserScreenHeight: 1200
browserJavaEnabled: true
browserColorDepth: '32'
timeZone: '300'
browserJavascriptEnabled: true
channel: browser
challenge:
returnUrl: http://payment.example.com
narrative:
line1: trading name
value:
currency: GBP
amount: 42
setup-recurring-subscription:
description: Set up a recurring subscription payment (first). This is a customer initiated transaction (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
tokenCreation:
type: worldpay
customerAgreement:
type: subscription
storedCardUsage: first
narrative:
line1: trading name
value:
currency: GBP
amount: 42
'406':
value:
errorName: headerIsMissing
message: A valid header must be provided.
headerName: Content-Type
card-payment-fraud:
description: 'A one-off card payment using a plain card number that also performs a fraud assessment
* See [how to enable fraud assessment](/products/payments/enable-features/fraud-assessment) for details
'
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
fraud:
type: fraudSight
customer:
firstName: John
lastName: Appleseed
email: john.appleseed@example.com
phone: '00000000000'
ipAddress: 192.168.0.1
dateOfBirth: '1985-11-23'
customerId: id123
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment_moto:
description: A one-off MOTO card payment using a plain card number
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
channel: moto
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
setup-recurring-installment-merchant:
description: Set up a recurring installment payment (first). This is a customer initiated transaction (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
tokenCreation:
type: worldpay
customerAgreement:
type: installment
installmentType: merchant
storedCardUsage: first
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-external-3ds:
description: "A one-off card payment using a plain card number that also contains 3DS authentication details. \n* Values that are [required by the schemes](/products/payments/enable-features/3ds-authentication/integrated-3ds/#emvco-required-values) are included in this example. \n* See [how to enable external MPI authentication](/products/payments/enable-features/3ds-authentication/external-3ds) for integration details\n"
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
threeDS:
type: external
version: 2.2.0
eci: '05'
authenticationValue: kBNHXUAy4+HT1gAMBSDajheBcxQh
dsTransactionId: b8fb4ecc-7e2e-4b1c-816d-0149849776b8
customer:
email: john.appleseed@example.com
phone: '00000000000'
ipAddress: 192.168.0.1
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-auto-settlement:
description: A guest card payment using a plain card number. The payment will move to `authorize` and `send for settlement` if basic CVC/AVS checks pass.
__We recommend disabling cancel on avsNotMatched/cvcNotMatched as shown in the example.__
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
settlement:
auto: true
cancelOn:
avsNotMatched: disabled
cvcNotMatched: disabled
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
use-stored-card-checkout-cvc:
description: Use a previously stored Worldpay token for a customer initiated transaction (CIT) and use the Checkout SDK (cvcSessionHref) to capture the CVC value
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
href: https://try.access.developer.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
cvcSessionHref: https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoialRBL0FFelB....
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
narrative:
line1: trading name
value:
currency: GBP
amount: 42
use-stored-card-network-token:
description: Use a previously stored network token for a customer initiated payment (CIT).
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: networkToken
tokenNumber: '4444333322221111'
cryptogram: MAAAAAAAAAAAAAAAAAAAAAAAAAB=
eci: '07'
expiryDate:
month: 2
year: 2035
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
narrative:
line1: trading name
value:
currency: GBP
amount: 42
store-card-only-token:
description: 'Create a Worldpay Token for use with future customer initiated transactions (CIT)
* `value.amount` is set to `0` to indicate this is not a payment and a card verification will be performed instead
'
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
tokenCreation:
type: worldpay
customerAgreement:
type: cardOnFile
storedCardUsage: first
narrative:
line1: trading name
value:
currency: GBP
amount: 0
card-payment-exemption:
description: "A guest card payment using a plain card number that also performs 3DS authentication. \n* Values [required by the schemes](/products/payments/enable-features/3ds-authentication/#emvco-required-values) are included in this example\n* See [how to enable an SCA exemption](/products/payments/enable-features/sca-exemptions/) for integration details\n"
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
threeDS:
type: integrated
mode: always
deviceData:
acceptHeader: text/html
userAgentHeader: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)
browserLanguage: en-GB
browserScreenWidth: 900
browserScreenHeight: 1200
browserJavaEnabled: true
browserColorDepth: '32'
timeZone: '300'
browserJavascriptEnabled: true
channel: browser
challenge:
returnUrl: http://payment.example.com
exemption:
type: integrated
mode: always
capability: authorizationAndAuthentication
request:
placement: optimized
type: optimized
customer:
email: john.appleseed@example.com
phone: '00000000000'
ipAddress: 192.168.0.1
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-fundsTransfer:
description: A one-off cryptocurrency wallet load card payment using a plain card number
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
fundsTransfer:
type: walletLoad
purpose: crypto
recipient:
account:
type: storedValueWallet
walletReference: ABCDE12345
firstName: John
middleName: Roger
lastName: Smith
address:
address1: 221B Baker Street
address2: Marylebone
postalCode: NW1 6XE
city: London
state: LDN
countryCode: GB
dateOfBirth: '1985-11-23'
phoneNumber: +447987 654321
sender:
firstName: John
middleName: Roger
lastName: Smith
address:
address1: 221B Baker Street
address2: Marylebone
postalCode: NW1 6XE
city: London
state: LDN
countryCode: GB
narrative:
line1: trading name
value:
currency: GBP
amount: 42
'500':
value:
errorName: internalErrorOccurred
message: We cannot currently process your request. Please contact support.
sent-for-cancellation-202:
value:
outcome: sentForCancellation
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: f4806b75-89d1-498a-8634-bfa79afca54f
schemeReference: '060720116005060'
issuer:
authorizationCode: '675725'
riskFactors:
- risk: notMatched
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
fraud:
outcome: lowRisk
score: 44
threeDS:
outcome: authenticated
issuerResponse: frictionless
paymentInstrument:
type: card/plain+masked
cardBin: '400000'
lastFour: '1000'
countryCode: GB
expiryDate:
year: 2035
month: 5
cardBrand: mastercard
fundingType: debit
category: consumer
issuerName: BANK LIMITED
paymentAccountReference: 3001DBT34Q41D6J7PFC5W0UACOT4C
_links:
self:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3Am1abCnrwHIBOLZ%3A8ZpsSaLoyDtB%3A8H%2BxSOOOGjEbko3O%3A%3A7gTMASwaw7KY3SuOCoh4KCq84ktTU7AB2kOFpTY0bs7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ3ZOMOj3ix5oo3ctSHv2uo5m6InByzI1XuTONS3N8O%2B1%2BuC8Xk67Ze0uAJk%2BrJN9o7Z%3AVhRHFzbbwymcuTiRbNw%3D
'404':
value:
errorName: endpointNotFound
message: Requested endpoint was not found.
card-payment-payfac:
description: A one-off payment facilitator card payment using a plain card number
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
paymentFacilitator:
schemeId: '12345'
independentSalesOrganizationId: '12345'
subMerchant:
name: Sub Merchant Plc
reference: '12345'
address:
postalCode: SW1 1AA
street: Regent Street
city: London
countryCode: GB
state: CA
taxReference: '12345'
phoneNumber: 0123456789
email: test@email.com
url: url.example.com
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
setup-recurring-subscription-zero:
description: Set up a recurring subscription payment (first). This is a customer initiated transaction (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
tokenCreation:
type: worldpay
customerAgreement:
type: subscription
storedCardUsage: first
narrative:
line1: trading name
value:
currency: GBP
amount: 0
authorized-201-full:
description: "Example of an authorized response. Use the action `settlePayment` to complete the transaction. \n\nIncludes response information for: \n - [Fraud assessment](/products/payments/enable-features/fraud-assessment) \n - [Worldpay token creation](/products/payments/store-a-card)\n - [SCA Exemption](/products/payments/enable-features/sca-exemptions)\n - [Revenue Boost](/products/payments/openapi/payment/payment#payment/payment/t=response&c=201&path=&d=0/updatedpaymentinstrument)\n - [Account Updater](/products/payments/enable-features/account-updater)\n - [Partial Authorization](/products/payments/openapi/payment/payment#payment/payment/t=request&path=instruction&d=0/value/acceptpartialamount)\n"
value:
outcome: authorized
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: Memory265-13/08/1876
schemeReference: '060720116005060'
issuer:
authorizationCode: '675725'
riskFactors:
- risk: notChecked
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
fraud:
outcome: lowRisk
score: 44.6
exemption:
granted: true
placement: authorization
type: lowRisk
result: honored
reason: issuerHonored
token:
href: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiRVl3SDBtNnpEVmVTR3UzRUV3VEJEVDExTkxuVDVydXNiREdLR01hUXUwVT0ifQ
tokenId: '9968110159504301628'
tokenExpiryDateTime: '2024-04-11T15:59:23Z'
cardNumber: 4000********1000
cardHolderName: test
cardExpiry:
year: 2035
month: 5
bin: '400000'
fundingType: debit
countryCode: GB
schemeReference: '060720116005060'
conflicts:
conflictsExpiryDateTime: '2024-07-04T06:40:32.310316518Z'
paymentInstrument:
cardHolderName: John Snow
paymentInstrument:
type: card/plain+masked
cardBin: '400000'
lastFour: '1000'
countryCode: GB
expiryDate:
year: 2035
month: 5
cardBrand: mastercard
fundingType: debit
category: consumer
issuerName: BANK LIMITED
paymentAccountReference: 3001DBT34Q41D6J7PFC5W0UACOT4C
updatedPaymentInstrument:
appliedNetworkToken: true
accountUpdaterMessage: The account number was changed
type: card/plain+masked
cardBin: '888877'
lastFour: '5555'
expiryDate:
month: 9
year: 2031
cardBrand: visa
fundingType: credit
amounts:
requested: 1000
totalAuthorized: 700
currency: GBP
partialAuthorization: true
_links:
self:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D
_actions:
cancelPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/cancellations
method: POST
settlePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/settlements
method: POST
partiallySettlePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/partialSettlements
method: POST
reversePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/reversals
method: POST
card-payment:
description: A one-off card payment using a plain card number
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-cobranded:
description: 'A one-off card payment using a plain card number that specifies your customer''s preferred card brand
'
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000004970'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
routing:
preferredCardBrand: cartesBancaires
cvc: '123'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
recurring-unscheduled:
description: Subsequent unscheduled payment as part of a customer agreement. This is a merchant initiated transaction (MIT).
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
href: https://try.access.developer.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: unscheduled
schemeReference: MCCOLXT1C0104
narrative:
line1: trading name
value:
currency: GBP
amount: 42
fs-highrisk:
description: If [FraudSight is enabled](/products/payments/enable-features/fraud-assessment) the payment could be flagged as `fraudHighRisk`, stopping the request from proceeding any further
value:
outcome: fraudHighRisk
transactionReference: 2847f678-fd97-4558-b913-8945c8b11dc9
score: 97
reason:
- Recent unexpected card activity
card-payment-integrated-3ds:
description: "A one-off card payment using a plain card number that also performs 3DS authentication. \n* Values that are [required by the schemes](/products/payments/enable-features/3ds-authentication/#emvco-required-values) are included in this example. \n* See [how to enable 3DS authentication](/products/payments/enable-features/3ds-authentication/) for integration details\n"
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
cvc: '123'
threeDS:
type: integrated
mode: always
exemptionOnOutage: true
deviceData:
acceptHeader: text/html
userAgentHeader: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)
browserLanguage: en-GB
browserScreenWidth: 900
browserScreenHeight: 1200
browserJavaEnabled: true
browserColorDepth: '32'
timeZone: '300'
browserJavascriptEnabled: true
channel: browser
challenge:
returnUrl: http://payment.example.com
customer:
email: john.appleseed@example.com
phone: '00000000000'
ipAddress: 192.168.0.1
narrative:
line1: trading name
value:
currency: GBP
amount: 42
authorized-201-basic:
description: 'Example of an authorized response. Use the action `settlePayment` to complete the transaction
'
value:
outcome: authorized
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: Memory265-13/08/1876
schemeReference: '060720116005060'
issuer:
authorizationCode: '675725'
riskFactors:
- risk: notChecked
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
paymentInstrument:
type: card/plain+masked
cardBin: '400000'
lastFour: '1000'
countryCode: GB
expiryDate:
year: 2035
month: 5
cardBrand: mastercard
fundingType: debit
category: consumer
issuerName: BANK LIMITED
paymentAccountReference: 3001DBT34Q41D6J7PFC5W0UACOT4C
_links:
self:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D
_actions:
cancelPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/cancellations
method: POST
settlePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/settlements
method: POST
partiallySettlePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/partialSettlements
method: POST
reversePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/reversals
method: POST
subsequent-recurring-subscription:
description: Subsequent payment as part of a recurring subscription series
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
href: https://try.access.developer.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: subscription
storedCardUsage: subsequent
schemeReference: MCCOLXT1C0104
narrative:
line1: trading name
value:
currency: GBP
amount: 42
setup-recurring-installment-latam:
description: Set up a Latin America installment payment. This is a customer initiated transaction (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: plain
cardHolderName: Sherlock Holmes
cardNumber: '4000000000001091'
expiryDate:
month: 5
year: 2035
cvc: '123'
customerAgreement:
type: installment
installmentType: latinAmerica
installmentPlan:
numberOfInstallments: 4
narrative:
line1: trading name
value:
currency: GBP
amount: 42
use-stored-card-token-href:
description: Use a previously stored Worldpay token for a customer initiated payment (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
cvc: '333'
href: https://try.access.developer.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
narrative:
line1: trading name
value:
currency: GBP
amount: 42
'401':
value:
errorName: accessDenied
message: Access to the requested resource has been denied.
sent-for-settlement-202-basic:
description: 'Example of a sentForSettlement response. [Auto settlement](/products/payments/enable-features/auto-settlement) was enabled in the payment request.
'
value:
outcome: sentForSettlement
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: Memory265-13/08/1876
schemeReference: '060720116005060'
issuer:
authorizationCode: '675725'
riskFactors:
- risk: notChecked
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
paymentInstrument:
type: card/plain+masked
cardBin: '400000'
lastFour: '1000'
countryCode: GB
expiryDate:
year: 2035
month: 5
cardBrand: mastercard
fundingType: debit
category: consumer
issuerName: BANK LIMITED
paymentAccountReference: 3001DBT34Q41D6J7PFC5W0UACOT4C
_links:
self:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D
_actions:
refundPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D/refunds
method: POST
partiallyRefundPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D/partialRefunds
method: POST
reversePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/partialSettlements
method: POST
apple-pay-encrypted:
description: Provide the encrypted Apple Pay payload
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: applepay
paymentInstrument:
type: encrypted
walletToken: '{"version": "EC_v1","data": "kdHd..GQ==","signature": "MIAGCSqGSIb3DQEH...AAA","header": {"transactionId": "d3b28af..f8","ephemeralPublicKey": "MFkwE..Q==","publicKeyHash": "dxCK..6o="}}'
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-checkout:
description: "A one-off card payment using the Checkout SDK to capture card details in a short lived session. \n"
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: checkout
cardHolderName: Sherlock Holmes
sessionHref: https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
billingAddress:
address1: 221B Baker Street
address2: Marylebone
address3: Westminster
postalCode: SW1 1AA
city: London
state: Greater London
countryCode: GB
narrative:
line1: trading name
value:
currency: GBP
amount: 42
card-payment-delegate:
description: 'A one-off card payment using the Agentic Commerce Protocol to capture card details in a short lived delegate token.
'
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: delegate
sessionHref: https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
narrative:
line1: trading name
value:
currency: GBP
amount: 42
'400':
value:
errorName: bodyDoesNotMatchSchema
message: A JSON body matching the expected schema must be provided.
validationErrors:
- errorName: fieldIsNotAllowed
message: Field at path is not allowed.
jsonPath: $.instruction.paymentInstrument.narrative
google-pay-decrypted-cryptogram-3ds:
description: Provide the decrypted CRYPTOGRAM_3DS Google Pay payload
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: googlepay
paymentInstrument:
type: decrypted
number: '4444333322221111'
cryptogram: MAAAAAAAAAAAAAAAAAAAAAAAAAB=
eci: '07'
expiryDate:
month: 5
year: 2035
narrative:
line1: trading name
value:
currency: GBP
amount: 42
'415':
value:
errorName: headerHasInvalidValue
message: A valid header must be provided.
headerName: Content-Type
google-pay-encrypted:
description: Provide the encrypted Google Pay payload
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: googlepay
paymentInstrument:
type: encrypted
walletToken: '{"protocolVersion":"ECv1","signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d","signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\u003d\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\u003d\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"}'
threeDS:
type: integrated
mode: always
exemptionOnOutage: true
deviceData:
acceptHeader: text/html
userAgentHeader: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)
browserLanguage: en-GB
browserScreenWidth: 900
browserScreenHeight: 1200
browserJavaEnabled: true
browserColorDepth: '32'
timeZone: '300'
browserJavascriptEnabled: true
channel: browser
challenge:
returnUrl: http://payment.example.com
narrative:
line1: trading name
value:
currency: GBP
amount: 42
use-stored-card-token-tokenId-namespace:
description: Use a previously stored Worldpay token for a customer initiated payment (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
cvc: '333'
tokenId: '9902480679618049603'
namespace: SHOPPER_ID_1234567890
customerAgreement:
type: cardOnFile
storedCardUsage: subsequent
narrative:
line1: trading name
value:
currency: GBP
amount: 42
subsequent-recurring-installment-merchant:
description: Set up a recurring subscription payment (first). This is a customer initiated transaction (CIT)
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: card
paymentInstrument:
type: token
href: https://try.access.developer.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ
customerAgreement:
type: installment
installmentType: merchant
storedCardUsage: subsequent
schemeReference: MCCOLXT1C0104
narrative:
line1: trading name
value:
currency: GBP
amount: 42
3ds-device-data-required-201:
description: If 3DS is enabled the issuers [device data collection](/products/payments/enable-features/3ds-authentication) must be run on the customer's browser
value:
transactionReference: Memory265-13/08/1876
outcome: 3dsDeviceDataRequired
deviceDataCollection:
jwt: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJpc3MiOiI2NjAzMDA3YTE2ZGQ5YTdlNmEwMzM0MDciLCJleHAiOjE3MTIyNDg3MTIsImlhdCI6MTcxMjI0ODExMiwianRpIjoiZjdjZGVhZWUtMTY4MS00NjlhLTgxZmEtMzBkY2MyOTYzODA3In0.T1a6hOCPVVsQmcCKU3eczwmxlHoWK83tUqIJ_VG4fwc
url: https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
bin: '400000'
_actions:
supply3dsDeviceData:
href: https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiR0ZSM3R2Z1d4OTI5SEdSVlVaWlk0cllQV3p4TU5raU85Y0ZwSkd2b09FWGo0SnVHYXI0MzJqZlM4RHp5UnRaaiJ9/3dsDeviceData
method: POST
sent-for-settlement-202-full:
description: "Example of a sentForSettlement response. [Auto settlement](/products/payments/enable-features/auto-settlement) was enabled in the payment request. \n\nIncludes response information for: \n - [fraud assessment](/products/payments/enable-features/fraud-assessment) \n - [Worldpay Token creation](/products/payments/store-a-card)\n - [SCA Exemption](/products/payments/enable-features/sca-exemptions)\n - [Revenue Boost](/products/payments/openapi/payment/payment#payment/payment/t=response&c=202&path=&d=0/updatedpaymentinstrument)\n - [Partial Authorization](/products/payments/openapi/payment/payment#payment/payment/t=request&path=instruction&d=0/value/acceptpartialamount)\n"
value:
outcome: sentForSettlement
paymentId: payI-dUcet9fk4_X4qZU0hpU0
transactionReference: Memory265-13/08/1876
schemeReference: '060720116005060'
issuer:
authorizationCode: '675725'
riskFactors:
- risk: notChecked
type: cvc
- risk: notChecked
detail: address
type: avs
- risk: notChecked
detail: postcode
type: avs
fraud:
outcome: lowRisk
score: 44.6
token:
href: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiRVl3SDBtNnpEVmVTR3UzRUV3VEJEVDExTkxuVDVydXNiREdLR01hUXUwVT0ifQ
tokenId: '9968110159504301628'
tokenExpiryDateTime: '2024-04-11T15:59:23Z'
cardNumber: 4000********1000
cardHolderName: test
cardExpiry:
year: 2035
month: 5
bin: '400000'
fundingType: debit
schemeReference: '060720116005060'
conflicts:
conflictsExpiryDateTime: '2024-07-04T06:40:32.310316518Z'
paymentInstrument:
cardHolderName: John Snow
paymentInstrument:
type: card/plain+masked
cardBin: '400000'
lastFour: '1000'
countryCode: GB
expiryDate:
year: 2035
month: 5
cardBrand: mastercard
fundingType: debit
category: consumer
issuerName: BANK LIMITED
paymentAccountReference: 3001DBT34Q41D6J7PFC5W0UACOT4C
updatedPaymentInstrument:
appliedNetworkToken: true
amounts:
requested: 1000
totalAuthorized: 700
currency: GBP
partialAuthorization: true
_links:
self:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D
_actions:
refundPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D/refunds
method: POST
partiallyRefundPayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmUCGmlXGGNqJmZcIdZa%3Aufi8N9Y8uwrkGtx1suHsSFnXn2PMsm%3AcRBXHzZt3giUlFW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ2hKYh1GAhFAwfPvBamw%3AisDwI2AuXQ9KT%3AMt9SY%3AfYERqcZ58SBNT3Gkwn1j%2Bkd7LZ%3AVhRHFzbbwymcuTiRbNw%3D/partialRefunds
method: POST
reversePayment:
href: https://try.access.worldpay.com/api/payments/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ%3D%3D.sN%3Ag8wd64bwkbrp0md%2BbPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y%3A7njc4649JSrU7%2BvFDl1J36%2BcwOkX0lW4Z%2BfnZKMutoUGX3m1%3AmZ%2BxHZ9nDpadu%2BBh7pRyJwnWeiSFTlqKvbrBxNm3HV0xann55pFjZ7qi4DNGZtx9zW6eOLVNOsPL6ecsn3Dp377s7pWRQKSZJKSFIJvAisP8cBzFPzqireuqfCu5ojcm60gRSsqS3glurO24RJkg5SrpRjgY6g7ca8uoA7tKDk9OVOIwORF5sGPHSSGMa2bEl2lMUkAANoWclQHiGzxWQQ%3AAwSoo6RsrBugbhEp0K8HxZkfVrqy4oVlW8FdQ7kIuZOH78i6pPLzArc%2BOtMdnU%3ArZ%3AVhRHFzbbwymcuTiRbNw%3D/partialSettlements
method: POST
apple-pay-decrypted:
description: Provide the decrypted Apple Pay payload
value:
transactionReference: Memory265-13/08/1876
orderReference: order-12345
merchant:
entity: default
instruction:
method: applepay
paymentInstrument:
type: decrypted
number: '4444333322221111'
cryptogram: MAAAAAAAAAAAAAAAAAAAAAAAAAB=
eci: '07'
expiryDate:
month: 5
year: 2035
narrative:
line1: trading name
value:
currency: GBP
amount: 42
schemas:
Custom:
type: object
properties:
number1:
type: integer
format: int32
number2:
type: integer
format: int32
number3:
type: integer
format: int32
number4:
type: integer
format: int32
number5:
type: integer
format: int32
number6:
type: integer
format: int32
number7:
type: integer
format: int32
number8:
type: integer
format: int32
number9:
type: integer
format: int32
string1:
type: string
maxLength: 100
minLength: 1
string2:
type: string
maxLength: 100
minLength: 1
string3:
type: string
maxLength: 100
minLength: 1
string4:
type: string
maxLength: 100
minLength: 1
string5:
type: string
maxLength: 100
minLength: 1
string6:
type: string
maxLength: 100
minLength: 1
string7:
type: string
maxLength: 100
minLength: 1
string8:
type: string
maxLength: 100
minLength: 1
string9:
type: string
maxLength: 100
minLength: 1
Narrative:
type: object
description: The text that appears on your customer's statement. Used to identify the merchant.
properties:
line1:
type: string
description: line1 is used to provide basic details about the merchant.
maxLength: 24
minLength: 1
pattern: ^[a-zA-Z0-9 ,./-]*$
line2:
type: string
description: ' line2 is used for additional context about the payment or merchant. E.g. Order number or Merchant phone number. '
maxLength: 24
minLength: 1
pattern: ^[a-zA-Z0-9 ,./-]*$
required:
- line1
ValidationErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
jsonPath:
type: string
validationErrors:
type: array
items:
$ref: '#/components/schemas/ValidationErrorResponse'
PaymentsCardPlainPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- plain
cardNumber:
type: string
description: Customer's card number.
example: '4000000000001091'
maxLength: 19
minLength: 12
pattern: ^[0-9]+$
cardHolderName:
type: string
description: '
The name on your customer''s card. Required if instruction.tokenCreation is present. However we recommend that you supply this to improve authentication rates.'
example: Sherlock Holmes
maxLength: 255
minLength: 1
expiryDate:
$ref: '#/components/schemas/ExpiryDate'
cvc:
type: string
description: '
CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.'
example: '123'
maxLength: 4
minLength: 3
pattern: '[0-9]*$'
billingAddress:
$ref: '#/components/schemas/PaymentsBillingAddress'
routing:
$ref: '#/components/schemas/Routing'
required:
- cardNumber
- expiryDate
- type
PaymentsFraud:
type: object
description: 'Fraud assessment to detect potential fraud and prevent the transaction from proceeding.
Read more on how to set it up under our [__Fraud Assessment__](/products/payments/enable-features/fraud-assessment) guide.'
properties:
type:
type: string
default: fraudSight
description: Enable a FraudSight risk assessment
enum:
- fraudSight
silentMode:
type: boolean
default: false
description: "Perform the Fraud assessment but do not act on the outcome.\n Normally used for the initial launch while the data model is maturing."
tmxSessionId:
type: string
description: Device fingerprint provided by Threatmetrix.
maxLength: 128
minLength: 30
pattern: ^[A-Za-z0-9_-]*$
custom:
$ref: '#/components/schemas/Custom'
description: Additional values specific to your order that can be used to create manual fraud rules.
required:
- type
AccountHistory:
type: object
properties:
createdAt:
type: string
description: Date the customer account was created.
modifiedAt:
type: string
description: Date the customer account was last modified.
passwordModifiedAt:
type: string
description: Date the password for the customer account was last modified.
paymentAccountEnrolledAt:
type: string
description: Date the payment account was added to the cardholder account.
PaymentsUnscheduledCustomerAgreement:
allOf:
- $ref: '#/components/schemas/PaymentsCustomerAgreement'
- type: object
properties:
type:
type: string
enum:
- unscheduled
schemeReference:
type: string
description: Unique reference provided by card schemes used to link the `first` and `subsequent` payments. This value is bundled with the Worldpay token if created as part of the `first` payment and therefore not required here as well. If you manage multiple agreements for a single cardholder using a token, please use the `schemeReference` returned to you. This allows you to distinguish and manage each separate agreement appropriately.
example: MCCOLXT1C0104
maxLength: 56
minLength: 1
pattern: ^[A-Za-z0-9]*$
required:
- type
PaymentsSubMerchant:
type: object
properties:
name:
type: string
description: The name of your subMerchant's company.
Also used for __3DS authentication__ to display the merchant name during the authentication process.
example: Merchant Plc
maxLength: 25
minLength: 1
pattern: ^(?!\s*$)[A-Za-z0-9 ]*$
reference:
type: string
description: Unique merchant reference.
example: '123456789012345'
maxLength: 15
minLength: 1
pattern: '[a-zA-Z0-9]*$'
address:
$ref: '#/components/schemas/PaymentsSubMerchantAddress'
description: Contains the subMerchant address information.
phoneNumber:
type: string
description: Phone number of your subMerchant's company.
example: 987-65-4321
maxLength: 20
minLength: 4
pattern: ^(?!\s*$)[0-9\s()+\-/.x]*$
taxReference:
type: string
description: Tax Reference of your subMerchant's company.
example: 987-65-4321
maxLength: 20
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s-]*$
email:
type: string
description: Email address of your subMerchant's company.
example: email@example.com
maxLength: 40
minLength: 1
pattern: ^.+@.+$
url:
type: string
example: url.example.com
maxLength: 255
minLength: 1
pattern: ^[a-zA-Z0-9@!£*#$)(+\-_=.,/;:]*$
required:
- address
- name
- reference
PaymentsExternalThreeDS:
allOf:
- $ref: '#/components/schemas/PaymentsThreeDS'
- type: object
properties:
type:
type: string
description: ThreeDS type.
enum:
- external
version:
type: string
description: 3DS version used to process the transaction.
example: 2.2.0
maxLength: 5
minLength: 5
pattern: ^2[.][0-9][.][0-9]$
eci:
type: string
description: " Electronic Commerce Indicator (ECI). Required for all card brands except Cartes Bancaires.\n\n | ECI | Meaning | \n |---|---| \n | 02 or 05 | Fully authenticated transaction | \n | 01 or 06 | Attempted authentication transaction | \n | 00 or 07 | Non 3-D Secure transaction | \n\n | Scheme | Value | \n |---|---| \n | Mastercard | 02, 01, 00 |\n | Visa | 05, 06, 07 |\n | Amex | 05, 06, 07 | \n | JCB | 05, 06, 07 |\n | Diners | 05, 06, 07 |\n"
enum:
- '00'
- '01'
- '02'
- '05'
- '06'
- '07'
authenticationValue:
type: string
description: Required if `eci` value is 01, 02, 05 or 06. A cryptographic value that provides evidence of the outcome of a 3DS verification.
example: kBNHXUAy4+HT1gAMBSDajheBcxQh
maxLength: 29
minLength: 1
pattern: ^[a-zA-Z0-9+/]+={0,2}$
dsTransactionId:
type: string
format: RFC 4122 UUID
description: Required if 'eci' value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer.
example: b8fb4ecc-7e2e-4b1c-816d-0149849776b8
cryptogramAlgorithm:
type: string
description: Indicates the algorithm used to generate the cryptogram. For Cartes Bancaires authorizations only.
example: '2'
maxLength: 1
minLength: 1
pattern: ^[a-zA-Z0-9]$
challengePreference:
type: string
description: Indicates the preferred challenge behavior. For Cartes Bancaires authorizations only.
enum:
- noPreference
- noChallengeRequested
- challengeRequested
- challengeMandated
- noChallengeRequestedTRAPerformed
authenticationFlow:
type: string
description: 'Set to challenge if your customer was redirected to their bank to complete authentication, or frictionless if your customer completed authentication without needing to be redirected to their bank. For Cartes Bancaires authorizations only.
'
enum:
- challenge
- frictionless
- frictionlessDelegated
networkScore:
type: string
description: The global score calculated by the Cartes Bancaires scoring platform. For Cartes Bancaires authorizations only.
maxLength: 2
minLength: 1
pattern: ^[0-9]+$
brand:
type: string
description: The card brand used in the authentication. For Cartes Bancaires authorizations only.
enum:
- cartesBancaires
description: 'An object containing 3DS authentication preferences.
Read more on how to set it up under our [__3DS Authentication__](/products/payments/enable-features/3ds-authentication) guide.'
required:
- type
- version
PaymentsDecryptedPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- decrypted
number:
type: string
maxLength: 19
minLength: 12
pattern: ^\d+$
cryptogram:
type: string
example: BLIYQ4EA/wLF4/hK9ABFMAABAAA=
maxLength: 40
minLength: 1
eci:
type: string
description: Electronic Commerce Indicator.
pattern: ^\d{2}$
expiryDate:
$ref: '#/components/schemas/ExpiryDate'
billingAddress:
$ref: '#/components/schemas/PaymentsBillingAddress'
required:
- expiryDate
- number
- type
PaymentsSubscriptionCustomerAgreement:
allOf:
- $ref: '#/components/schemas/PaymentsCustomerAgreement'
- type: object
properties:
type:
type: string
enum:
- subscription
storedCardUsage:
type: string
description: ' Set to `first` to store a card or `subsequent` to use a previously stored card. '
enum:
- first
- subsequent
schemeReference:
type: string
description: Optional field available only for `subsequent` storedCardUsage. Unique reference provided by card schemes used to link the `first` and `subsequent` payments. If a Worldpay token was created as part of the first payment, this value is bundled with the token and does not need to be provided again. If you manage multiple agreements for a single cardholder using a token, please use the `schemeReference` returned to you. This allows you to distinguish and manage each separate agreement appropriately.
example: MCCOLXT1C0104
maxLength: 56
minLength: 1
pattern: ^[A-Za-z0-9]*$
required:
- storedCardUsage
- type
PaymentsCustomerAgreement:
type: object
description: ' Contains specific customer agreements for the transaction. '
discriminator:
propertyName: type
mapping:
cardOnFile: '#/components/schemas/PaymentsCardOnFileCustomerAgreement'
subscription: '#/components/schemas/PaymentsSubscriptionCustomerAgreement'
installment: '#/components/schemas/PaymentsInstallmentCustomerAgreement'
unscheduled: '#/components/schemas/PaymentsUnscheduledCustomerAgreement'
properties:
type:
type: string
description: The processing arrangement agreed with your customer.
required:
- type
PaymentsIntegratedThreeDS:
allOf:
- $ref: '#/components/schemas/PaymentsThreeDS'
- type: object
properties:
type:
type: string
description: ThreeDS type.
enum:
- integrated
mode:
type: string
enum:
- always
challenge:
$ref: '#/components/schemas/Challenge'
description: An object containing 3DS challenge preferences and configuration.
deviceData:
$ref: '#/components/schemas/DeviceData'
description: An object containing device data for 3DS & Fraud assessment.
previousSuspiciousActivity:
type: boolean
description: Has the account been flagged for suspicious activity.
userType:
type: string
enum:
- guestUser
- registeredUser
- federatedAccount
- issuerCredentials
- thirdPartyAuthentication
- fidoAuthenticator
accountHistory:
$ref: '#/components/schemas/AccountHistory'
description: Customer account history.
reorder:
type: boolean
description: Repeat of a previous order.
preOrderDate:
type: string
description: Expected date that a pre-ordered purchase will be available.
transactionHistory:
$ref: '#/components/schemas/TransactionHistory'
description: Object containing details of the last transaction.
giftCardsPurchase:
$ref: '#/components/schemas/PaymentsGiftCardsPurchase'
description: If the order is being used to purchase a gift card.
exemptionOnOutage:
type: boolean
description: '"Attempt authorization (without liability shift) using an authentication outage exemption in the event of a 3DS network failure. Even with this boolean set they are not currently part of default merchant setup. See [how to enable authentication outage exemptions](/products/payments/enable-features/3ds-authentication#how-to-enable-authentication-outage-exemptions)" '
description: 'An object containing 3DS authentication preferences.
Read more on how to set it up under our [__3DS Authentication__](/products/payments/enable-features/3ds-authentication) guide.'
required:
- challenge
- deviceData
- mode
- type
TransactionHistory:
type: object
properties:
attemptsLastDay:
type: integer
format: int32
description: ' Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours. '
attemptsLastYear:
type: integer
format: int32
description: ' Number of transactions (successful or abandoned) for this cardholder account within the last year. '
completedLastSixMonths:
type: integer
format: int32
description: ' Number of purchases with this customer account during the previous six months. '
addCardsLastDay:
type: integer
format: int32
description: Number of attempts to add a card in the last 24hrs.
shippingAddressFirstUsedAt:
type: string
description: ' When the shipping address used for the transaction was first used. '
PaymentRequest:
properties:
transactionReference:
type: string
description: ' A unique reference generated by you that is used to identify a payment throughout its lifecycle. '
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
orderReference:
type: string
description: 'A reference that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments, for example where:
- the total amount for a single order is split across multiple payments
- you use a single reference for each payment in a recurring agreement or split shipment scenario'
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~/+]*$
merchant:
$ref: '#/components/schemas/Merchant'
instruction:
$ref: '#/components/schemas/PaymentsInstruction'
channel:
type: string
description: 'Interaction between the cardholder and you. Supply a value of `ecom` to process an eCommerce authorization. Supply a value of `moto` to process an authorization as a [__Mail Order or Telephone Order__](/products/payments/enable-features/moto) transaction.
__Note: 3DS authentication cannot be supplied for MOTO payments__.'
enum:
- ecom
- moto
required:
- instruction
- merchant
- transactionReference
TokenCreation:
type: object
description: 'Use this object if you want to create a token after the payment. Can only be used with paymentInstrument.type: card/plain & checkout.'
properties:
type:
type: string
enum:
- worldpay
namespace:
type: string
description: ' A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace. '
maxLength: 64
minLength: 1
pattern: ^[^_][^ &<]*$
description:
type: string
description: ' A description of your token. If not supplied, a default description is created for you. '
maxLength: 255
minLength: 1
pattern: ^[^&<]*$
required:
- type
Customer:
type: object
properties:
customerId:
type: string
description: 'Unique identifier used by the ecommerce system for the customer.
__Used for:__ Risk assessment'
maxLength: 128
minLength: 1
firstName:
type: string
description: 'Customer''s first name.
__Used for:__ 3DS authentication | Risk assessment'
maxLength: 22
minLength: 1
lastName:
type: string
description: 'Customer''s last name.
__Used for:__ 3DS authentication | Risk assessment'
maxLength: 22
minLength: 1
phone:
type: string
description: 'Customer''s phone number.
__Used for:__ 3DS authentication | Risk assessment | Card authorization'
maxLength: 20
minLength: 4
pattern: ^[0-9]*$
dateOfBirth:
type: string
format: date
description: 'Customer''s date of birth.
__Used for:__ Risk assessment'
email:
type: string
description: 'Customers''s email address used for the ecommerce account.
__Used for:__ 3DS authentication | Risk assessment | Card authorization'
maxLength: 128
minLength: 1
pattern: ^.+@.+$
ipAddress:
type: string
description: ' A unique identifier for your customer''s physical location that can be used by the issuer in risk analysis. Must be in IPv4 or IPv6 format. E.g. 192.0.0.0.
__Used for:__ 3DS authentication | Risk assessment | Card authorization'
documentReference:
type: string
description: Required for domestic processing in some Latin American countries.
maxLength: 50
minLength: 1
pattern: ^[-A-Za-z0-9_\-/\\*~+.,&()]*$
PaymentsResponse201:
type: object
discriminator:
propertyName: outcome
mapping:
authorized: '#/components/schemas/CardAuthorizedPaymentResponse'
refused: '#/components/schemas/PaymentRefusedResponse'
fraudHighRisk: '#/components/schemas/FraudHighRiskResponse'
3dsDeviceDataRequired: '#/components/schemas/DeviceDataRequiredResponse'
properties:
outcome:
type: string
transactionReference:
type: string
description: ' A unique reference generated by you that is used to identify a payment throughout its lifecycle. '
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
PaymentsFundsSender:
type: object
description: An object containing details about the sender of funds, including name and address information. The sender account is always the card account declared within `instruction.paymentInstrument`. __Although an optional object in the API schema, `sender` is required for some regions and use cases.__
properties:
firstName:
type: string
description: Sender's first name. Must be supplied if `lastName` or `middleName` are provided.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
middleName:
type: string
description: Sender's middle name.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
lastName:
type: string
description: Sender's last name. Must be supplied if `firstName` or `middleName` are provided.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
address:
$ref: '#/components/schemas/PaymentsTransferAddress'
description: Sender's address.
dateOfBirth:
type: string
format: date
description: Sender's date of birth
documentReference:
type: string
description: Sender's document reference (e.g. Tax ID). Required for domestic processing in some Latin American countries.
maxLength: 25
minLength: 1
pattern: ^[-A-Za-z0-9_\-/\\*~+.,&()]*$
ExpiryDate:
type: object
description: Contains your customer's card or token expiry date.
properties:
year:
type: integer
format: int32
example: 2028
month:
type: integer
format: int32
example: 6
required:
- month
- year
Value:
type: object
description: The value and currency.
properties:
currency:
type: string
description: ' The three character currency code. See list of supported currencies '
example: USD
minLength: 1
amount:
type: integer
format: int32
description: 'The payment amount. Implied decimal. For example, 250 GBP = £2.50
When set to `0` will perform a card verification instead of a payment as part of a new `customerAgreement`.'
example: 250
acceptPartialAmount:
type: boolean
description: Set to `true` to accept a partial authorization amount. You can charge the remainder of the amount using a different payment credential with a new authorization request.
required:
- amount
- currency
ErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
PaymentsNetworkTokenPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- networkToken
tokenNumber:
type: string
description: The network token number.
maxLength: 19
minLength: 12
pattern: '[0-9]*$'
cardHolderName:
type: string
description: The name as shown on the card.
maxLength: 255
minLength: 1
cryptogram:
type: string
description: The single-use cryptogram provisioned for this payment. Required for all Customer Initiated Transactions (CITs).
__Note:__ If the `cryptogram` and `eci` are not provided, the Payments API will __automatically__ attempt to provision them. This will only be successful for Network Tokens created via Worldpay. For Network Tokens created via other gateways you must provide these.
maxLength: 40
minLength: 1
eci:
type: string
description: Electronic Commerce Indicator.
pattern: ^\d{2}$
expiryDate:
$ref: '#/components/schemas/ExpiryDate'
billingAddress:
$ref: '#/components/schemas/PaymentsBillingAddress'
required:
- expiryDate
- tokenNumber
- type
PaymentsTransferAddress:
type: object
properties:
address1:
type: string
description: Must be supplied if `city` is provided.
maxLength: 80
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
address2:
type: string
maxLength: 80
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
city:
type: string
description: Must be supplied if `address1` is provided.
maxLength: 50
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
postalCode:
type: string
maxLength: 10
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
state:
type: string
description: 1-3 alphanumeric characters and spaces.
maxLength: 3
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
countryCode:
type: string
format: ISO 3166-1 alpha-2
description: Country code in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
minLength: 1
required:
- countryCode
PaymentsRecipientAccount:
type: object
discriminator:
propertyName: type
mapping:
bankAccount: '#/components/schemas/PaymentsBankAccount'
card: '#/components/schemas/PaymentsCardAccount'
wallet: '#/components/schemas/PaymentsWalletAccount'
storedValueWallet: '#/components/schemas/PaymentsWalletAccount'
stagedDigitalWallet: '#/components/schemas/PaymentsWalletAccount'
merchantWallet: '#/components/schemas/PaymentsWalletAccount'
email: '#/components/schemas/PaymentsEmailAccount'
phone: '#/components/schemas/PaymentsPhoneAccount'
socialNetwork: '#/components/schemas/PaymentsSocialNetworkAccount'
properties:
type:
type: string
description: The type of account.
required:
- type
Shipping:
type: object
description: 'Object containing all data related to how the order will be shipped.
__Used for:__ 3DS Authentication | Risk assessment'
properties:
method:
type: string
description: The shipping method used.
enum:
- billingAddress
- verifiedAddress
- otherAddress
- store
- digital
- unshippedTickets
- other
timeFrame:
type: string
enum:
- electronic
- sameDay
- nextDay
- twoDaysPlus
email:
type: string
description: The email address used for an electronic delivery.
maxLength: 128
minLength: 1
pattern: ^.+@.+$
phone:
type: string
description: The phone number used for delivery.
maxLength: 20
minLength: 4
pattern: ^[0-9]*$
firstName:
type: string
description: First name used on the shipping address.
maxLength: 22
minLength: 1
lastName:
type: string
description: Last name used on the shipping address.
maxLength: 22
minLength: 1
address:
$ref: '#/components/schemas/PaymentsShippingAddress'
PaymentsInstruction:
type: object
description: An object that contains all information related to the payment and API configurations.
discriminator:
propertyName: method
mapping:
card: '#/components/schemas/PaymentsCardInstruction'
applepay: '#/components/schemas/PaymentsApplepayInstruction'
googlepay: '#/components/schemas/PaymentsGooglepayInstruction'
properties:
method:
type: string
paymentInstrument:
oneOf:
- $ref: '#/components/schemas/PaymentsCardPlainPaymentInstrument'
- $ref: '#/components/schemas/PaymentsDecryptedPaymentInstrument'
- $ref: '#/components/schemas/PaymentsEncryptedPaymentInstrument'
- $ref: '#/components/schemas/PaymentsNetworkTokenPaymentInstrument'
- $ref: '#/components/schemas/SessionPaymentInstrument'
- $ref: '#/components/schemas/SessionsDelegatePaymentInstrument'
- $ref: '#/components/schemas/TokenPaymentInstrument'
narrative:
$ref: '#/components/schemas/Narrative'
tokenCreation:
$ref: '#/components/schemas/TokenCreation'
value:
$ref: '#/components/schemas/Value'
debtRepayment:
type: boolean
description: A flag which identifies a payment as being for the purpose of repaying a debt.
fraud:
$ref: '#/components/schemas/PaymentsFraud'
threeDS:
oneOf:
- $ref: '#/components/schemas/PaymentsExternalThreeDS'
- $ref: '#/components/schemas/PaymentsIntegratedThreeDS'
exemption:
$ref: '#/components/schemas/Exemption'
settlement:
$ref: '#/components/schemas/Settlement'
customer:
$ref: '#/components/schemas/Customer'
shipping:
$ref: '#/components/schemas/Shipping'
customerAgreement:
oneOf:
- $ref: '#/components/schemas/PaymentsCardOnFileCustomerAgreement'
- $ref: '#/components/schemas/PaymentsInstallmentCustomerAgreement'
- $ref: '#/components/schemas/PaymentsSubscriptionCustomerAgreement'
- $ref: '#/components/schemas/PaymentsUnscheduledCustomerAgreement'
recipient:
$ref: '#/components/schemas/PaymentsRecipient'
consumerBillPayment:
type: boolean
description: An attribute that identifies a bill payment paid by providers on behalf of consumers. If you are registered with Visa as a Consumer of the Bill Payment Service (CBPS), you must set this to `true` for any payments associated with the CBPS.
fundsTransfer:
$ref: '#/components/schemas/PaymentsFundsTransfer'
required:
- method
- narrative
- paymentInstrument
- value
Merchant:
type: object
description: An object that contains information about the merchant.
properties:
entity:
type: string
description: ' Used to route the request in Access Worldpay, created as part of on-boarding. '
example: default
maxLength: 32
minLength: 1
pattern: ^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$
mcc:
type: string
description: ' You can apply a merchant category code (mcc) to an individual request. You can only provide an mcc if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, merchant.mcc defaults to a configured value. '
pattern: ^\d{4}$
paymentFacilitator:
$ref: '#/components/schemas/PaymentsPaymentFacilitator'
description: An object containing Payment Facilitator information. This information is required for every authorization [__only if you are a Payment Facilitator__](/products/payments/enable-features/payment-facilitator)
required:
- entity
PaymentsRecipient:
type: object
description: 'An object containing information about the recipient of financial services. Required for MCC 6012 transactions in the Visa Europe region. The recipient may or may not be the cardholder.
Read more on how to set it up under our [__Financial Services__](/products/payments/enable-features/financial-services-mcc6012-mcc6051) guide.'
properties:
accountReference:
type: string
description: The account number of the recipient. Either a bank account number or a partial card number.
maxLength: 10
minLength: 1
pattern: ^[A-Za-z0-9]*$
lastName:
type: string
description: The last name of the recipient.
maxLength: 22
minLength: 1
pattern: ^[A-Za-z@!£*#$)(+\-_=.,/;:'"]*$
address:
$ref: '#/components/schemas/PaymentsRecipientAddress'
dateOfBirth:
type: string
format: date
description: Recipient's date of birth.
PaymentsFundsTransfer:
type: object
description: 'Contains details of the funds transfer request, which is a money movement for a reason other than the purchase of goods or services (also known as Account Funding Transaction (AFT)).
Read more on how to set it up under our [__Account Funding Transactions__](/products/payments/enable-features/account-funding-transactions) guide.'
properties:
type:
type: string
description: Specifies the type of the funds transfer. {% admonition type="warning" name="Note" %} You may only submit the `fundsTransfer.type` values that relate to the use cases that you have been approved for by the schemes.{% /admonition %}
enum:
- accountToAccount
- cash
- disbursement
- personToPerson
- purchase
- topUp
- walletLoad
x-enumDescriptions:
disbursement: A card is used as the source of funds for a disbursement
personToPerson: Move funds to an account owned by another person (eg gifts)
accountToAccount: Move funds to another financial institution account owned by the same person
topUp: Top up a pre-paid or debit card
purchase: For the initial purchase of a reloadable account (such as prepaid or gift card), or direct crypto & liquid asset purchases without an intermediary wallet load
cash: A card is used to fund a transfer where funds are given to the recipient in cash
walletLoad: Move funds to a digital wallet owned by the same person
purpose:
type: string
description: Specifies the purpose of the funds transfer. Required for some regions and use cases (eg crypto).
enum:
- businessToBusiness
- creditCardRepayment
- crypto
- crowdLending
- debitCard
- education
- emergency
- familySupport
- gift
- giftCard
- gaming
- highRiskSecurities
- liquidAssets
- medical
- payroll
- prepaidCard
- salary
- savings
- travel
- other
recipient:
$ref: '#/components/schemas/PaymentsFundsRecipient'
sender:
$ref: '#/components/schemas/PaymentsFundsSender'
required:
- type
Challenge:
type: object
properties:
returnUrl:
type: string
description: ' Once the customer completes the challenge page the issuer redirects/posts to the returnUrl in order for you to resume the session. It must be the full URL path. '
minLength: 1
windowSize:
type: string
default: 390x400
description: ' Specify the challenge window size (width x height) that the issuer should use. This is to better tailor the experience to the customers device. Default is 390x400. '
enum:
- 250x400
- 390x400
- 600x400
- 500x600
- fullPage
preference:
type: string
description: ' Set a preference for how the Issuer decides on a 3DS challenge.'
enum:
- noPreference
- noChallengeRequested
- challengeRequested
- challengeMandated
- noChallengeRequestedTRAPerformed
required:
- returnUrl
Exemption:
type: object
description: "An object used to request or specify an SCA Exemption. \n\nRead more on how to set it up under our [__SCA Exemptions__](/products/payments/enable-features/sca-exemptions) guide."
properties:
type:
type: string
description: Ask for an SCA exemption recommendation directly from Worldpay (integrated) or use a 3rd party TRA solution.
__Note:__ Only type `integrated` is supported for now.
enum:
- integrated
mode:
type: string
description: Specify which transactions to request SCA Exemptions for.
enum:
- always
capability:
type: string
description: Indicates whether the exemption requested from Worldpay can return a placement of authorization (payment) and/or authentication (3DS).
enum:
- authorizationAndAuthentication
- authorizationOnly
- authenticationOnly
example: authenticationOnly
x-enumDescriptions:
authenticationOnly: The SCA Exemptions service can only return a `placement` of `authentication`.
authorizationOnly: The SCA Exemptions service can only return a `placement` of `authorization`.
authorizationAndAuthentication: The SCA Exemptions service can return either a `placement` of `authorization` or `authentication`.
request:
$ref: '#/components/schemas/PaymentsExemptionRequest'
required:
- capability
- mode
- type
SessionsDelegatePaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- delegate
sessionHref:
type: string
description: '
An http address that contains your Delegate token providing the card details.'
required:
- sessionHref
- type
InstallmentPlan:
type: object
properties:
numberOfInstallments:
type: integer
format: int32
description: Number of installments that the requested amount should be broken into.
required:
- numberOfInstallments
Routing:
type: object
description: An object containing specific routing preferences.
properties:
preferredCardBrand:
type: string
description: Specifies your customer's preferred card brand to be used for the transaction using a co-badged card.
enum:
- visa
- mastercard
- maestro
- amex
- cartesBancaires
- diners
- dankort
- jcb
- discover
- elo
- eftposAU
PaymentsEncryptedPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
description: The type of instrument.
enum:
- encrypted
walletToken:
type: string
minLength: 1
billingAddress:
$ref: '#/components/schemas/PaymentsBillingAddress'
required:
- type
- walletToken
PaymentsCardOnFileCustomerAgreement:
allOf:
- $ref: '#/components/schemas/PaymentsCustomerAgreement'
- type: object
properties:
type:
type: string
enum:
- cardOnFile
storedCardUsage:
type: string
description: ' Set to `first` to store a card or `subsequent` to use a previously stored card. '
enum:
- first
- subsequent
required:
- storedCardUsage
- type
PaymentsGiftCardsPurchase:
type: object
properties:
totalValue:
$ref: '#/components/schemas/Value'
description: The value and currency.
quantity:
type: integer
format: int32
description: The number of gift cards being purchased.
SessionPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- checkout
sessionHref:
type: string
description: '
An http address that contains your Checkout session providing the card details.'
cardHolderName:
type: string
description: '
The name on your customer''s card. Required if instruction.tokenCreation is present. However we recommend that you supply this to improve authentication rates.'
example: Sherlock Holmes
maxLength: 255
minLength: 1
billingAddress:
$ref: '#/components/schemas/PaymentsBillingAddress'
routing:
$ref: '#/components/schemas/Routing'
required:
- sessionHref
- type
Settlement:
type: object
description: 'Automatically settle a payment following authorization. If any of the AVS/CVC response riskFactors are marked as `notMatched` the payment will be `sentForCancellation` automatically.
Read more on how to set it up under our [__Auto Settlement__](/products/payments/enable-features/auto-settlement) guide.'
properties:
auto:
type: boolean
cancelOn:
$ref: '#/components/schemas/Cancellation'
description: Configuration for when a payment is `sentForCancellation` automatically.
required:
- auto
PaymentsInstallmentCustomerAgreement:
allOf:
- $ref: '#/components/schemas/PaymentsCustomerAgreement'
- type: object
properties:
type:
type: string
enum:
- installment
storedCardUsage:
type: string
description: ' Set to `first` to store a card or `subsequent` to use a previously stored card. Mandatory for `merchant` installment type. '
enum:
- first
- subsequent
installmentType:
type: string
description: " Defines the type of installments service. \n\nRead more on how to set up [__Latin America Installments__](/products/payments/enable-features/latam-installments) under our guide."
enum:
- merchant
- latinAmerica
installmentPlan:
$ref: '#/components/schemas/InstallmentPlan'
description: Required only for `latinAmerica` installment type. Not allowed for `merchant` installment type.
schemeReference:
type: string
description: Optional field available only for `subsequent` storedCardUsage. Unique reference provided by card schemes used to link the `first` and `subsequent` payments. If a Worldpay token was created as part of the first payment, this value is bundled with the token and does not need to be provided again. If you manage multiple agreements for a single cardholder using a token,please use the `schemeReference` returned to you. This allows you to distinguish and manage each separate agreement appropriately.
example: MCCOLXT1C0104
maxLength: 56
minLength: 1
pattern: ^[A-Za-z0-9]*$
required:
- installmentType
- type
PaymentsSubMerchantAddress:
type: object
properties:
postalCode:
type: string
description: Post code/Zip code of your subMerchant's company.
example: SW1 1AA
maxLength: 10
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
street:
type: string
description: Street name of your subMerchant's company.
example: 221B Baker Street
maxLength: 50
minLength: 1
pattern: ^(?!\s*$)[A-Za-z0-9\s]*$
city:
type: string
description: City of your subMerchant's company.
example: London
maxLength: 13
minLength: 1
pattern: ^(?!\s*$)[A-Za-z\s-]*$
state:
type: string
description: State of your subMerchant's company.
example: GB
maxLength: 3
minLength: 1
pattern: ^(?!\s*$)[a-zA-Z0-9\s]*$
countryCode:
type: string
description: Country code of your subMerchant's company in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
example: GB
maxLength: 2
minLength: 2
required:
- city
- countryCode
- postalCode
- street
HeaderErrorResponse:
type: object
properties:
errorName:
type: string
message:
type: string
headerName:
type: string
PaymentsFundsRecipient:
description: An object containing details about the recipient of funds, including name and address information, as well as recipient account details. In many use cases, the recipient is the same person as the sender (for example if your customer uses their card to load funds into their own crypto exchange or investment account). __Although an optional object in the API schema, `recipient` is required for some regions and use cases.__
properties:
account:
$ref: '#/components/schemas/PaymentsRecipientAccount'
firstName:
type: string
description: Recipient's first name.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
middleName:
type: string
description: Recipient's middle name.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
lastName:
type: string
description: Recipient's last name.
maxLength: 22
minLength: 1
pattern: ^(?!\s*$).*$
address:
$ref: '#/components/schemas/PaymentsTransferAddress'
dateOfBirth:
type: string
format: date
description: Recipient's date of birth
phoneNumber:
type: string
description: Recipient's phone number
maxLength: 20
minLength: 4
pattern: ^(?!\s*$)[0-9\s()+\-/.x]*$
documentReference:
type: string
description: Required for domestic processing in some Latin American countries.
maxLength: 25
minLength: 1
pattern: ^[-A-Za-z0-9_\-/\\*~+.,&()]*$
PaymentsRecipientAddress:
type: object
properties:
postalCode:
type: string
description: The postal code of the recipient. Relevant only in the UK.
maxLength: 10
minLength: 1
pattern: ^[A-Za-z0-9 ]*$
PaymentsThreeDS:
type: object
description: 'An object containing 3DS authentication preferences.
Read more on how to set it up under our [__3DS Authentication__](/products/payments/enable-features/3ds-authentication) guide.'
discriminator:
propertyName: type
mapping:
integrated: '#/components/schemas/PaymentsIntegratedThreeDS'
external: '#/components/schemas/PaymentsExternalThreeDS'
properties:
type:
type: string
required:
- type
PaymentsExemptionRequest:
type: object
properties:
placement:
type: string
default: optimized
description: Defines where the exemption is being requested.
enum:
- optimized
- authorization
- authentication
x-enumDescriptions:
authorization: A request for an exemption placed within the authorization.
optimized: We select the best performing placement based on its data.
authentication: A request for an exemption placed within the authentication (3DS).
type:
type: string
default: optimized
description: Defines which type of exemption is being requested.
enum:
- optimized
- lowValue
- lowRisk
x-enumDescriptions:
lowValue: An exemption for an authorization that is under €30.
optimized: We select the best performing type based on its data.
lowRisk: An exemption for an authorization that has been through Transaction Risk Analysis (TRA).
PaymentsBillingAddress:
type: object
description: Contains the billing address information.
properties:
address1:
type: string
description: Address line 1
maxLength: 80
minLength: 1
address2:
type: string
description: Address line 2
maxLength: 80
minLength: 1
address3:
type: string
description: Address line 3
maxLength: 80
minLength: 1
postalCode:
type: string
description: 'Required for all countries except the following: IE'
maxLength: 15
minLength: 1
city:
type: string
description: Address city
maxLength: 50
minLength: 1
state:
type: string
description: Address state
maxLength: 30
minLength: 1
countryCode:
type: string
format: ISO 3166-1 alpha-2
description: Must be provided in [ISO 3166-1 alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
minLength: 1
required:
- address1
- city
- countryCode
PaymentsPaymentFacilitator:
type: object
properties:
schemeId:
type: string
description: Your payment facilitator ID received from Mastercard, Visa and Amex.
example: '12345678901'
maxLength: 11
minLength: 1
pattern: '[0-9]*$'
independentSalesOrganizationId:
type: string
description: Independent Sales Organization (ISO) ID provided by Mastercard.
example: '12345678901'
maxLength: 11
minLength: 1
pattern: '[0-9]*$'
subMerchant:
$ref: '#/components/schemas/PaymentsSubMerchant'
description: Your sub-merchant's details.
required:
- schemeId
- subMerchant
PaymentsResponse202:
type: object
discriminator:
propertyName: outcome
mapping:
sentForSettlement: '#/components/schemas/SentForSettlementResponse'
sentForCancellation: '#/components/schemas/SentForCancellationResponse'
properties:
outcome:
type: string
transactionReference:
type: string
description: ' A unique reference generated by you that is used to identify a payment throughout its lifecycle. '
maxLength: 64
minLength: 1
pattern: ^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$
Cancellation:
type: object
properties:
cvcNotMatched:
type: string
description: By default a payment will be `sentForCancellation` if the CVC is `notMatched`, set `disabled` to continue with `sentForSettlement`.
enum:
- enabled
- disabled
avsNotMatched:
type: string
description: By default a payment will be `sentForCancellation` if the `address` or `postcode` AVS is `notMatched`, set `disabled` to continue with `sentForSettlement`.
enum:
- enabled
- disabled
DeviceData:
type: object
properties:
acceptHeader:
type: string
description: ' Used by the issuer to check if the customer''s browser is compatible with the issuer 3DS challenge display. '
maxLength: 2048
minLength: 1
userAgentHeader:
type: string
description: ' Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321. '
maxLength: 2048
minLength: 1
browserLanguage:
type: string
description: ' Your customer''s browser language that can be used by the issuer in risk analysis. Must conform to the language tags defined by IETF. E.g. en-GB, fr-FR. '
maxLength: 8
minLength: 1
browserJavaEnabled:
type: boolean
description: Defines whether Java is enabled on your customers browser.
browserColorDepth:
type: string
description: The color depth of your customers browser
enum:
- '1'
- '4'
- '8'
- '15'
- '16'
- '24'
- '32'
- '48'
browserScreenHeight:
type: integer
format: int32
description: Defines the pixel height of the customers browser.
browserScreenWidth:
type: integer
format: int32
description: Defines the pixel width of the customers browser.
timeZone:
type: string
description: " Time zone offset in minutes between UTC and your customer's browser local time. \nExample time zone offset values in minutes: \nIf UTC -5 hours: \n`300` \n`+300` \nIf UTC +5 hours: \n`-300` \n "
pattern: ^[+-]?\d{1,4}$
browserJavascriptEnabled:
type: boolean
description: Defines whether Javascript is enabled on your customers browser.
channel:
type: string
description: Determines the channel that the transaction came through. `native` should only be set if using the Cardinal 3DS SDK (iOS/Android)
enum:
- browser
- native
required:
- acceptHeader
- userAgentHeader
PaymentsShippingAddress:
type: object
properties:
address1:
type: string
description: Address line 1
maxLength: 80
minLength: 1
address2:
type: string
description: Address line 2
maxLength: 80
minLength: 1
address3:
type: string
description: Address line 3
maxLength: 80
minLength: 1
postalCode:
type: string
description: Address postal code
maxLength: 15
minLength: 1
city:
type: string
description: Address city
maxLength: 50
minLength: 1
state:
type: string
description: Address state
maxLength: 30
minLength: 1
countryCode:
type: string
format: ISO 3166-1 alpha-2
description: The supported ISO 3166-1 alpha-2 country code
minLength: 1
required:
- address1
- city
- countryCode
- postalCode
PaymentsPaymentInstrument:
type: object
discriminator:
propertyName: type
properties:
type:
type: string
description: The type of instrument.
required:
- type
TokenPaymentInstrument:
allOf:
- $ref: '#/components/schemas/PaymentsPaymentInstrument'
- type: object
properties:
type:
type: string
enum:
- token
tokenId:
type: string
description: Worldpay's internal identifier for a token. If supplied, must be between 15 and 21 characters, must consist of digits and upper-case characters excluding 'I' and 'O'. __Note:__ Provide a value in `tokenId` or `href`, never both.
example: 9902480679618050000
maxLength: 21
minLength: 15
pattern: ^[0-9A-HJ-NP-Z]*$
href:
type: string
description: An http address that contains your link to an Access Token. __Note:__ Provide a value in `href` or `tokenId`, never both.
example: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoiNjQxbUsw...
namespace:
type: string
description: A reference to group up to 16 cards, e.g. for one customer.
maxLength: 64
minLength: 1
pattern: ^[^_][^ &<]*$
cvc:
type: string
description: '
CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.'
example: '123'
maxLength: 4
minLength: 3
pattern: '[0-9]*$'
cvcSessionHref:
type: string
description: '
Href to the Checkout session providing the Card Verification Code (CVC).__Note:__ Provide a value in `cvcSessionHref` or `cvc`, never both.'
example: https://try.access.worldpay.com/sessions/eyJrIjoxLCJkIjoiNjQxbUsw...
routing:
$ref: '#/components/schemas/Routing'
required:
- type
securitySchemes:
BasicAuth:
type: http
scheme: basic