Skip to content
APIs/Card Payments/
Take a card payment

Take a card payment

Request

Take online card payments using our Card Payments API.

Security
BasicAuth
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.

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

A reference, generated by you, that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments, for example where:

  • the total amount for a single order is split across multiple payments
  • you use a single reference for each payment in a recurring agreement or split shipment scenario
Example:"order-12345"
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.

instructionobjectrequired

An object that contains all information related to the payment.

riskProfilestring

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

If using either the FraudSight or Exemptions API you must provide this.

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

An object containing authentication details.

exemptionobject
shippingobject

An object containing shipping details.

orderobject

An object containing details about the order.

recipientobject

Additional transaction recipient data.

customerobject

Additional customer data.

industryDataobject

Payment authorization for GBP 2.50

import java.net.*;
import java.net.http.*;
import java.util.*;

public class App {
  public static void main(String[] args) throws Exception {
    var httpClient = HttpClient.newBuilder().build();

    var host = "https://try.access.worldpay.com";
    var pathname = "/cardPayments/customerInitiatedTransactions";
    var request = HttpRequest.newBuilder()
      .POST(HttpRequest.BodyPublishers.ofString(payload))
      .uri(URI.create(host + pathname ))
      .header("Content-Type", "application/vnd.worldpay.payments-v7+json")
      .header("Accept", "application/vnd.worldpay.payments-v7+json")
      .header("Authorization", "Basic " + Base64.getEncoder().encodeToString(("<username>:<password>").getBytes()))
      .build();

    var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.body());
  }
}

Responses

The payment authorization has been successfully created

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

Outcome of the request. Sent for Settlement returned only if requestAutoSettlement is enabled in the request.

Enum:"authorized""Sent for Settlement""refused"
Discriminator
paymentIdstring, [ 21 .. 36 ] characters^[A-Za-z0-9_-]+$

Unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions.

Example:"payI-dUcet9fk4_X4qZU0hpU0"
commandIdstring, [ 21 .. 36 ] characters^[A-Za-z0-9_-]+$

Unique identifier generated by us for a single instance of an interaction (command) with the Worldpay API.

Example:"cmdRvD-OxCyXgJLQ9_jbqXAC0"
exemptionobject

An exemption result and reason if either a risk profile was included in your authorization request, or if you included the exemption object in the request.

issuerobject

An object containing information returned by the issuer.

paymentInstrumentobject

Details of the paymentInstrument used.

updatedPaymentInstrumentobject

Details of the updated payment instrument.

amountsobject

An object containing transaction amounts. Returned for partial authorizations.

riskFactorsArray of objects

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

schemeobject

An object containing information returned by the card scheme.

Response

Payment authorization for GBP 2.50 with a successful outcome

{
  "outcome": "authorized",
  "paymentId": "payI-dUcet9fk4_X4qZU0hpU0",
  "commandId": "cmd-Rjc4HJwnBdj3Ri9v10vT0",
  "riskFactors": [
    {
      "type": "cvc",
      "risk": "notSupplied"
    },
    {
      "type": "avs",
      "risk": "notChecked",
      "detail": "address"
    },
    {
      "type": "avs",
      "risk": "notChecked",
      "detail": "postcode"
    }
  ],
  "issuer": {
    "authorizationCode": "T75725"
  },
  "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/linkData"
    },
    "cardPayments:partialCancel": {
      "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/partials/linkData"
    },
    "cardPayments:settle": {
      "href": "https://try.access.worldpay.com/payments/settlements/full/linkData"
    },
    "cardPayments:partialSettle": {
      "href": "https://try.access.worldpay.com/payments/settlements/partials/linkData"
    },
    "cardPayments:events": {
      "href": "https://try.access.worldpay.com/payments/events/linkData"
    },
    "curies": [
      {
        "name": "cardPayments",
        "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
        "templated": true
      }
    ]
  }
}