Last Updated: 26 March 2024 | Change Log

Take a card payment

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.

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

{
    "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
            }
        }
    }
}

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

• Worldpay tokens
• Network tokens
• Checkout SDK
• Mobile Wallets

Parameter descriptions

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.

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.

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"
        }
    }
}

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.

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. 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"
        }
    }
}

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

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"

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"
        }
    }
}

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)

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

    "instruction": {        
        "customerAgreement": {
            "type": "installment",
            "installmentType": "latinAmerica",
            "installmentPlan": {
                "numberOfInstallments": 3
            }
        },
        "routing": {
            "fundingType": "debit"
        }
    },
    "customer": {
        "documentReference": "123-ABC"
    },
    "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)

    "instruction": {        
        "fundsTransfer": {
            "type": "walletLoad",
            "purpose": "crypto",
            "recipient": {
                "account": {
                    "type": "storedValueDigitalWallet",
                    "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 repayments, or consumer bill payments, you should supply additional details in the authorization request for compliance reasons.

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

Level 2 / Level 3 data

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

{
    "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

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

{
    "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
                }
              ],
          }
    }
}

Account Updater (DIY)

Request a real-time account update (Visa cards only) when using a previously stored card (subsequent card on file). This can only be supplied with customerAgreement.type set to cardOnFile and customerAgreement.storedCardUsage set to subsequent.

{
    "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
            }
        },
        "customerAgreement":{
            "type": "cardOnFile",
            "storedCardUsage": "subsequent"
        },
        "requestAccountUpdater": true
    }
}

Co-branded cards

Co-branded (or co-badged) payment cards are cards that integrate two or more payment brands and allow the transaction to be processed through either of its payment networks.

Response

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 to false in the authorization request and the outcome is "authorized"
  • refund, partially refund, reverse or query a payment when requestAutoSettlement was set to true in the authorization request and the outcome is "Sent for Settlement"
• 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.

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.

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:

exemptions

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

The table below describes the response parameters:

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