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

Card Payments (6)

Payments root resource, returns links to available payments actions.

Download OpenAPI description

openapi.json

openapi.yaml

Servers

testing (try)

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

live

https://access.worldpay.com/

Take a one-time payment

To take a payment, you must first create an authorization request. Your response contains links to your next available actions.

Operations

Take repeat payments

Take a payment using a stored credential

Operations

Authorize using Card on File with verification

Request

Use our card on file authorize resource when your customer is initiating a payment using stored card details verifying their account first

Path

linkDatastringrequired

Action link that's received in your request

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+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.

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

instructionobjectrequired

An object that contains all information related to the payment.

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

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

intentstring

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

customerobject

An object that contains riskProfile and authentication of the customer.

riskProfilestring

authenticationany

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

versionstringrequired

The version of 3DS used to process the transaction.

Enum"1""2"

ecistringrequired

Electronic Commerce Indicator (ECI).

typestringrequired

Value"3DS"

Discriminator

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.

application/vnd.worldpay.payments-v6+json

Payment authorization for GBP 2.50

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity"
  },
  "instruction": {
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      }
    }
  }
}

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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""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",
  "_links": {
    "payments:cancel": {
      "href": "/payments/authorizations/cancellations/linkData"
    },
    "payments:settle": {
      "href": "/payments/settlements/linkData"
    },
    "payments:partialSettle": {
      "href": "/payments/settlements/partials/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "payments:cardOnFileAuthorize": {
      "href": "/payments/cardOnFile/linkData"
    },
    "payments:recurringAuthorize": {
      "href": "/payments/recurring/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Authorize using Card on File no verification

Request

Use our card on file authorize resource when your customer is initiating a payment using stored card details (without verifying their account first)

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+json

instructionobjectrequired

An object that contains all information related to the payment.

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

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

intentstring

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

schemeobject

referencestringrequired

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

paymentFacilitatorobject

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

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

transactionReferencestringrequired

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

channelstring

The payment channel indicates the interaction of the cardholder with the merchant. Supply a value of moto to process an authorization as a Mail Order or Telephone Order (MOTO) transaction. If channel is not provided, the authorization will be processed as ecommerce by default

Value"moto"

customerobject

An object that contains riskProfile and authentication of the customer.

riskProfilestring

authenticationany

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

versionstringrequired

The version of 3DS used to process the transaction.

Enum"1""2"

ecistringrequired

Electronic Commerce Indicator (ECI).

typestringrequired

Value"3DS"

Discriminator

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.

application/vnd.worldpay.payments-v6+json

Payment authorization for GBP 2.50

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity"
  },
  "instruction": {
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      }
    }
  }
}

Responses

The authorization for migrated Card On File 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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""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",
  "_links": {
    "payments:cancel": {
      "href": "/payments/authorizations/cancellations/linkData"
    },
    "payments:settle": {
      "href": "/payments/settlements/linkData"
    },
    "payments:partialSettle": {
      "href": "/payments/settlements/partials/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "payments:cardOnFileAuthorize": {
      "href": "/payments/cardOnFile/linkData"
    },
    "payments:recurringAuthorize": {
      "href": "/payments/recurring/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Card on File Sale

Request

Use our card on file sale resource when your customer is initiating a payment using stored card details, and you want to instantly trigger the settlement process

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+json

instructionobjectrequired

An object that contains all information related to the payment.

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

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

intentstring

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

schemeobject

referencestringrequired

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

paymentFacilitatorobject

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

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

transactionReferencestringrequired

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

channelstring

Value"moto"

customerobject

An object that contains riskProfile and authentication of the customer.

riskProfilestring

authenticationany

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

versionstringrequired

The version of 3DS used to process the transaction.

Enum"1""2"

ecistringrequired

Electronic Commerce Indicator (ECI).

typestringrequired

Value"3DS"

Discriminator

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.

application/vnd.worldpay.payments-v6+json

Card sale for GBP 2.50

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity"
  },
  "instruction": {
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      }
    }
  }
}

Responses

The sale for migrated Card On File 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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

An object containing information returned by the scheme.

referencestringrequired

Response

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

Sale for GBP 2.50 with a successful outcome

{
  "outcome": "Sent For Settlement",
  "_links": {
    "payments:refund": {
      "href": "/payments/settlements/refunds/:linkData"
    },
    "payments:partialRefund": {
      "href": "/payments/settlements/refunds/partials/:linkData"
    },
    "payments:reversal": {
      "href": "/payments/sales/reversals/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Authorize Recurring Payment no verification

Request

Use our migrate recurring authorize resource when you are initiating a payment using your customer's stored card details, without verifying their account first

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+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

paymentFacilitatorobject

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

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

instructionobjectrequired

An object that contains all information related to the payment.

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.

intentstringrequired

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

paymentInstrumentobjectrequired

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

application/vnd.worldpay.payments-v6+json

Recurring payment authorization for GBP 2.50

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity"
  },
  "instruction": {
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      }
    },
    "intent": "subscription"
  }
}

Responses

The recurring 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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

An object containing information returned by the scheme.

referencestringrequired

Response

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

Recurring payment authorization for GBP 2.50 with a successful outcome

{
  "outcome": "authorized",
  "_links": {
    "payments:cancel": {
      "href": "/payments/authorizations/cancellations/linkData"
    },
    "payments:settle": {
      "href": "/payments/settlements/linkData"
    },
    "payments:partialSettle": {
      "href": "/payments/settlements/partials/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Authorize Recurring Payment with verification

Request

Use our recurring authorize resources when you are initiating a payment using your customer's stored card details, verifying your customer's account first.

Path

linkDatastringrequired

Action link that's received in your request

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+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

paymentFacilitatorobject

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

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

instructionobjectrequired

An object that contains all information related to the payment.

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.

intentstringrequired

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

paymentInstrumentobjectrequired

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

application/vnd.worldpay.payments-v6+json

Recurring payment authorization for GBP 2.50

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity"
  },
  "instruction": {
    "narrative": {
      "line1": "trading name"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      }
    },
    "intent": "subscription"
  }
}

Responses

The recurring 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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

An object containing information returned by the scheme.

referencestringrequired

Response

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

Recurring payment authorization for GBP 2.50 with a successful outcome

{
  "outcome": "authorized",
  "_links": {
    "payments:cancel": {
      "href": "/payments/authorizations/cancellations/linkData"
    },
    "payments:settle": {
      "href": "/payments/settlements/linkData"
    },
    "payments:partialSettle": {
      "href": "/payments/settlements/partials/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Recurring Sale

Request

Use our recurring sale resource to authorize and settle merchant initiated transactions where you have stored the card details. You must verify your customer's account before submitting your first recurring payment for authorization.

Path

linkDatastringrequired

Action link that's received in your request

Headers

Content-Typestringrequired

Example:

application/vnd.worldpay.payments-v6+json

Acceptstring

Example:

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

Bodyapplication/vnd.worldpay.payments-v6+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

paymentFacilitatorobject

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

pfIdstringrequired

subMerchantobjectrequired

isoIdstring

instructionobjectrequired

An object that contains all information related to the payment.

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.

intentstringrequired

A parameter detailing the reason for this particular card on file agreement.

Enum"instalment""subscription"

paymentInstrumentobjectrequired

cardExpiryDateobjectrequired

Contains your customer's card expiry date.

typestringrequired

An identifier for the paymentInstrument being used.

Value"card/plain"

Discriminator

cardNumberstringrequired

Contains your customer's card number.

billingAddressobject

Contains the billing address information.

cardHolderNamestring

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

cvcstring

CVC is a unique set of 3 or 4 numbers on the back of the card. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.

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.

debtRepaymentboolean

DRI is a flag which identifies a payment as being for the purpose of repaying a debt.

application/vnd.worldpay.payments-v6+json

Recurring sale with all optional fields

{
  "transactionReference": "transaction-ref",
  "merchant": {
    "entity": "an-entity",
    "mcc": "1234",
    "paymentFacilitator": {
      "pfId": "12345",
      "isoId": "12345",
      "subMerchant": {
        "name": "Merchant Plc",
        "merchantId": "12345",
        "postalCode": "SW1 1AA",
        "street": "Regent Street",
        "city": "London",
        "countryCode": "123",
        "taxId": "12345",
        "state": "St8"
      }
    }
  },
  "instruction": {
    "debtRepayment": true,
    "narrative": {
      "line1": "trading name",
      "line2": "order number"
    },
    "value": {
      "currency": "GBP",
      "amount": 250
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 12,
        "year": 2024
      },
      "cardHolderName": "John Appleseed",
      "billingAddress": {
        "address1": "address line 1",
        "address2": "address line 2",
        "address3": "address line 3",
        "city": "city",
        "state": "state",
        "postalCode": "12345",
        "countryCode": "IT"
      }
    },
    "intent": "subscription"
  }
}

Responses

The recurring payment 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

Full details of the paymentInstrument used.

typestring

cardobject

numberobject

issuerobject

paymentAccountReferencestring

countryCodestring

fundingTypestring

brandstring

expiryDateobject

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"not_checked""not_matched""not_supplied""verificationFailed"

detailstring

Enum"address""postcode"

schemeobject

referencestringrequired

Response

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

Payment sale with all optional fields

{
  "outcome": "authorized",
  "issuer": {
    "authorizationCode": "012345"
  },
  "riskFactors": [
    {
      "type": "cvc",
      "risk": "not_matched"
    },
    {
      "type": "avs",
      "detail": "postcode",
      "risk": "not_checked"
    }
  ],
  "_links": {
    "payments:refund": {
      "href": "/payments/settlements/refunds/:linkData"
    },
    "payments:partialRefund": {
      "href": "/payments/settlements/refunds/partials/:linkData"
    },
    "payments:reversal": {
      "href": "/payments/sales/reversals/linkData"
    },
    "payments:events": {
      "href": "/payments/events/linkData"
    },
    "curies": [
      {
        "name": "payments",
        "href": "/rels/payments/{rel}",
        "templated": true
      }
    ]
  }
}

Manage Payments

Cancel, settle, refund or reverse payments

Operations

Query a Payment

Send a request to find out the current status of your payment after it has been authorized.

Operations

Card Payments (6)

Take a one-time payment

Take repeat payments

Authorize using Card on File with verification

Request

Responses

Was this helpful?

Authorize using Card on File no verification

Request

Responses

Was this helpful?

Card on File Sale

Request

Responses

Was this helpful?

Authorize Recurring Payment no verification

Request

Responses

Was this helpful?

Authorize Recurring Payment with verification

Request

Responses

Was this helpful?

Recurring Sale

Request

Responses

Was this helpful?

Manage Payments

Query a Payment