# 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.

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

  - `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.Also used for __3DS authentication__ to display the merchant name during the authentication process.
    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` (any)

  - `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.

__Used for:__ Risk assessment

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

__Used for:__ 3DS authentication | Risk assessment

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

__Used for:__ 3DS authentication | Risk assessment

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

__Used for:__ 3DS authentication | Risk assessment | Card authorization

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

__Used for:__ Risk assessment

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

__Used for:__ 3DS authentication | Risk assessment | Card authorization

  - `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.

__Used for:__ 3DS authentication | Risk assessment | Card authorization

  - `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.

__Used for:__ 3DS Authentication | Risk assessment

  - `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.shipping.address` (object)

  - `instruction.shipping.address.address1` (string, required)
    Address line 1

  - `instruction.shipping.address.address2` (string)
    Address line 2

  - `instruction.shipping.address.address3` (string)
    Address line 3

  - `instruction.shipping.address.postalCode` (string, required)
    Address postal code

  - `instruction.shipping.address.city` (string, required)
    Address city

  - `instruction.shipping.address.state` (string)
    Address state

  - `instruction.shipping.address.countryCode` (string, required)
    The supported ISO 3166-1 alpha-2 country code

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

  - `instruction.recipient.address.postalCode` (string)
    The postal code of the recipient. Relevant only in the UK.

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

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

  - `instruction.fundsTransfer.purpose` (string)
    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"

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

  - `instruction.fundsTransfer.recipient.account` (object)

  - `instruction.fundsTransfer.recipient.account.type` (string, required)
    The type of account.

  - `instruction.fundsTransfer.recipient.firstName` (string)
    Recipient's first name.

  - `instruction.fundsTransfer.recipient.middleName` (string)
    Recipient's middle name.

  - `instruction.fundsTransfer.recipient.lastName` (string)
    Recipient's last name.

  - `instruction.fundsTransfer.recipient.address` (object)

  - `instruction.fundsTransfer.recipient.address.address1` (string)
    Must be supplied if city is provided.

  - `instruction.fundsTransfer.recipient.address.address2` (string)

  - `instruction.fundsTransfer.recipient.address.city` (string)
    Must be supplied if address1 is provided.

  - `instruction.fundsTransfer.recipient.address.postalCode` (string)

  - `instruction.fundsTransfer.recipient.address.state` (string)
    1-3 alphanumeric characters and spaces.

  - `instruction.fundsTransfer.recipient.address.countryCode` (string, required)
    Country code in [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes).

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

  - `instruction.fundsTransfer.recipient.phoneNumber` (string)
    Recipient's phone number

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

  - `instruction.fundsTransfer.sender` (object)
    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.__

  - `instruction.fundsTransfer.sender.firstName` (string)
    Sender's first name. Must be supplied if lastName or middleName are provided.

  - `instruction.fundsTransfer.sender.middleName` (string)
    Sender's middle name.

  - `instruction.fundsTransfer.sender.lastName` (string)
    Sender's last name. Must be supplied if firstName or middleName are provided.

  - `instruction.fundsTransfer.sender.address` (object)

  - `instruction.fundsTransfer.sender.dateOfBirth` (string)
    Sender's date of birth

  - `instruction.fundsTransfer.sender.documentReference` (string)
    Sender's document reference (e.g. Tax ID). Required for domestic processing in some Latin American countries.

  - `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 406 fields (application/json):

  - `errorName` (string)

  - `message` (string)

  - `headerName` (string)