# Payment request

Initiate payment

Endpoint: POST /api/payments
Version: 2024-06-01
Security: BasicAuth

## Header parameters:

  - `WP-Api-Version` (string, required)
    The API version
    Enum: "2024-06-01"

## Request fields (application/json):

  - `transactionReference` (string, required)
    A unique reference generated by you that is used to identify a payment throughout its lifecycle.

  - `merchant` (object, required)
    An object that contains information about the merchant.

  - `merchant.entity` (string, required)
    Used to route the request in Access Worldpay, created as part of on-boarding.
    Example: "default"

  - `merchant.mcc` (string)
    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.

  - `merchant.paymentFacilitator` (object)

  - `merchant.paymentFacilitator.schemeId` (string, required)
    Your payment facilitator ID received from Mastercard, Visa and Amex.
    Example: "12345678901"

  - `merchant.paymentFacilitator.independentSalesOrganizationId` (string)
    Independent Sales Organization (ISO) ID provided by Mastercard.
    Example: "12345678901"

  - `merchant.paymentFacilitator.subMerchant` (object, required)

  - `merchant.paymentFacilitator.subMerchant.name` (string, required)
    The name of your subMerchant's company.
    Example: "Merchant Plc"

  - `merchant.paymentFacilitator.subMerchant.reference` (string, required)
    Unique merchant reference.
    Example: "123456789012345"

  - `merchant.paymentFacilitator.subMerchant.address` (object, required)

  - `merchant.paymentFacilitator.subMerchant.address.postalCode` (string, required)
    Post code/Zip code of your subMerchant's company.
    Example: "SW1 1AA"

  - `merchant.paymentFacilitator.subMerchant.address.street` (string, required)
    Street name of your subMerchant's company.
    Example: "221B Baker Street"

  - `merchant.paymentFacilitator.subMerchant.address.city` (string, required)
    City of your subMerchant's company.
    Example: "London"

  - `merchant.paymentFacilitator.subMerchant.address.state` (string)
    State of your subMerchant's company.
    Example: "GB"

  - `merchant.paymentFacilitator.subMerchant.address.countryCode` (string, required)
    Country code of your subMerchant's company in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).
    Example: "GB"

  - `merchant.paymentFacilitator.subMerchant.phoneNumber` (string)
    Phone number of your subMerchant's company.
    Example: "987-65-4321"

  - `merchant.paymentFacilitator.subMerchant.taxReference` (string)
    Tax Reference of your subMerchant's company.
    Example: "987-65-4321"

  - `merchant.paymentFacilitator.subMerchant.email` (string)
    Email address of your subMerchant's company.
    Example: "email@example.com"

  - `merchant.paymentFacilitator.subMerchant.url` (string)
    Example: "url.example.com"

  - `instruction` (object, required)
    An object that contains all information related to the payment and API configurations.

  - `instruction.method` (string, required)

  - `instruction.paymentInstrument` (any, required)

  - `instruction.narrative` (object, required)
    The text that appears on your customer's statement. Used to identify the merchant.

  - `instruction.narrative.line1` (string, required)
    line1 is used to provide basic details about the merchant.

  - `instruction.narrative.line2` (string)
    line2 is used for additional context about the payment or merchant. E.g. Order number or Merchant phone number.

  - `instruction.tokenCreation` (object)
    Use this object if you want to create a token after the payment. Can only be used with paymentInstrument.type: card/plain & checkout.

  - `instruction.tokenCreation.type` (string, required)
    Enum: "worldpay"

  - `instruction.tokenCreation.namespace` (string)
    A namespace is used to group up to 16 cards, e.g. for one customer. A card can exist in more than one namespace.

  - `instruction.tokenCreation.description` (string)
    A description of your token. If not supplied, a default description is created for you.

  - `instruction.value` (object, required)
    The value and currency.

  - `instruction.value.currency` (string, required)
    The three character currency code. See list of supported currencies
    Example: "USD"

  - `instruction.value.amount` (integer, required)
    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

  - `instruction.value.acceptPartialAmount` (boolean)
    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.

  - `instruction.debtRepayment` (boolean)
    A flag which identifies a payment as being for the purpose of repaying a debt.

  - `instruction.fraud` (object)
    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.

  - `instruction.fraud.type` (string, required)
    Enable a FraudSight risk assessment
    Enum: "fraudSight"

  - `instruction.fraud.silentMode` (boolean)
    Perform the Fraud assessment but do not act on the outcome.
            Normally used for the initial launch while the data model is maturing.

  - `instruction.fraud.tmxSessionId` (string)
    Device fingerprint provided by Threatmetrix.

  - `instruction.fraud.custom` (object)

  - `instruction.fraud.custom.number1` (integer)

  - `instruction.fraud.custom.number2` (integer)

  - `instruction.fraud.custom.number3` (integer)

  - `instruction.fraud.custom.number4` (integer)

  - `instruction.fraud.custom.number5` (integer)

  - `instruction.fraud.custom.number6` (integer)

  - `instruction.fraud.custom.number7` (integer)

  - `instruction.fraud.custom.number8` (integer)

  - `instruction.fraud.custom.number9` (integer)

  - `instruction.fraud.custom.string1` (string)

  - `instruction.fraud.custom.string2` (string)

  - `instruction.fraud.custom.string3` (string)

  - `instruction.fraud.custom.string4` (string)

  - `instruction.fraud.custom.string5` (string)

  - `instruction.fraud.custom.string6` (string)

  - `instruction.fraud.custom.string7` (string)

  - `instruction.fraud.custom.string8` (string)

  - `instruction.fraud.custom.string9` (string)

  - `instruction.threeDS` (object)
    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.

  - `instruction.threeDS.mode` (string, required)
    Enum: "always"

  - `instruction.threeDS.challenge` (object, required)

  - `instruction.threeDS.challenge.returnUrl` (string, required)
    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.

  - `instruction.threeDS.challenge.windowSize` (string)
    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"

  - `instruction.threeDS.challenge.preference` (string)
    Set a preference for how the Issuer decides on a 3DS challenge.
    Enum: "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated", "noChallengeRequestedTRAPerformed"

  - `instruction.threeDS.deviceData` (object, required)

  - `instruction.threeDS.deviceData.acceptHeader` (string, required)
    Used by the issuer to check if the customer's browser is compatible with the issuer 3DS challenge display.

  - `instruction.threeDS.deviceData.userAgentHeader` (string, required)
    Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321.

  - `instruction.threeDS.deviceData.browserLanguage` (string)
    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.

  - `instruction.threeDS.deviceData.browserJavaEnabled` (boolean)
    Defines whether Java is enabled on your customers browser.

  - `instruction.threeDS.deviceData.browserColorDepth` (string)
    The color depth of your customers browser
    Enum: "1", "4", "8", "15", "16", "24", "32", "48"

  - `instruction.threeDS.deviceData.browserScreenHeight` (integer)
    Defines the pixel height of the customers browser.

  - `instruction.threeDS.deviceData.browserScreenWidth` (integer)
    Defines the pixel width of the customers browser.

  - `instruction.threeDS.deviceData.timeZone` (string)
    Time zone offset in minutes between UTC and your customer's browser local time.  
Example time zone offset values in minutes:  
If UTC -5 hours:  
300  
+300  
If UTC +5 hours:  
-300

  - `instruction.threeDS.deviceData.browserJavascriptEnabled` (boolean)
    Defines whether Javascript is enabled on your customers browser.

  - `instruction.threeDS.deviceData.channel` (string)
    Determines the channel that the transaction came through. native should only be set if using the Cardinal 3DS SDK (iOS/Android)
    Enum: "browser", "native"

  - `instruction.threeDS.previousSuspiciousActivity` (boolean)
    Has the account been flagged for suspicious activity.

  - `instruction.threeDS.userType` (string)
    Enum: "guestUser", "registeredUser", "federatedAccount", "issuerCredentials", "thirdPartyAuthentication", "fidoAuthenticator"

  - `instruction.threeDS.accountHistory` (object)

  - `instruction.threeDS.accountHistory.createdAt` (string)
    Date the customer account was created.

  - `instruction.threeDS.accountHistory.modifiedAt` (string)
    Date the customer account was last modified.

  - `instruction.threeDS.accountHistory.passwordModifiedAt` (string)
    Date the password for the customer account was last modified.

  - `instruction.threeDS.accountHistory.paymentAccountEnrolledAt` (string)
    Date the payment account was added to the cardholder account.

  - `instruction.threeDS.reorder` (boolean)
    Repeat of a previous order.

  - `instruction.threeDS.preOrderDate` (string)
    Expected date that a pre-ordered purchase will be available.

  - `instruction.threeDS.transactionHistory` (object)

  - `instruction.threeDS.transactionHistory.attemptsLastDay` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours.

  - `instruction.threeDS.transactionHistory.attemptsLastYear` (integer)
    Number of transactions (successful or abandoned) for this cardholder account within the last year.

  - `instruction.threeDS.transactionHistory.completedLastSixMonths` (integer)
    Number of purchases with this customer account during the previous six months.

  - `instruction.threeDS.transactionHistory.addCardsLastDay` (integer)
    Number of attempts to add a card in the last 24hrs.

  - `instruction.threeDS.transactionHistory.shippingAddressFirstUsedAt` (string)
    When the shipping address used for the transaction was first used.

  - `instruction.threeDS.giftCardsPurchase` (object)

  - `instruction.threeDS.giftCardsPurchase.totalValue` (object)
    The value and currency.

  - `instruction.threeDS.giftCardsPurchase.quantity` (integer)
    The number of gift cards being purchased.

  - `instruction.threeDS.exemptionOnOutage` (boolean)
    "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)"

  - `instruction.exemption` (object)
    An object used to request or specify an SCA Exemption. 

Read more on how to set it up under our [__SCA Exemptions__](/products/payments/enable-features/sca-exemptions) guide.

  - `instruction.exemption.type` (string, required)
    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"

  - `instruction.exemption.mode` (string, required)
    Specify which transactions to request SCA Exemptions for.
    Enum: "always"

  - `instruction.exemption.capability` (string, required)
    Indicates whether the exemption requested from Worldpay can return a placement of authorization (payment) and/or authentication (3DS).
    Enum: "authorizationAndAuthentication", "authorizationOnly", "authenticationOnly"

  - `instruction.exemption.request` (object)

  - `instruction.exemption.request.placement` (string)
    Defines where the exemption is being requested.
    Enum: "optimized", "authorization", "authentication"

  - `instruction.exemption.request.type` (string)
    Defines which type of exemption is being requested.
    Enum: "optimized", "lowValue", "lowRisk"

  - `instruction.settlement` (object)
    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.

  - `instruction.settlement.auto` (boolean, required)

  - `instruction.settlement.cancelOn` (object)

  - `instruction.settlement.cancelOn.cvcNotMatched` (string)
    By default a payment will be sentForCancellation if the CVC is notMatched, set disabled to continue with sentForSettlement.
    Enum: "enabled", "disabled"

  - `instruction.settlement.cancelOn.avsNotMatched` (string)
    By default a payment will be sentForCancellation if the address or postcode AVS is notMatched, set disabled to continue with sentForSettlement.
    Enum: "enabled", "disabled"

  - `instruction.customer` (object)

  - `instruction.customer.customerId` (string)
    Unique identifier used by the ecommerce system for the customer.

  - `instruction.customer.firstName` (string)
    Customer's first name.

  - `instruction.customer.lastName` (string)
    Customer's last name.

  - `instruction.customer.phone` (string)
    Customer's phone number.

  - `instruction.customer.dateOfBirth` (string)
    Customer's date of birth.

  - `instruction.customer.email` (string)
    Customers's email address used for the ecommerce account.

  - `instruction.customer.ipAddress` (string)
    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.

  - `instruction.customer.documentReference` (string)
    Required for domestic processing in some Latin American countries.

  - `instruction.shipping` (object)
    Object containing all data related to how the order will be shipped.

  - `instruction.shipping.method` (string)
    The shipping method used.
    Enum: "billingAddress", "verifiedAddress", "otherAddress", "store", "digital", "unshippedTickets", "other"

  - `instruction.shipping.timeFrame` (string)
    Enum: "electronic", "sameDay", "nextDay", "twoDaysPlus"

  - `instruction.shipping.email` (string)
    The email address used for an electronic delivery.

  - `instruction.shipping.phone` (string)
    The phone number used for delivery.

  - `instruction.shipping.firstName` (string)
    First name used on the shipping address.

  - `instruction.shipping.lastName` (string)
    Last name used on the shipping address.

  - `instruction.customerAgreement` (any)

  - `instruction.recipient` (object)
    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.

  - `instruction.recipient.accountReference` (string)
    The account number of the recipient. Either a bank account number or a partial card number.

  - `instruction.recipient.lastName` (string)
    The last name of the recipient.

  - `instruction.recipient.dateOfBirth` (string)
    Recipient's date of birth.

  - `instruction.consumerBillPayment` (boolean)
    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.

  - `instruction.requestAccountUpdater` (boolean)
    Allows you to request a real-time account update (Visa cards only) when using a previously stored card. You can only use this on subsequent card requests.

  - `channel` (string)
    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"

## Response 201 fields (application/json):

  - `outcome` (string)

  - `transactionReference` (string)
    A unique reference generated by you that is used to identify a payment throughout its lifecycle.

## Response 202 fields (application/json):

  - `outcome` (string)

  - `transactionReference` (string)
    A unique reference generated by you that is used to identify a payment throughout its lifecycle.

## Response 400 fields (application/json):

  - `errorName` (string)

  - `message` (string)

  - `jsonPath` (string)

  - `validationErrors` (array)

## Response 401 fields (application/json):

  - `errorName` (string)

  - `message` (string)

## Response 404 fields (application/json):

  - `errorName` (string)

  - `message` (string)

## Response 406 fields (application/json):

  - `errorName` (string)

  - `message` (string)

  - `headerName` (string)

## Response 415 fields (application/json):

  - `errorName` (string)

  - `message` (string)

## Response 500 fields (application/json):

  - `errorName` (string)

  - `message` (string)