Last Updated: 04 December 2024 | 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 cardholder 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.

Parameter descriptions

Parameter	Required	Description
`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.merchantId` `subMerchant.address.postalcode` `subMerchant.address.street` `subMerchant.address.city` `subMerchant.address.countryCode` `subMerchant.telephone` (mandatory for Amex) `subMerchant.email` (mandatory for Amex) `subMerchant.taxReference` You can find more formatting information here.
`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.debtRepayment`	❌	DRI 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.
`instruction.requestAutoSettlement.enabled`	✅	A boolean value to indicate whether the transaction should be sent for settlement now (`true`), or later using an action link (`false`)
`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: `subscription` `installment` `unscheduled` `reauthorization` `resubmission` `noShow` `delayedCharge`
`customerAgreement.schemeReference`	❌	Unique reference provided by card schemes that identifies a repeat payment agreement between you and the customer. For Visa and Mastercard cards, you should provide the scheme reference returned in the original store card transaction made by the customer.
`customerAgreement.storedCardUsage`	❌	Indicate whether the transaction is using a stored card. MITs with the following `customerAgreement.type` values always use a stored card: `subscription` `installment` `unscheduled` However, the following `customerAgreement.type` values do not necessarily use a stored card: `reauthorization` `resubmission` `noShow` `delayedCharge` In this case, simply omit `customerAgreement.storedCardUsage`. Possible values: `subsequent`
`customerAgreement.schemeReference`	❌	Unique reference provided by card schemes that identifies a repeat payment agreement between you and the customer. For Visa and Mastercard cards, you should provide the scheme reference returned in the original store card transaction made by the customer.
`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.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.
`riskProfile`	❌	Used to apply the SCA exemption in the payment request and update the FraudSight data model to benefit future payments.
`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

Optional parameters

Example Merchant 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",
    "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
        },
        "customerAgreement": {
            "type": "subscription",
            "schemeReference": "060720116005060"
        },
        "narrative": {
            "line1": "Mind Palace",
            "line2": "Memory265-13/08/1876"
        },
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "debtRepayment": true,
        "consumerBillPayment": true,
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardHolderName": "John Appleseed",
            "billingAddress": {
                "address1": "221B Baker Street",
                "address2": "Marylebone",
                "address3": "Westminster",
                "city": "London",
                "state": "Greater London",
                "postalCode": "NW1 6XE",
                "countryCode": "GB"
            },
            "expiryDate": {
                "month": 5,
                "year": 2035
            }
        },
        "requestAccountUpdater": true
    },
    "customer":{
        "documentReference": "ABCDE123"
    },
    "recipient": {
        "accountReference":"1234",
        "lastName":"abc",
        "address": {
            "postalCode": "DH1 3LE"
        },
        "dateOfBirth": {
            "day": 29,
            "month": 4,
            "year": 1985
        }
    }
}

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: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 or cancel a payment

Take repeat card payments

Merchant Initiated Transactions

Parameter descriptions

Optional parameters

Response

Successful payment

paymentInstrument

Refused payment

Example response

riskFactors

Do you like our page?

`paymentInstrument`

`riskFactors`