Access Worldpay
/
Take a card payment

Last Updated: 04 December 2024 | Change Log

Take a card payment

New API Version

This documentation is for version 7 of the Card Payments API. If you're using version 6, you can find information on how to upgrade in our migration guide.

Take online card payments using our Card Payments API.

Customer Initiated Transactions

All payment requests where the cardholder actively participates in the flow are Customer Initiated Transactions (CITs).

POST to our customerInitiatedTransactions endpoint to authorize a payment.

The requests below contain all the mandatory fields needed for a successful authorization request.

Note

Click the tabs below to see all the mandatory fields for all supported paymentInstrument parameters.

POST https://try.access.worldpay.com/cardPayments/customerInitiatedTransactions

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "expiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "channel": "ecom"
}

For more information about network token requests, see our network tokens section.

Parameter descriptions

ParameterRequiredDescription
transactionReference✅A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format, for more details and the best practices.
merchant✅An object that contains information about the merchant.
merchant.entity✅Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
Contact your Implementation Manager for more details.
merchant.mcc❌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. For more information contact your Relationship Manager.
merchant.paymentFacilitator❌An object containing Payment Facilitator information. This information is required for every authorization only if you are a Payment Facilitator:
  • schemeId
  • independentSalesOrganizationId
  • subMerchant.name
  • subMerchant.reference
  • subMerchant.address.postalCode
  • subMerchant.address.street
  • subMerchant.address.city
  • subMerchant.address.state
  • subMerchant.address.countryCode
  • subMerchant.phoneNumber (mandatory for Amex)
  • subMerchant.email (mandatory for Amex)
  • subMerchant.taxReference
You can find more formatting information here.
channel✅The payment channel indicates the interaction of the cardholder with the merchant. Possible value :
  • ecom
  • moto
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 (MOTO) transaction.
Note
3DS authentication data cannot be supplied for MOTO payments.
instruction✅An object that contains all information related to the payment.
instruction.narrative✅The text that appears on your customer's statement. Used to identify the merchant.
See narrative format for more details and best practices.
narrative.line1✅The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space.).
See narrative line1 format for more details.
narrative.line2❌Additional details about the payment e.g. order number, telephone number.
instruction.requestAutoSettlement.enabled✅A boolean value to indicate whether the transaction should be sent for settlement now (true), or later at a time of your choosing, using an action link (false). See settlement
instruction.customerAgreement❌An object containing details about processing agreements made with your customer. Ie:
  • An agreement to store the customer's paymentInstrument for future processing (e.g. set up a subscription plan, or store a card on file)
  • Set up an installment schedule (for Latin America payments)
customerAgreement.type✅Possible values:
  • cardOnFile
  • subscription
  • installment
customerAgreement.storedCardUsage✅
Mandatory for types:
  • cardOnFile
  • subscription
  • installment (where installmentType = merchant)
Possible values:
  • first - for storing a card
  • subsequent - for subsequent use of a previously stored card
customerAgreement.installmentType✅
Mandatory where customerAgreement.type = installment.		Possible values:
  • merchant
    • - for installment plans offered by merchants (e.g. "Buy Now, Pay Later")
  • latinAmerica - for installment plans in Latin America
instruction.value✅An object that contains information about the value of the payment.
value.currency✅The three digit currency code.
See list of supported currencies.
value.amount✅The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our currency table.
instruction.paymentInstrument✅An object that contains the payment type and details.
To use "tokens" as a paymentInstrument you must first create a token.
paymentInstrument.cardHolderName❌The name on your customer's card.
This is not a mandatory field however it is recommended that you supply this to improve authorization rates. If not sent, the default value is "Not Supplied".
paymentInstrument.expiryDate✅The expiry date of the supplied payment instrument. This will usually be the expiry date printed on the card, however for "type": "card/networkToken" and "type": "card/networkToken+applepay", the token expiry should be supplied.
Mandatory where the paymentInstrument has a type of: card/plain, card/networkToken or card/networkToken+applepay.
paymentInstrument.cardNumber✅Your customer's card number. Mandatory for "type": "card/plain" requests.
paymentInstrument.tokenNumber✅The token number for "type": "card/networkToken" and "type": "card/networkToken+applepay" payment instruments.
paymentInstrument.cvc❌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.
paymentInstrument.billingAddress❌An object containing the billing address information. If included you must send at least:
  • address1
  • city
  • countryCode
  • postalCode
This is used for Address Verification Service (AVS) and can only be supplied with a card/plain,card/wallet+applepay or card/wallet+googlepay payment instrument. Our API checks the submitted AVS to see if it matches the address registered with the issuing bank. If the address supplied does not match the registered address it means that the payment carries additional risk.
instruction.requestAccountUpdater❌Set to true to request a real-time account update (Visa cards only) when using a previously stored card. If the supplied card has been updated, we will return updated card details in the updatedPaymentInstrument object in the authorization response.

Note
The following conditions must all be fulfilled to request a real-time account update:
  • cvc must not be supplied
  • customerAgreement.type must be "cardOnFile"
  • customerAgreement.storedCardUsage must be "subsequent"
instruction.routing❌An object containing preferred routing instructions.
routing.preferredCardBrand❌Set your customer's preferred card brand to honor their card brand choice for co-badged cards.
riskProfile❌Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments.

Store a card

If you are storing your customer's payment details for future use, you must indicate this, using the customerAgreement object. You can use our Tokens API to store your customer's card details via Worldpay tokens or network tokens.

Note

Important: You must have consent from your customer to store their card details.

You must also indicate when a card that you have stored previously is being used in a subsequent payment.

Example use cases:

  • First card on file: A payment where the customer opts to store their card on your website for faster checkout on future purchases (ie express checkout)
  • Subsequent card on file: A payment where the customer selects a card that they have previously stored with you for an express checkout flow
  • First payment in a subscription agreement
  • First payment in an installment plan

Subsequent subscription or installment payments must be sent using our merchant initiated transactions endpoint, since these payments are not directly initiated by the cardholder.

Note

Strong Customer Authentication (SCA) is mandatory when storing payment details. You must include 3DS authentication or an SCA Exemption when a stored card is being used for the first time.

Example card on file requests:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "expiryDate": {
                "month": 5,
                "year": 2035
            },
            "cvc":"123"
        },
        "customerAgreement":{
            "type":"cardOnFile",
            "storedCardUsage":"first"
        }
    },
    "channel": "ecom",
    "authentication": {
        "threeDS": {
            "eci": "05",
            "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=",
            "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999",
            "version": "2.2.0"
        }
    }
}

Example first subscription requests:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "expiryDate": {
                "month": 5,
                "year": 2035
            },
            "cvc":"123"
        },
        "customerAgreement":{
            "type":"subscription",
            "storedCardUsage":"first"
        }
    },
    "channel": "ecom",
    "authentication": {
        "threeDS": {
            "eci": "05",
            "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=",
            "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999",
            "version": "2.2.0"
        }
    }
}
ParameterRequiredDescription
customerAgreement.type✅The processing arrangement agreed with your customer.
Possible values:
  • cardOnFile - for storing card details for future CITs
  • subscription - for storing card details for a subscription agreement
  • installment - for storing card details for an installment plan
customerAgreement.storedCardUsageMandatory for types:
  • cardOnFile
  • subscription
  • installment (where installmentType = merchant
Possible values:
  • first - for storing a card
  • used - for using a previously-stored card
customerAgreement.installmentTypeMandatory where customerAgreement.type = installment.Possible values:
  • merchant
  • latinAmerica - for installment plans in Latin America

Settlement

Auto settlement

You can request that payment authorizations are automatically sent for settlement (sometimes referred to as "capture") by setting requestAutoSettlement.enabled to true in your /cardPayments/customerInitiatedTransactions request.

Manual settlement

To manually request settlement at a time of your choosing, set requestAutoSettlement.enabled to false. You can then use the cardPayments:settle or cardPayments:partialSettle next action link returned in your response message to send the full authorized amount or a partial amount for settlement.

Note

Payment Authorizations automatically expire after a set time period. The time period can be as little as three days, and depends on a number of parameters such as your region, Merchant Category Code (MCC), and the payment purpose. Please refer to card scheme documentation for the authorization expiry time periods for each scenario.

Network Tokens

Network tokens are format-preserving representations of a cardNumber (Primary Account Number, or PAN: the long card number, usually on the front of a card). This means that, like a cardNumber, network tokens are usually 16-digits in length.

Some benefits of using network tokens:

  • Increased authorization rates
  • Reduced card scheme fees in some regions
  • Increased security given a new cryptogram must be provisioned for each customer initiated payment
  • Network tokens remain unaltered if the underlying card expires and is re-issued

When using network tokens in Customer Initiated Transactions, you must include the cryptogram for this particular transaction. This can be obtained from our Tokens API or your Token provider.

ParameterRequiredDescription
authentication.networkToken✅An object containing network token verification details.
authentication.networkToken.cryptogram✅The single-use cryptogram provisioned for this payment.
authentication.networkToken.eci❌Electronic Commerce Indicator (ECI).
Indicates the outcome of the network token verification.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Not successfully authenticated
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07

Example network token requests:

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/networkToken",
            "tokenNumber": "4444333322221111",
            "expiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "channel": "ecom",
    "authentication": {
        "networkToken": {
            "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=",
            "eci": "05"
        }
    }
}

FraudSight

Link your FraudSight assessment with your payment using the riskProfile. This allows the fraud model to learn and improve the risk health of future payments.

"riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC"

For a full example request please see our optional parameters section.

SCA Exemptions

Link your Exemption assessment with your payment using the riskProfile. This allows the exemption to be applied to your payment authorization.

"riskProfile": "https://try.access.worldpay.com/riskProfile/ewogICJ2IiA6IDEsC"

For a full example request please see our optional parameters section.

3DS

3DS authorization request parameter descriptions

Complete an authentication request using our 3DS API to get the details required to prove that 3DS has taken place.

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "default"
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "narrative": {
            "line1": "Mind Palace"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "expiryDate": {
                "month": 5,
                "year": 2035
            }
        }
    },
    "channel": "ecom",
    "authentication": {
        "threeDS": {
            "eci": "05",
            "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=",
            "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999",
            "version": "2.2.0"
        }
    }
}
Note
  • 3DS data cannot be supplied for MOTO transactions.

The descriptions of parameters from your 3DS authorization request

ParameterRequiredDescription
authentication.threeDS✅An object containing the result of your customer's verification. For more details see 3DS verification.
authentication.threeDS.version✅The version of 3DS used to process the transaction.
For 3DS1 - 1.0.2
For 3DS2 - 2.1.0 or 2.2.0
Note
Required for Mastercard's Identity Check transactions in Authorization.
authentication.threeDS.eci✅Electronic Commerce Indicator (ECI).
Indicates the outcome of the 3DS verification.
  • 02 or 05 - Fully Authenticated Transaction
  • 01 or 06 - Attempted Authentication Transaction
  • 00 or 07 - Non 3-D Secure Transaction
  • Mastercard - 02, 01, 00
  • Visa - 05, 06, 07
  • Amex - 05, 06, 07
  • JCB - 05, 06, 07
  • Diners - 05, 06, 07
authentication.threeDS.authenticationValue✅Required, if threeDS.eci value is 01, 02, 05 or 06.
A cryptographic value that provides evidence of the outcome of a 3DS verification.
  • Visa - Cardholder Authentication Verification Value (CAVV)
  • Mastercard - Universal Cardholder Authentication Field (UCAF)
threeDS.authenticationValue must be 28 digits max and must be base64-encoded.
authentication.threeDS.transactionId✅Required, if threeDS.eci value is 01, 02, 05 or 06.
A unique authentication transaction identifier, generated by the issuer.

For version 3DS1: transactionId is base64-encoded and 28 digits in length.
For version 3DS2: transactionId follows RFC 4122 UUID standard and is 36 characters in length.
authentication.threeDS.cryptogramAlgorithm❌Indicates the algorithm used to generate the cryptogram.
For Cartes Bancaires authorizations only.
authentication.threeDS.challengePreference❌Indicates the preferred challenge behavior.
  • noPreference
  • noChallengeRequested
  • challengeRequested
  • challengeMandated

For Cartes Bancaires authorizations only.
authentication.threeDS.authenticationFlow❌
  • challenge - Your customer was redirected to their bank to complete authentication
  • frictionless - Your customer completed authentication without needing to be redirected to their bank

For Cartes Bancaires authorizations only.
authentication.threeDS.statusReason❌Provides further information relating to the outcome of the authentication. Returned for failed authentications only.
For Cartes Bancaires authorizations only.
authentication.threeDS.cancellationIndicator❌An indicator as to why the authentication was cancelled.
  • - 01 - Cardholder selected cancel
  • - 02 - Reserved for future use
  • - 03 - Authentication timed out
  • - 04 & 05 - Authentication timed out at ACS provider
  • - 06 - Transaction error
  • - 07 - Unknown
  • - 08 - Transaction timed out at SDK

For Cartes Bancaires authorizations only.
authentication.threeDS.networkScore❌The global score calculated by the Cartes Bancaires scoring platform.
For Cartes Bancaires authorizations only.
authentication.threeDS.brand❌The card brand used in the authentication.
For Cartes Bancaires authorizations only.

Mail Order and Telephone Order (MOTO) transactions

Take MOTO transactions by using "channel":"moto".

3DS authentication data cannot be supplied for MOTO transactions.

Latin America (LatAm) Payments

Take payments in Latin America, with additional regional functionalities and parameters, such as installment plans and customer's tax/document reference.

Parameters
ParameterRequired?Description
instruction.customerAgreement❌An object containing details about processing agreements made with your customer, e.g. a request to set up an installment schedule for Latin American payments
customerAgreement.type✅installment
customerAgreement.storedCardUsage❌Possible values:
  • first - for storing a card
  • subsequent - for subsequent use of a previously-stored card
customerAgreement.installmentType✅
  • latinAmerica
customerAgreement.installmentPlan✅An object describing the installment plan.
installmentPlan.numberOfInstallments✅The number of installments to split the payment into.
customer.documentReference❌The customer's document reference number is required for domestic processing in some Latin America countries in order to reduce fraud and improve approval rates. Some example documents:
  • Argentina: DNI, CUIT, CUIL or CDI
  • Brazil: CPF or CNPJ
  • Mexico: CURP
instruction.routing.fundingType✅Specify the source of funds for cards that combine multiple funding types (sometimes referred to as "combo cards"). Possible values:
  • credit
  • debit
order.salesTax✅The amount of sales tax (VAT/IVA) of the transaction.

Code example

    "instruction": {        
        "customerAgreement": {
            "type": "installment",
            "installmentType": "latinAmerica",
            "installmentPlan": {
                "numberOfInstallments": 3
            }
        },
        "customer": {
            "documentReference": "123-ABC"
        },
        "routing": {
            "fundingType": "debit"
        }
    },
    "order": {
        "salesTax": 300
    }

Funds Transfers

A funds transfer is a money movement for a reason other than for the purchase of goods or services. These are also referred to as Account Funding Transactions (AFTs).

Examples:

  • Loading a wallet with funds using a card (including stored value digital wallets and crypto or trading wallets)
  • Adding funds to a pre-paid card using another card
  • Sending money to another person (for example as a gift)
Parameters

You must include the instruction.fundsTransfer object to correctly flag a transaction as a funds transfer.

ParameterRequired?Description
instruction.fundsTransfer❌An object containing details about the transfer and the sender and recipient of funds.
fundsTransfer.type✅Possible values:
  • accountToAccount - Move funds to another financial institution account owned by the same person
  • cash - A card is used to fund a transfer where funds are given to the recipient in cash
  • disbursement - A card is used as the source of funds for a disbursement
  • transfer - Move funds to another account owned by the same person. Eg crypto/trading
  • personToPerson - Move money to an account owned by another person
  • payrollDisbursement - Use a card to fund payroll disbursements
  • prePaidTopUp - Top up a pre-paid card
  • debitTopUp - Transfer funds from a card to a debit card account owned by the same person
fundsTransfer.purpose❌Possible values:
  • familySupport
  • travel
  • education
  • medical
  • emergency
  • savings
  • gift
  • other
  • salary
  • crowdLending
  • crypto
fundsTransfer.sender❌An object containing details about the sender of funds. Includes:
  • firstName
  • middleName
  • lastName
  • address.address1
  • address.address2
  • address.postalCode
  • address.city
  • address.state
  • address.countryCode
fundsTransfer.recipient❌An object containing details about the recipient of funds. Includes:
  • firstName
  • middleName
  • lastName
  • address.address1
  • address.address2
  • address.postalCode
  • address.city
  • address.state
  • address.countryCode
  • dateOfBirth
  • phoneNumber
recipient.account❌An object for the account details of the recipient
account.type❌Possible values:
  • bankAccount
  • card
  • email
  • phone
  • wallet
  • socialNetwork
account.identifierType❌Required when account.type is bankAccount. Possible values:
  • iban
  • swift
  • routingNumber
account.reference❌A reference specific to the account type selected. Possible fields:
  • iban
  • swift
  • routingNumber
  • accountNumber
  • cardNumber
  • walletReference
  • emailAddress
  • phoneNumber
  • socialNetworkReference

Code example

    "instruction": {        
        "fundsTransfer": {
            "type": "transfer",
            "purpose": "crypto",
            "recipient": {
                "account": {
                    "type": "wallet",
                    "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": {
                    "day": 12,
                    "month": 4,
                    "year": 2001
                },
                "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"
                }
            }
        }
    }

Financial Services (including MCC 6012)

If you provide financial services, debt repayment, or consumer bill payments, you should supply additional details in the authorization request for compliance reasons.

Parameters
ParameterDescriptionFormatting
instruction.debtRepaymentDRI is a flag which identifies a payment as being for the purpose of repaying a debt. Possible value :
  • true (only supply if true)
For more information contact your Relationship Manager.		true
instruction.consumerBillPaymentAn 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.true
recipientAn 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.
recipient.accountReferenceThe account number of the recipient. Either a bank account number or a partial card number.Alphanumeric. Max 10 characters
recipient.lastNameThe last name of the recipient.String.
recipient.dateOfBirth.dayThe day of birth of the recipient.Possible Values: 1-31
recipient.dateOfBirth.monthThe month of birth of the recipient.Possible Values: 1-12
recipient.dateOfBirth.yearThe year of birth of the recipient.A valid 4 digit year in the past. Example: "1984"
recipient.address.postalCodeThe postal code of the recipient. Relevant only in the UK.Must be full UK postal code

Code example

    "recipient": {
        "accountReference": "12499844",
        "lastName": "Moriarty",
        "address": {
            "postalCode": "SW1 1AA"
        },
        "dateOfBirth": {
            "day": 29,
            "month": 4,
            "year": 1990
        }
    }

Level 2 / Level 3 data

Receive several cost and efficiency benefits when supplying Level 2 & Level 3 data as part of the authorization or settlement requests.

Benefits
Benefit
Description
Reduced interchange feesIf you are a US based merchant, you can qualify for lower interchange fees on transactions by providing additional order-specific data, such as tax reference, product code or sales tax amount. Card networks often offer lower rates for transactions with enhanced data, reducing processing costs.
Enhanced fraud detectionDetailed transaction data allows card networks to better authenticate purchases, reducing fraud and chargeback rates.
Improved dispute managementWith comprehensive transaction details, card networks can better handle and resolve disputes. This reduces the time and effort you spend managing chargebacks and can lead to faster resolutions.
Increased customer trust and satisfactionProviding enhanced data improves transaction transparency, giving customers more confidence in their purchases. It also leads to more accurate transaction records on your customer's statements, minimizing confusion or disputes.
Compliance with industry standardsCard networks increasingly require detailed transaction data to maintain compliance with industry standards and processing requirements.
Parameters
ParameterRequired?Description
merchant.taxReference❌Your tax reference.
shipping.recipient❌An object containing recipient's postal and country codes.
shipping.sender❌An object containing sender's postal code.
customer.reference❌Customer reference for the order.
order.invoiceReference❌Invoice reference for the order.
order.salesTax❌Total amount of sales tax for the order.
order.discountAmount❌Total amount of discounts for the order.
order.shippingAmount❌Total amount of shipping costs for the order.
order.dutyAmount❌Total amount of duty costs for the order.
order.orderDate❌Date of the order.
order.taxExempt❌A flag to indicate whether the purchase is exempt from tax. Must be set to true if order.salesTax is 0.
order.items❌An array with objects containing details of items purchased. Each object represents one group of items and you can submit up to 99 item groups.
items.productCode❌Merchant defined product code.
items.commodityCode❌Commodity code as defined by the National Institute of Governmental Purchasing.
items.name❌Name of the item(s).
items.quantity❌Number of items purchased.
items.unitOfMeasure❌The unit of measure of the purchased item. Explains how to interpret items.quantity field, e.g. quantity = 15, unitOfMeasure = kg
items.unitCost❌The price of one unit of the item purchased.
items.totalAmountNoTax❌Total cost of the item(s) excluding tax.
items.totalTaxAmount❌Total tax amount for the item(s).
items.totalAmount❌Total cost of the item(s) including tax.
items.totalDiscountAmount❌Total discount amount for the item(s).

Code example

{
    "merchant": {
        "taxReference": "VAT1999292",
    },
    "shipping": {
        "recipient": {
            "address": {
                "postalCode": "NW1 6XE",
                "countryCode": "GB"
            }
        },
        "sender": {
            "address": {
                "postalCode": "NW1 6XE"
            }
        }
    },
    "customer": {
        "reference": "CUST00000001"
    },
    "order": {
        "invoiceReference": "INV000123451",
        "salesTax": 3500,
        "discountAmount": 400,
        "shippingAmount": 150,
        "dutyAmount": 325,
        "orderDate": {
            "day": 1,
            "month": 3,
            "year": 2024
        },
        "taxExempt": false,
        "items": [
            {
                "productCode": "fff-1223",
                "commodityCode": "ABC123",
                "name": "Red Hat",
                "quantity": 4,
                "unitCost": 3500,
                "unitOfMeasure": "kg",
                "totalAmountNoTax": 2000,
                "totalTaxAmount": 2000,
                "totalAmount": 2000,
                "totalDiscountAmount": 2000
            }
        ]
    }
}

Airline Itinerary Data

Receive several cost and efficiency benefits when supplying detailed airline itinerary data as part of their authorization requests. You can submit these additional details in the authorization or settlement requests, depending on when your booking system generates the ticket number.

Benefits
Benefit
Description
Reduced interchange feesIf you are an airline merchant you can qualify lower interchange fees on transactions by providing airline-specific data, such as flight details, ticket numbers, and passenger information. Card networks often offer lower rates for transactions with enhanced data, reducing processing costs.
Enhanced fraud detectionDetailed transaction data allows card networks to better authenticate purchases, reducing fraud and chargeback rates. This is especially important for high-ticket airline transactions, where fraud prevention is critical.
Improved dispute managementWith comprehensive transaction details, card networks can better handle and resolve disputes. This reduces the time and effort you spend managing chargebacks and can lead to faster resolutions.
Increased customer trust and satisfactionProviding enhanced data improves transaction transparency, giving customers more confidence in their purchases. It also leads to more accurate transaction records on your customer's statements, minimizing confusion or disputes.
Compliance with industry standardsCard networks increasingly require detailed data in specific industries, like airlines, to maintain compliance with industry standards and processing requirements.
Parameters
ParameterRequired?Description
industryData.type✅Set to airline to provide itinerary specific information.
industryData.agentCode✅The IATA travel agency code.
industryData.agentName❌The name of the travel agent.
industryData.airlineCode✅The two character IATA airline code.
industryData.airlineName✅The name of the airline (displayed as it would be on a bill).
industryData.invoiceReference❌Billing Settlement Plan invoice reference.
industryData.passenger✅An object containing passenger details.
passenger.code✅The passenger code.
passenger.firstName✅Passenger's first name.
passenger.lastName✅Passenger's last name.
industryData.ticket✅An object containing ticket details.
ticket.number✅The ticket number.
ticket.restricted✅Typically, restricted airfares require approval and e-ticket processing within 24 hours of making the reservation, are not transferable if cancelled, and can have specific requirements on when or whether a cancelled ticket can be rebooked. You must define if the ticket is restricted, but this does not affect the payment flows.
ticket.issueDate❌An object containing the ticket's issue date.
ticket.issuerAddress✅An object containing the ticket issuer's address.
ticket.flightDetails❌An array with objects containing flight details. Each object represents one leg of a flight and you can submit up to four flight legs within this array.
flightDetails.carrierCode✅Same as industryData.airlineCode, the code represents the airline for the specific flight leg.
flightDetails.flightCode✅The flight code.
flightDetails.stopOver❌Set to true if this flight leg is a stopover, connecting different destinations.
flightDetails.departureAirport✅The three letter IATA Airport Code for the departure airport.
flightDetails.arrivalAirport✅The three letter IATA Airport Code for the destination airport.
flightDetails.departureDate✅An object containing the date of the departure.
flightDetails.fareClassCode✅The code used by airlines to identity a fare type.
flightDetails.fareBasisCode❌An optional extension to the fareClassCode for custom codes.
flightDetails.taxAmount✅The tax amount for this specific flight leg.

Code example

{
    "industryData": {
        "type": "airline",
        "agentCode": "0",
        "agentName": "Agent Name",
        "airlineCode": "MY",
        "airlineName": "MyAirline",
        "invoiceReference": "INV133328465768",
        "passenger":{
            "code": "12345678",
            "firstName": "John",
            "lastName": "Passenger"
        },
        "ticket":{
            "number": "123",
            "restricted": true,
            "issueDate": {
                "day": 1,
                "month": 1,
                "year": 2000
            },
            "issuerAddress": {
                "address1": "Airport venue 1",
                "city": "London",
                "countryCode": "GB",
                "postalCode": "AB1 CD5"
            },
            "flightDetails": [ 
                {
                "carrierCode": "M1",
                "flightCode": "501",
                "stopOver": false,
                "departureAirport": "LON",
                "arrivalAirport": "AMS",
                "departureDate": {
                    "day": 1,
                    "month": 1,
                    "year": 2000
                },
                "fareClassCode": "F",
                "fareBasisCode": "TMYA",
                "taxAmount": 3500
                },
                {
                "carrierCode": "M1",
                "flightCode": "501",
                "stopOver": false,
                "departureAirport": "AMS",
                "arrivalAirport": "LON",
                "departureDate": {
                    "day": 1,
                    "month": 1,
                    "year": 2000
                },
                "fareClassCode": "F",
                "fareBasisCode": "TMYA",
                "taxAmount": 3500
                }
              ],
          }
    }
}

Optional parameters

Example Customer Initiated Transaction (all parameters)

The requests below contain all the mandatory and optional fields needed for a successful authorization request.

Full request body:

{
    "transactionReference": "Memory265-13/08/1876",
    "channel": "ecom",
    "merchant": {
        "entity": "default",
        "paymentFacilitator": {
            "schemeId": "1111",
            "independentSalesOrganizationId": "222",
            "subMerchant": {
                "name": "James Moriarty",
                "reference": "12345",
                "address": {
                    "postalCode": "SW1 1AA",
                    "street": "Regent Street",
                    "city": "London",
                    "state": "WSM",
                    "countryCode": "GB"
                },
                "taxReference": "12345679",
                "email": "james.moriarty@email.com",
                "phoneNumber": "+447987 654321"
            }
        }
    },
    "instruction": {
        "requestAutoSettlement": {
            "enabled": false
        },
        "consumerBillPayment": true,
        "customerAgreement": {
            "type": "cardOnFile",
            "storedCardUsage": "used"
        },
        "narrative": {
            "line1": "Mind Palace",
            "line2": "Memory265-13/08/1876"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardHolderName": "Sherlock Holmes",
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "city": "London",
                "state": "Greater London",
                "postalCode": "NW1 6XE",
                "countryCode": "GB"
            },
            "expiryDate": {
                "month": 5,
                "year": 2035
            },
            "cvc": "123"
        },
        "debtRepayment": true,
        "requestAccountUpdater": true
    },
    "riskProfile": "https://try.access.worldpay.com/riskProfile/ewogIC",
    "authentication": {
        "threeDS": {
            "version": "2.1.0",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA==",
            "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
        }
    },
    "customer":{
        "documentReference": "ABCDE123"
  }
}

Response

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

Successful payment

You receive:

paymentInstrument

We return the "paymentInstrument" object, if we are able to provide information related to the underlying card used in the authorization request.

Note

If we return the paymentInstrument object, there is no guarantee that each field listed below will be returned with every transaction.

ParameterDescription
paymentInstrument.typeThe type of paymentInstrument. Eg:
  • card/plain+masked
  • card/network+masked
  • card/network
paymentInstrument.brandThe card brand. Sometimes referred to as the network or scheme. Eg:
  • "visa"
  • "mastercard"
  • "amex"
paymentInstrument.cardBinThe card bin. Eg:
444433
Note
this may contain the * character.
paymentInstrument.lastFourThe last four digits of the card. Eg:
1111
Note
this may contain the * character, where the card number is less than 16 digits.
paymentInstrument.expiryDate.monthThe card expiry month. Eg:
11
paymentInstrument.expiryDate.yearThe card expiry year. Eg:
2025
paymentInstrument.fundingTypeHow the card is funded. Eg:
  • credit
  • debit
  • prepaid
  • deferredDebit
  • chargeCard
paymentInstrument.categoryWhether the card is classed as a consumer card or a card for commercial use. Eg:
  • consumer
  • commercial
paymentInstrument.countryCodeThe alpha-2 ISO-3166 country code that the card was issued in. May return "N/A" where the country is unknown. Eg:
GB
paymentInstrument.issuerNameThe name of the card issuer. Eg:
Some Issuer PLC.
paymentInstrument.paymentAccountReferenceThe payment account reference (PAR) is a non-financial reference that uniquely identifies the underlying cardholder account. This allows you to correlate payments made with differing instruments (e.g. "card/plain" and "card/wallet+applepay"), where the same account funds the transaction. A PAR cannot be used to initiate a payment. Eg:
ABC123DEF456GHI789JKL123MNO45

Refused payment

You receive:

  • an HTTP code 201
  • an "outcome": "refused"
  • a refusalCode containing either our standard refusal codes or the rawCode (if enabled)
  • a refusalDescription which gives additional context on the refusal
  • an advice code (only if returned by the card scheme and acquirer)
  • risk factors (only returned if issuer identifies conflict)
  • an exemption result and reason (only if you supplied a risk profile to request an SCA exemption)
  • a paymentInstrument

Example response

{
    "outcome": "authorized",
    "riskFactors": [
        {
            "type": "cvc",
            "risk": "notSupplied"
        },
        {
            "type": "avs",
            "risk": "notChecked",
            "detail": "address"
        },
        {
            "type": "avs",
            "risk": "notChecked",
            "detail": "postcode"
        }
    ],
    "issuer": {
        "authorizationCode": "12345A"
    },
    "scheme": {
        "reference": "060720116005060"
    },
    "paymentInstrument": {
        "type": "card/plain+masked",
        "cardBin": "444433",
        "lastFour": "1111",
        "category": "consumer",
        "expiryDate": {
            "month": 5,
            "year": 2035
        },
        "cardBrand": "visa",
        "fundingType": "credit",
        "issuerName": "Some Issuer PLC",
        "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E"
    },
    "_links": {
        "cardPayments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI="
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
            }
        ]
    }
}

You can use the payments:settle action link to settle the payment straight away. You only receive this, if you set "requestAutoSettlement" to false in your initial request.
Alternatively you can cache the response and use the link to settle the payment later.

Note

In case of an error, you can get further information in our error reference.

riskFactors

To reduce the probability of processing a fraudulent payment, supply your customer's billing address and cvc in your authorization request.

We check this with your customer's issuing bank and include any conflicts in our response.

The riskFactors array is returned only if there is a risk associated with the authorization request. The riskFactors array returns an object for avs, cvc or riskProfile only if this information was included in the authorization request and if any risk was identified.

The table below describes the response parameters:

ParameterDescription
riskFactors.typeReturns avs, cvc or riskProfile
riskFactors.detailFor avs only.
Returns postcode or address
riskFactors.riskReturns notChecked, notMatched, notSupplied or verificationFailed

exemptions

An exemption result and reason if a risk profile was included in your authorization request.

The table below describes the response parameters:

ParameterDescription
exemption.resultReturns honored, outOfScope, rejected or unknown
exemption.reason
  • For honored, returns issuerHonored or unknown.
  • For outOfScope, returns merchantInitiatedTransaction, oneLegOut, moto, contactless or unknown.
  • For rejected, returns issuerRejected, highRisk, invalid, unsupportedScheme, notSubscribed, unsupportedAcquirer or unknown

Soft declines

The issuer responds with a soft decline (refusal code 65), if no exemption has been applied to the payment. The next logical step for this is to proceed with 3DS authentication.

Next steps

Settle or cancel a payment