Card Payments (7)

Take online payments with our Card Payments API.

Authentication Header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to your by your Implementation Manager.

You must use the Authorization header for any request you send to our Card Payments APIs, unless you are using client certificate authenticating with SSL/TLS.

Accept/Content-Type Header

Content-Type: application/vnd.worldpay.payments-v7+json
Accept: application/vnd.worldpay.payments-v7+json

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our Card Payments APIs.

We require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT.

DNS Whitelisting
Whitelist the following URLs:

https://try.access.worldpay.com/
https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting.

Download OpenAPI description

openapi.json

openapi.yaml

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

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

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

channelstringrequired

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.

Enum"ecom""moto"

merchantobjectrequired

An object that contains information about the merchant.

entitystring[ 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"

mccstring^\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.

paymentFacilitatorobject

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

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

Merchant's tax reference.

instructionobjectrequired

An object that contains all information related to the payment.

requestAutoSettlementobjectrequired

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

valueobjectrequired

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

narrativeobjectrequired

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

paymentInstrumentobjectrequired

customerAgreementobject

Contains specific customer agreements for the transaction.

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 with the purpose of repaying a debt.

requestAccountUpdaterboolean

Allows you to request a real-time account update (Visa cards only) when using a previously stored card. You can only use this on subsequest card requests.

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

routingobject

An object containing specific routing preferences.

riskProfilestring

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

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

authenticationobject

An object containing 3DS and/or Network Token authentication details.

threeDSobject

networkTokenobject

Network Token authentication. Only allowed for card/networkToken transactions.

shippingobject

An object containing shipping details.

senderobject

recipientobject

orderobject

An object containing details about the order.

taxExemptboolean

A flag to indicate whether the purchase is exempt from tax. Must be set to true if order.salesTax is 0

orderDateobject

Date of the order.

itemsArray of objects

Array of order items. You can send up to 99 individual order objects within this array.

dutyAmountinteger

Total amount of duty costs for the order.

salesTaxinteger

Total amount of sales tax for the order. Must be provided if merchant.taxReference is supplied.

shippingAmountinteger

Total amount of shipping costs for the order.

invoiceReferencestring[ 1 .. 15 ] characters

Invoice reference for the order.

discountAmountinteger

Total amount of discounts for the order.

recipientobject

Additional transaction recipient data.

accountReferencestring

Partial account number of the recipient.

lastNamestring

Last name of the recipient

addressobject

Address of the recipient

dateOfBirthobject

Birth date of the recipient

customerobject

Additional customer data.

documentReferencestring

Required for domestic processing in some Latin American countries.

referencestring

Merchant-generated customer reference.

industryDataobject

An object containing industry specific order data.

typestringrequired

Value"airline"

airlineNamestringrequired

The name of the airline (displayed as it would be on a bill).

ticketobjectrequired

An object containing ticket details.

agentNamestring

The name of the travel agent.

agentCodestringrequired

The IATA travel agency code.

invoiceReferencestring

Billing Settlement Plan invoice reference.

airlineCodestringrequired

The two character IATA airline code.

passengerobjectrequired

An object containing passenger details.

application/vnd.worldpay.payments-v7+json

Payment authorization for GBP 2.50

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "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-v7+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

updatedPaymentInstrumentobject

Details of the updated payment instrument.

accountUpdaterMessagestring

typestring

lastFourstring

cardBinstring

expiryDateobject

cardBrandstring

fundingTypestring

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

Result of the verification.

Enum"notChecked""notMatched""notSupplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

An object containing information returned by the card scheme.

referencestringrequired

The reference returned by the scheme for this particular payment authorization. The scheme reference returned in a customer initiated transaction should be provided in all subsequent merchant initiated transactions.

Response

application/vnd.worldpay.payments-v7+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": "MCCOLXT1C0104  "
  },
  "paymentInstrument": {
    "type": "card/plain+masked",
    "cardBin": "555555",
    "lastFour": "4444",
    "category": "consumer",
    "countryCode": "GB",
    "expiryDate": {
      "month": 9,
      "year": 2029
    },
    "cardBrand": "mastercard",
    "fundingType": "credit",
    "issuerName": "AN ISSUING BANK LTD",
    "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E"
  },
  "_links": {
    "cardPayments:cancel": {
      "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/"
    },
    "cardPayments:partialCancel": {
      "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/"
    },
    "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

transactionReferencestring[ 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.

entitystring[ 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"

mccstring^\d{4}$

paymentFacilitatorobject

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

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

Merchant's tax reference.

instructionobjectrequired

An object that contains all information related to the payment.

requestAutoSettlementobjectrequired

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

valueobjectrequired

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

narrativeobjectrequired

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

paymentInstrumentobjectrequired

customerAgreementobjectrequired

Contains specific customer agreements for the transaction.

consumerBillPaymentboolean

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

requestAccountUpdaterboolean

Allows you to request a real-time account update (Visa cards only) when using a previously stored card. You can only use this on subsequent card requests.

debtRepaymentboolean

Debt Repayment Indicator is a flag which identifies a payment with 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 (AFT)).

routingobject

An object containing specific routing preferences.

recipientobject

Additional transaction recipient data.

accountReferencestring

Partial account number for the recipient.

lastNamestring

Last name of the recipient.

addressobject

Address of the recipient.

dateOfBirthobject

Birth date of the recipient.

shippingobject

An object containing shipping details.

senderobject

recipientobject

orderobject

An object containing details about the order.

taxExemptboolean

A flag to indicate whether the purchase is exempt from tax. Must be set to true if order.salesTax is 0

orderDateobject

Date of the order.

itemsArray of objects

Array of order items. You can send up to 99 individual order objects within this array.

dutyAmountinteger

Total amount of duty costs for the order.

salesTaxinteger

Total amount of sales tax for the order. Must be provided if merchant.taxReference is supplied.

shippingAmountinteger

Total amount of shipping costs for the order.

invoiceReferencestring

Invoice reference for the order.

discountAmountinteger

Total amount of discounts for the order.

customerobject

Additional customer data.

documentReferencestring

Required for domestic processing in some Latin American countries.

referencestring

Merchant-generated customer reference.

industryDataobject

An object containing industry specific order data.

typestringrequired

Value"airline"

airlineNamestringrequired

The name of the airline (displayed as it would be on a bill).

ticketobjectrequired

An object containing ticket details.

agentNamestring

The name of the travel agent.

agentCodestringrequired

The IATA travel agency code.

invoiceReferencestring

Billing Settlement Plan invoice reference.

airlineCodestringrequired

The two character IATA airline code.

passengerobjectrequired

An object containing passenger details.

riskProfilestring

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

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

application/vnd.worldpay.payments-v7+json

MIT authorization for subscriptions

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "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-v7+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

updatedPaymentInstrumentobject

Details of the updated payment instrument.

accountUpdaterMessagestring

typestring

lastFourstring

cardBinstring

expiryDateobject

cardBrandstring

fundingTypestring

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

Result of the verification.

Enum"notChecked""notMatched""notSupplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

An object containing information returned by the card scheme.

referencestringrequired

Response

application/vnd.worldpay.payments-v7+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": "MCCOLXT1C0104  "
  },
  "paymentInstrument": {
    "type": "card/plain+masked",
    "cardBin": "555555",
    "lastFour": "4444",
    "category": "consumer",
    "countryCode": "GB",
    "expiryDate": {
      "month": 9,
      "year": 2029
    },
    "cardBrand": "mastercard",
    "fundingType": "credit",
    "issuerName": "AN ISSUING BANK LTD",
    "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

Headers

Content-Typestringrequired

Example: application/vnd.worldpay.payments-v7+json

Acceptstringrequired

Example: application/vnd.worldpay.payments-v7+json

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

{
  "lastEvent": "Authorized",
  "_links": {
    "cardPayments:cancel": "/payments/authorizations/cancellations/:linkData",
    "cardPayments:settle": "/payments/settlements/full/:linkData",
    "cardPayments:partialSettle": "/payments/settlements/partials/:linkData",
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Query payment status Recovery

Request

Send a request to find out the current status of your payment after it has been authorized using the events action link. This action is only to be used for recovery purposes. Use this action if your authorization requests timed out. The response determines if your authorization request was successful and your next available actions are returned.

Headers

Content-Typestringrequired

Example: application/vnd.worldpay.payments-v7+json

Acceptstringrequired

Example: application/vnd.worldpay.payments-v7+json

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

{
  "lastEvent": "Authorized",
  "_links": {
    "cardPayments:cancel": "/payments/authorizations/cancellations/:linkData",
    "cardPayments:settle": "/payments/settlements/full/:linkData",
    "cardPayments:partialSettle": "/payments/settlements/partials/:linkData",
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Card Payments (7)

Take a card payment

Request

Responses

Do you like our page?

Take a repeat card payment

Request

Responses

Do you like our page?

Manage Payments

Query a Payment

Query payment status

Request

Responses

Do you like our page?

Query payment status Recovery

Request

Responses

Do you like our page?

Card Payments (7)

Take a card payment

RequestExpand all

Responses

Do you like our page?

Take a repeat card payment

RequestExpand all

Responses

Do you like our page?

Manage Payments

Query a Payment

Query payment status

Request

Responses

Do you like our page?

Query payment status Recovery

Request

Responses

Do you like our page?

Request

Request