Skip to content
APIs/Card Payments/Take a card payment

Last updated: 01 September 2026 | 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.

Note

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

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

Code examples

{
    "transactionReference": "Memory265-13/08/1876",
    "channel": "ecom",
    "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
            }
        }
    }
}

Schema (parameters)

transactionReferencestring, [ 1 .. 64 ] characters(transactionReference)^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$required

A unique reference generated by you that is used to identify a payment throughout its lifecycle.

orderReferencestring, [ 1 .. 64 ] characters(orderReference)^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~/+]*$

A reference, generated by you, 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
Example:"order-12345"
channelstringrequired

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 transaction. Note: 3DS authentication cannot be supplied for MOTO payments.

Enum:"ecom""moto"
merchantobjectrequired

An object that contains information about the merchant.

instructionobjectrequired

An object that contains all information related to the payment.

riskProfilestring

Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments.

If using either the FraudSight or Exemptions API you must provide this.

Example:"https://try.access.worldpay.com/riskProfile/{linkData}"
authenticationobject

An object containing authentication details.

exemptionobject(exemption)
shippingobject(shipping)

An object containing shipping details.

orderobject(order)

An object containing details about the order.

recipientobject(recipient)

Additional transaction recipient data.

customerobject

Additional customer data.

industryDataobject(industryData)

For more information about the accepted payment instruments, see our dedicated guidance:


Store a card

If you are storing your customer's payment details for future use, you must indicate this using the customerAgreement object. Additionally, 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 (i.e. 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",
    "channel": "ecom",
    "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"
        }
    },
    "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",
    "channel": "ecom",
    "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"
        }
    },
    "authentication": {
        "threeDS": {
            "eci": "05",
            "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAA3=",
            "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999",
            "version": "2.2.0"
        }
    }
}
ParameterRequired?Description
instruction.customerAgreement❌An object containing details about processing agreements made with your customer, i.e.:
  • An agreement to store the customer's paymentInstrument for future processing (e.g. set up a subscription plan or store a card on file)
  • An agreement to set up an installment schedule (for Latin America payments)
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 for the first time
  • used - for using a previously stored card
customerAgreement.installmentTypeMandatory where customerAgreement.type = installmentPossible 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
Note

See our guidance on how to Create a Network Token.

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


Example network token requests:

{
    "transactionReference": "Memory265-13/08/1876",
    "channel": "ecom",
    "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
            }
        }
    },
    "authentication": {
        "networkToken": {
            "cryptogram": "MAAAAAAAAAAAAAAAAAAAAAAAAAB=",
            "eci": "05"
        }
    }
}
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

FraudSight

Linking the payment

If using the FraudSight API you must apply the riskProfile from the assessment response in the card payment request. This links the risk assessment to the payment and allows the data model to mature and identify future fraudulent transactions.

See linking the FraudSight assessment for details.

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

SCA Exemptions

Granted by Worldpay

Apply your Worldpay granted exemption (from Exemptions or FraudSight) using the riskProfile. This allows the exemption to be applied to your payment authorization.

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

Granted by 3rd party TRA (external)

To use exemptions granted by a 3rd party Transaction Risk Analysis (TRA) tool.

This is not enabled by default, please contact your Worldpay Implementation Manager.

Do not send externally granted TRA exemptions without approval from us and confirmation that we have fully enabled it.

"exemption": {
    "type": "external",
    "request": { 
        "placement":  "authentication",  
        "type": "lowRisk" 
    }
}

3DS authentication outage exemption

This is not enabled by default, please contact your Worldpay Implementation Manager.

If 3DS suffers from a recognized downstream outage, you can apply an authenticationOutage exemption. Liability shift is not offered, but it increases the chance of an authorized outcome.

"exemption": {
    "type": "authenticationOutage"
}

View the full exemption object schema

3DS

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",
    "channel": "ecom",
    "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
            }
        }
    },
    "authentication": {
        "threeDS": {
            "eci": "05",
            "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAA3=",
            "transactionId": "a09b446d-5c0d-4003-9c99-21fb73d75999",
            "version": "2.2.0"
        }
    }
}
Warning

You cannot re-use the authenticationValue in multiple authorization requests. Re-using the authenticationValue will result in issuer declines and may incur fees.

Note

3DS data cannot be supplied for MOTO transactions.

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. Possible values for 3DS2:
  • 2.1.0
  • 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 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
  • noChallengeRequestedTRAPerformed

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.status❌Indicates the outcome of the authentication or verification request.
  • Y - Successful authentication
  • N - Failed authentication
  • U - Unable to complete authentication
  • A - Successful attempts authentication
  • I - Exemption acknowledged

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.
authentication.threeDS.exemptionCode❌A code indicating the authentication exemption reason.
  • gAAA - Issuer transaction risk analysis
  • QAAA - Recurring operations with identical amounts and a specified duration
  • IAAA - Delegated authentication
  • EAAA - Authentication implementation is not technically possible
  • CAAA - Low amount
  • BAAA - Acceptor/acquirer transaction risk analysis
  • AgAA - Trusted beneficiary
  • AQAA - Secure corporate payment process and protocol
  • AAgA - Unattended terminal for transport fares and parking fees
  • AAQA - Out of RTS SCA scope
  • AAIA - Other cases
  • AAEA - Transaction risk analysis - merchant in CB Low Risk Merchant program

For Cartes Bancaires authorizations only.

Enable additional features

Account Updater

Reduce declines and improve your customer's experience by automatically retrieving updated card details in real time.

Co-branded Cards

Take payments from cards that carry multiple card brands.

Financial Services (MCC 6012/6051)

Supply additional mandatory data if you offer financial services, debt repayments, or consumer bill payments.

Funding Transactions (AFT)

Take Account Funding Transactions (AFTs) to pull funds from a card account to another destination.

Airline data

Supply detailed airline itinerary data to achieve several cost and efficiency benefits.

Corporate Purchasing Data (Level 2 / 3)

Submit additional order, tax, and line item data in your payment authorization and settlement requests where your customer is using a commercial or purchasing card.

Latin America Payments

Take payments in Latin America, including regional installment plan options, combo cards, and supplying customer document references.

MOTO transactions

Take Mail Order/ Telephone Order payments.

Partial authorizations

Accept authorizations for partial amounts.

View all features

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:

  • an HTTP code 201
  • an "outcome": "authorized" or "Sent for Settlement"
  • a paymentId - a unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions
  • a commandId - a unique identifier generated by us for a single instance of an interaction (command) with our API
  • 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)
  • an issuer authorization code
  • links to either:
  • a paymentInstrument object

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. E.g.:
  • card/plain+masked
  • card/network+masked
  • card/network
paymentInstrument.brandThe card brand. Sometimes referred to as the network or scheme. E.g.:
  • visa
  • mastercard
  • amex
paymentInstrument.cardBinThe card bin. E.g.:
444433
Note
this may contain the * character.
paymentInstrument.lastFourThe last four digits of the card. E.g.:
1111
Note
this may contain the * character, where the card number is less than 16 digits.
paymentInstrument.expiryDate.monthThe card expiry month. E.g.:
11
paymentInstrument.expiryDate.yearThe card expiry year. E.g.:
2025
paymentInstrument.fundingTypeHow the card is funded. E.g.:
  • credit
  • debit
  • prepaid
  • deferredDebit
  • chargeCard
paymentInstrument.categoryWhether the card is classed as a consumer card or a card for commercial use. E.g.:
  • 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. E.g.:
GB
paymentInstrument.issuerNameThe name of the card issuer. E.g.:
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. E.g.:
ABC123DEF456GHI789JKL123MNO45
paymentInstrument.debitNetworkThe debit network that the transaction was routed through. Returned optionally for subscribing merchants. See our API reference for all possible values.
Marketplaces

If you follow a Marketplace flow, ensure you now split your payment through our Split Payments API, to guarantee an automated payout to the party.

Refused payment

You receive:

  • an HTTP code 201
  • an "outcome": "refused"
  • a paymentId - a unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions
  • a commandId - a unique identifier generated by us for a single instance of an interaction (command) with our API
  • 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 object

Example response

{
    "outcome": "authorized",
    "paymentId": "pay-fh47sbnaKR28AuocN28x0",
    "commandId": "cmdfHx982Nbhsklg91hsvlrv0",
    "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:partialCancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/eyJrIjoiazNhYjYzMiJ9"
        },
        "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 a payment
Refund a payment
Cancel a payment
Reverse a payment