Last Updated: 22 April 2025 | Change Log
Take a card payment
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.
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)
A unique reference generated by you that is used to identify a payment throughout its lifecycle.
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.
An object that contains information about the merchant.
Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.
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.
An object containing Payment Facilitator information. This information is required for every authorization <b>only if you are a Payment Facilitator.</b>
Merchant's tax reference.
An object that contains all information related to the payment.
Indicates whether the transaction should be sent for settlement now true
or later false
at a time of your choosing.
An object that contains information about the value of the payment.
The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.
The three character currency code. See list of <a href="/products/access/reference/supported-countries-currencies#iso-currency-codes">supported currencies</a>
Set to true
for an estimated authorization value, which you can increase at a later stage. requestAutoSettlement
must be false
for estimated authorizations.
The text that appears on your customer's statement. Used to identify the merchant.
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).
Additional details about the payment e.g. order number, telephone number.
An identifier for the paymentInstrument
being used.
- card/plain
- card/token
- card/networkToken
- card/checkout
- card/wallet+applepay
- card/wallet+googlepay
- card/networkToken+applepay
- card/networkToken+googlepay
Contains your customer's card number.
The cardholder's name as it appears on their card.
Contains your customer's card expiry date.
Contains the billing address information.
CVC is a unique set of 3 or 4 numbers used to verify the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.
Contains specific customer agreements for the transaction.
Consumer Bill Payment is a flag which identifies a bill payment paid by providers on behalf of consumers.
Debt Repayment Indicator is a flag which identifies a payment with the purpose of repaying a debt.
Allows you to request a real-time account update when using a previously stored card. You can only use this with customerAgreement
transactions with a storedCardUsage
value of subsequent
. If the stored card details that you provided for the transaction are no longer valid and new credentials are available, the authorization will be processed with the new card and its details will be returned in the updatedPaymentInstrument
object in the response.
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)).
An object containing specific routing preferences.
Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments.
An object containing 3DS and/or Network Token authentication details.
An object for applying exemptions. If you are applying a TRA exemption from us, use the riskProfile
object
An object containing shipping details.
An object containing details about the order.
Additional transaction recipient data.
Additional customer data.
An object containing industry specific order data.
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.
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.
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"
}
}
}
Parameter | Required | Description |
---|---|---|
instruction.customerAgreement | ❌ | An object containing details about processing agreements made with your customer, i.e.:
|
customerAgreement.type | ✅ | The processing arrangement agreed with your customer. Possible values:
|
customerAgreement.storedCardUsage | Mandatory for types:
| Possible values:
|
customerAgreement.installmentType | Mandatory where customerAgreement.type = installment | Possible values:
|
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.
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
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"
}
}
}
Parameter | Required | Description |
---|---|---|
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.
|
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"
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 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 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"
}
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"
}
}
}
3DS data cannot be supplied for MOTO transactions.
Parameter | Required | Description |
---|---|---|
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:
Note Required for Mastercard's Identity Check transactions in Authorization. |
authentication.threeDS.eci | ✅ | Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS verification.
|
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.
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.
For Cartes Bancaires authorizations only. |
authentication.threeDS.authenticationFlow | ❌ |
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.
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. |
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
View all features
Response
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"
- 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:
- settle, partially settle, cancel, or query a payment when
requestAutoSettlement
was set tofalse
in the authorization request and theoutcome
is"authorized"
- refund, partially refund, reverse or query a payment when
requestAutoSettlement
was set totrue
in the authorization request and theoutcome
is"Sent for Settlement"
- settle, partially settle, cancel, or query a payment when
- 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.
If we return the paymentInstrument
object, there is no guarantee that each field listed below will be returned with every transaction.
Parameter | Description |
---|---|
paymentInstrument.type | The type of paymentInstrument. Eg:
|
paymentInstrument.brand | The card brand. Sometimes referred to as the network or scheme. Eg:
|
paymentInstrument.cardBin | The card bin. Eg:444433 Note this may contain the * character. |
paymentInstrument.lastFour | The 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.month | The card expiry month. Eg: 11 |
paymentInstrument.expiryDate.year | The card expiry year. Eg: 2025 |
paymentInstrument.fundingType | How the card is funded. Eg:
|
paymentInstrument.category | Whether the card is classed as a consumer card or a card for commercial use. Eg:
|
paymentInstrument.countryCode | The alpha-2 ISO-3166 country code that the card was issued in. May return "N/A" where the country is unknown. Eg: GB |
paymentInstrument.issuerName | The name of the card issuer. Eg: Some Issuer PLC. |
paymentInstrument.paymentAccountReference | The 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
object
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: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.
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:
Parameter | Description |
---|---|
riskFactors.type | Returns avs , cvc or riskProfile |
riskFactors.detail | For avs only.Returns postcode or address |
riskFactors.risk | Returns 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:
Parameter | Description |
---|---|
exemption.result | Returns honored , outOfScope , rejected or unknown |
exemption.reason |
|
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