Last Updated: 22 April 2025 | Change Log

Take repeat card payments

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 repeat card payments using our Card Payments API.

Merchant Initiated Transactions

You can take payments without the active participation of the customer according to an agreement previously made with the cardholder. These are known as Merchant Initiated Transactions (MITs).

POST to our merchantInitiatedTransactions endpoint to authorize a payment.

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

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

Note

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

Merchant Initiated Transaction request body:

{
    "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
            }
        },
        "customerAgreement": {
            "type": "subscription",
            "schemeReference": "000000000000020005060720116005061"
        }
    }
}

Important

Before taking a Merchant Initiated Payment, you must obtain prior agreement with the cardholder to store a card.

Schema (parameters)

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

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

merchantobjectrequired

An object that contains information about the merchant.

merchant.entitystring(entity)[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$required

Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for authentication and queries.

Example: "default"

merchant.mccstring(mcc)^\d{4}$

You can apply a merchant category code mcc to an individual request. You can only provide an mcc if we have enabled the dynamic mcc feature during boarding. If enabled but not provided, merchant.mcc defaults to a configured value.

merchant.paymentFacilitatorobject(paymentFacilitator)

An object containing Payment Facilitator information. This information is required for every authorization <b>only if you are a Payment Facilitator.</b>

merchant.taxReferencestring(taxReference)[ 1 .. 20 ] characters^(?!\s*$)[a-zA-Z0-9\s-]*$

Merchant's tax reference.

instructionobjectrequired

An object that contains all information related to the payment.

instruction.requestAutoSettlementobjectrequired

Indicates whether the transaction should be sent for settlement now true or later false at a time of your choosing.

instruction.requestAutoSettlement.enabledboolean

instruction.valueobject(value)required

An object that contains information about the value of the payment.

instruction.value.amountintegerrequired

The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50.

Example: 250

instruction.value.currencystringrequired

The three character currency code. See list of <a href="/products/access/reference/supported-countries-currencies#iso-currency-codes">supported currencies</a>

Example: "USD"

instruction.narrativeobject(narrative)required

The text that appears on your customer's statement. Used to identify the merchant.

instruction.narrative.line1stringrequired

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

instruction.narrative.line2string

Additional details about the payment e.g. order number, telephone number.

instruction.paymentInstrumentobjectrequired

instruction.paymentInstrument.typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

instruction.paymentInstrument.cardNumberstring[ 12 .. 19 ] charactersrequired

Contains your customer's card number.

instruction.paymentInstrument.cardHolderNamestring

The cardholder's name as it appears on their card.

instruction.paymentInstrument.expiryDateobjectrequired

Contains your customer's card expiry date.

instruction.paymentInstrument.expiryDate.monthintegerrequired

instruction.paymentInstrument.expiryDate.yearintegerrequired

instruction.paymentInstrument.billingAddressobject

Contains the billing address information.

instruction.customerAgreementobjectrequired

Contains specific customer agreements for the transaction.

instruction.customerAgreement.typestringrequired

The processing arrangement agreed with your customer. A subscription plan occurs at fixed time intervals.

Discriminator

instruction.customerAgreement.schemeReferencestring

Used by card schemes to link merchant initiated transactions (MITs) to the original customer initiated transaction (CIT). Supply the value returned by the card scheme in the original CIT.

Example: "MCCNDUVST1002 "

instruction.consumerBillPaymentboolean(consumerBillPayment)

Consumer Bill Payment is a flag which identifies a bill payment paid by providers on behalf of consumers.

instruction.requestAccountUpdaterboolean(requestAccountUpdater)

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.

instruction.debtRepaymentboolean(debtRepayment)

Debt Repayment Indicator is a flag which identifies a payment with the purpose of repaying a debt.

instruction.fundsTransferobject(fundsTransfer)

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

instruction.routingobject(routing)

An object containing specific routing preferences.

recipientobject(recipient)

Additional transaction recipient data.

shippingobject(shipping)

An object containing shipping details.

orderobject(order)

An object containing details about the order.

customerobject

Additional customer data.

industryDataobject(industryData)

An object containing industry specific order data.

riskProfilestring

Used to update the FraudSight data model to benefit future payments.

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

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.

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"
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 cancel, settle, partially settle or query your payment
a paymentInstrument

`paymentInstrument`

The "paymentInstrument" object is returned if we are able to provide information related to the underlying card used in the authorization request.

Note

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

Parameter	Description
`paymentInstrument.type`	The type of paymentInstrument. Eg: `card/plain+masked` `card/network+masked` `card/network`
`paymentInstrument.brand`	The card brand. Sometimes referred to as the network or scheme. Eg: `visa` `mastercard` `amex`
`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: `credit` `debit` `prepaid` `deferredDebit` `chargeCard`
`paymentInstrument.category`	Whether the card is classed as a consumer card or a card for commercial use. Eg: `consumer` `commercial`
`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 intiate 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)
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: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. 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:

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`

Next steps

Settle a payment
Refund a payment
Cancel a payment
Reverse a payment

Take repeat card payments

Merchant Initiated Transactions

Schema (parameters)

Enable additional features

Account Updater

Co-branded Cards

Financial Services (MCC 6012/6051)

Funding Transactions (AFT)

Airline data

Corporate Purchasing Data (Level 2 / 3)

Latin America Payments

View all features

Response

Successful payment

paymentInstrument

Refused payment

Example response

riskFactors

Next steps

Do you like our page?

`paymentInstrument`

`riskFactors`