Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Card Payments (7)

Card Payments root resource, returns links to available payments actions.

Download OpenAPI description
Languages
Servers
testing (try)
https://try.access.worldpay.com/
live
https://access.worldpay.com/

Take a card payment

Request

Take online card payments using our Card Payments API.

Headers
Content-Typestringrequired
Example:

application/vnd.worldpay.payments-v7+json

Acceptstringrequired
Example:

application/vnd.worldpay.payments-v7+json

Bodyapplication/vnd.worldpay.payments-v7+json
transactionReferencestringrequired

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.

entitystringrequired

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

mccstring

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.

paymentFacilitatorobject

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

schemeIdstringrequired
independentSalesOrganizationIdstring
subMerchantobjectrequired
instructionobjectrequired

An object that contains all information related to the payment.

requestAutoSettlementobjectrequired

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

enabledboolean
valueobjectrequired

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

amountintegerrequired

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

currencystringrequired

The three digit currency code.

narrativeobjectrequired

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

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

line2string

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

paymentInstrumentobjectrequired
typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"
Discriminator
cardNumberstringrequired

Contains your customer's card number.

cardHolderNamestring

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

expiryDateobjectrequired

Contains your customer's card expiry date.

billingAddressobject

Contains the billing address information.

cvcstring

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.

customerAgreementobject

Contains specific customer agreements for the transaction.

typestringrequired

The processing arrangement agreed with your customer.

Discriminator
storedCardUsagestringrequired

Set to first to store a card or subsequent to use a previously stored card.

Enum"first""subsequent"
consumerBillPaymentboolean

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

debtRepaymentboolean

Debt Repayment Indicator is a flag which identifies a payment as being for the purpose of repaying a debt.

fundsTransferobject

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

typestringrequired

Specify the type of the funds transfer.

Enum"accountToAccount""cash""debitTopUp""disbursement""payrollDisbursement""personToPerson""prePaidTopUp""stagedDigitalWallet""transfer"
purposestring

Specify the purpose of the funds transfer.

Enum"crowdLending""crypto""education""emergency""familySupport""gift""medical""salary""savings""travel"
recipientobject

An object containing details about the recipient of funds.

senderobject

An object containing details about the sender of funds.

channelstringrequired

Interaction between the cardholder and the merchant. 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"
riskProfilestring

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

authentication3DS (object) or networkToken (object)

An object containing 3DS or Network Token authnentication of the customer.

One of:

An object containing 3DS or Network Token authnentication of the customer.

threeDSobject
versionstringrequired

The version of 3DS used to process the transaction.

ecistringrequired

Electronic Commerce Indicator (ECI).

authenticationValuestring

Required, if authentication.eci value is 01, 02, 05 or 06. A cryptographic value that provides evidence of the outcome of a 3DS verification..

transactionIdstring

Required, if authentication.eci value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer.

recipientobject

Additional transaction recipient data.

accountReferencestring

Partial account number of the recipient.

lastNamestring

Last name of the recipient

addressobject

Address of the recipient

postalCodestringrequired
dateOfBirthobject

Birth date of the recipient

dayintegerrequired
monthintegerrequired
yearintegerrequired
customerobject

Additional customer data.

documentReferencestring

Required for domestic processing in some Latin American countries.

application/vnd.worldpay.payments-v7+json

Payment authorization for GBP 2.50

{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "MindPalaceLtd" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "MindPalace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } } }, "channel": "ecom" }

Responses

The payment authorization has been successfully created

Bodyapplication/vnd.worldpay.payments-v6.hal+json
outcomestringrequired

Outcome of the request.

Discriminator
exemptionobject

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

resultstringrequired
reasonstringrequired
issuerobject

An object containing information returned by the issuer.

authorizationCodestringrequired
paymentInstrumentobject

Details of the paymentInstrument used.

typestring
cardBinstring
lastFourstring
categorystring
issuerNamestring
fundingTypestring
cardBrandstring
paymentAccountReferencestring
expiryDateobject
monthinteger
yearinteger
riskFactorsArray of objects

Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified.

typestringrequired
Enum"avs""cvc""riskProfile"
riskstringrequired
Enum"notChecked""notMatched""notSupplied""verificationFailed"
detailstring
Enum"address""postcode"
schemeobject

An object containing information returned by the scheme.

referencestringrequired
Response
application/vnd.worldpay.payments-v6.hal+json

Payment authorization for GBP 2.50 with a successful outcome

{ "outcome": "authorized", "riskFactors": [ { "type": "cvc", "risk": "notSupplied" }, { "type": "avs", "risk": "notChecked", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ], "issuer": { "authorizationCode": "675725" }, "scheme": { "reference": "000000000000020005060720116005062" }, "paymentInstrument": { "type": "card/plain+masked", "cardBin": "555555", "lastFour": "4444", "category": "consumer", "expiryDate": { "month": 9, "year": 2029 }, "cardBrand": "mastercard", "fundingType": "credit", "issuerName": "UNKNOWN", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/" }, "curies": [ { "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}", "templated": true } ] } }

Take a repeat card payment

Request

Take online payments using our Card Payments API.

Headers
Content-Typestringrequired
Example:

application/vnd.worldpay.payments-v7+json

Acceptstringrequired
Example:

application/vnd.worldpay.payments-v7+json

Bodyapplication/vnd.worldpay.payments-v7+json
transactionReferencestringrequired

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.

entitystringrequired

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

mccstring

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.

paymentFacilitatorobject

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

schemeIdstringrequired
independentSalesOrganizationIdstring
subMerchantobjectrequired
instructionobjectrequired

An object that contains all information related to the payment.

requestAutoSettlementobjectrequired

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

enabledboolean
valueobjectrequired

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

amountintegerrequired

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

currencystringrequired

The three digit currency code.

narrativeobjectrequired

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

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

line2string

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

paymentInstrumentobjectrequired
typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"
Discriminator
cardNumberstringrequired

Contains your customer's card number.

cardHolderNamestring

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

expiryDateobjectrequired

Contains your customer's card expiry date.

billingAddressobject

Contains the billing address information.

customerAgreementobjectrequired

Contains specific customer agreements for the transaction.

typestringrequired

The processing arrangement agreed with your customer.

Discriminator
schemeReferencestring

A reference returned by the card scheme.

consumerBillPaymentboolean

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

debtRepaymentboolean

Debt Repayment Indicator is a flag which identifies a payment as being for the purpose of repaying a debt.

fundsTransferobject

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

typestringrequired

Specify the type of the funds transfer.

Enum"accountToAccount""cash""debitTopUp""disbursement""payrollDisbursement""personToPerson""prePaidTopUp""stagedDigitalWallet""transfer"
purposestring

Specify the purpose of the funds transfer.

Enum"crowdLending""crypto""education""emergency""familySupport""gift""medical""salary""savings""travel"
recipientobject

An object containing details about the recipient of funds.

senderobject

An object containing details about the sender of funds.

recipientobject

Additional transaction recipient data.

accountReferencestring

Partial account number for the recipient.

lastNamestring

Last name of the recipient

addressobject

Address of the recipient

postalCodestringrequired
dateOfBirthobject

Birth date of the recipient

dayintegerrequired
monthintegerrequired
yearintegerrequired
customerobject

Additional customer data.

documentReferencestring

Required for domestic processing in some Latin American countries.

application/vnd.worldpay.payments-v7+json

Recurring authorization for subscriptions

{ "transactionReference": "Memory265-13/08/1876", "merchant": { "entity": "MindPalaceLtd" }, "instruction": { "requestAutoSettlement": { "enabled": false }, "narrative": { "line1": "MindPalace" }, "value": { "currency": "GBP", "amount": 250 }, "paymentInstrument": { "type": "card/plain", "cardNumber": "4444333322221111", "expiryDate": { "month": 5, "year": 2035 } }, "customerAgreement": { "type": "subscription", "schemeReference": "MCCOLXT1C0104" } } }

Responses

The payment authorization has been successfully created

Bodyapplication/vnd.worldpay.payments-v6.hal+json
outcomestringrequired

Outcome of the request.

Discriminator
exemptionobject

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

resultstringrequired
reasonstringrequired
issuerobject

An object containing information returned by the issuer.

authorizationCodestringrequired
paymentInstrumentobject

Details of the paymentInstrument used.

typestring
cardBinstring
lastFourstring
categorystring
issuerNamestring
fundingTypestring
cardBrandstring
paymentAccountReferencestring
expiryDateobject
monthinteger
yearinteger
riskFactorsArray of objects

Any risk factors which have been identified for the authorization. This section will not appear if no risks are identified.

typestringrequired
Enum"avs""cvc""riskProfile"
riskstringrequired
Enum"notChecked""notMatched""notSupplied""verificationFailed"
detailstring
Enum"address""postcode"
schemeobject

An object containing information returned by the scheme.

referencestringrequired
Response
application/vnd.worldpay.payments-v6.hal+json

Payment authorization for GBP 2.50 with a successful outcome

{ "outcome": "authorized", "riskFactors": [ { "type": "cvc", "risk": "notSupplied" }, { "type": "avs", "risk": "notChecked", "detail": "address" }, { "type": "avs", "risk": "notChecked", "detail": "postcode" } ], "issuer": { "authorizationCode": "675725" }, "scheme": { "reference": "000000000000020005060720116005062" }, "paymentInstrument": { "type": "card/plain+masked", "cardBin": "555555", "lastFour": "4444", "category": "consumer", "expiryDate": { "month": 9, "year": 2029 }, "cardBrand": "mastercard", "fundingType": "credit", "issuerName": "UNKNOWN", "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E" }, "_links": { "cardPayments:cancel": { "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/" }, "cardPayments:settle": { "href": "https://try.access.worldpay.com/payments/settlements/full/" }, "cardPayments:partialSettle": { "href": "https://try.access.worldpay.com/payments/settlements/partials/" }, "cardPayments:events": { "href": "https://try.access.worldpay.com/payments/events/" }, "curies": [ { "name": "cardPayments", "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}", "templated": true } ] } }

Manage Payments

Operations

Query a Payment

Operations

Query payment status

Request

Send a request to find out the current status of your payment after it has been authorized using the events action link. Note: It can take up to 15 minutes for a payment event to update.

Path
linkDatastringrequired

Action link that's received in your request

No request payload

Responses

Retrieve the last event of a payment

Bodyapplication/vnd.worldpay.payments-v7+json
lastEventstringrequired
Response
application/vnd.worldpay.payments-v7+json

Querying a payment event with a transaction reference