Getting started

Integrate simple and secure web app card payments into your project with web payments optimized for mobile screens.

Judopay’s web payments UI come with built-in checks and security features, including real-time error detection, 3D Secure, data and address validation for frictionless card data capture. This minimises PCI compliance and lets you focus on developing other areas of your user experience. See our UI customization guide to learn more.

Web payments use the same protocols and environments as the standard Judopay API. Learn more about this in our RESTful API · Web payments reference.

Please note: If you are aiming to host web payments with an app, please note that redirects slow everything down and user interfaces that don’t match your app make your customers feel unsafe, lowering your conversion rate. Native apps offer customers an optimal checkout experience that is simple, frictionless and secure.

Judo Responsive Overview


Web payments require two configurations of your account. Both settings can be enabled in the dashboard:

Build the transaction header before your payment request. Find your account’s API token and secret on the dashboard and add them to the basic authorization object, base64 encoded:

Api-Version: 5.2
Accept: application/json
Authorization: Basic {base64 token & secret}

If you are looking to use any of the following options, these require additional configuration:

  • Supported card networks - The default value includes Visa, Mastercard, Maestro and AmEx.

    Note: Processing transactions with AmEx cards requires that your account supports it as well. Please contact us first if you are planning to accept AmEx.

  • Address Verification Service (AVS) - You will be able to capture the consumer’s country and postcode as an additional security layer.

    Note: AVS requires an additional configuration at account level. If you are looking to use this feature, please contact us.

  • 3D Secure - Your web payments will be processed through the 3D Secure check, adding an extra security layer to your payment process.

    Note: 3D Secure requires an additional configuration at account level. If you are looking to use this feature, please contact us.

Test sandbox payments

Test different payment types quickly and securely. The sandbox environment guide will provide you critical detail to ensure a solid integration and successful results. These are the highlights:

  • Ensure that the project is properly configured for sandbox environment.
  • Use the test cards provided in our sandbox guide.
  • If 3D Secure is enabled and you want to simulate the 3D Secure screen, contact us for card details.

Request a transaction

    1. Create a transaction request including all the mandatory objects. Check our RESTful API · Web payments reference to learn more about this request.

      The details in the following snippet are dummy data – use the data of your account instead:

        "amount": 125.00,
        "currency": "GBP",
        "yourConsumerReference": "example_customer_reference_00001",
        "yourPaymentReference": "example_payment_reference_00001",
        "invoiceNumber": "000546" , 
        "customerNumber": "ABC123456" 
        "clientIpAddress": "",
        "clientUserAgent": "example browser 5.25"
    2. Retrieve Judopay’s API response:

      "postUrl": "",
      "reference": "yth67_82nhjmf903jnmaiine…"

      Note: The reference provided has an expiration time of 30 minutes as it is provided by our API. If the transaction flow is not completed within this time, the payment will fail and the status will be set as ‘Expired’.

    3. Wrap your checkout button with a ‘form’ tag, using the postUrl as the form’s action and the reference as a hidden field:

      <form action="{postUrl}" method="post">
         <input id="Reference" name="Reference" type="hidden" value="{reference}">
         <input type="submit" value="Pay now">

      The consumer will be redirected to Judopay’s hosted secure web payments form where the card details will be requested.

    4. Once the transaction is completed, the consumer will be redirected to your designated success or failure URL. This call will include some extra data in the POST request to your success URL (“application/x-www-form-urlencoded”), including:

      1. Receipt ID – a unique identifier for that particular transaction.
      2. Card token to allow you to perform repeat payments.
      3. Reference – a transaction key to check the result of a payment and get the receipt information.

Check payment link

You can quickly check the payment link by sending a request to our API using the designed reference provided:


Note: Do not confuse ‘reference’ with ‘yourPaymentReference’. The first is for push and pull information with our API, the second is a variable that you can use to track the transaction. Use ‘reference’ for the above call.

You will receive your receipt information from our API as per the following example:

    "amount": 1.01,
    "cardAddress": {
        "countryCode": 826
    "clientIpAddress": "",
    "clientUserAgent": "Mozilla/5.0 (Windows NT 6.2; Win64; x64)...",
    "companyName": "trading",
    "currency": "GBP",
    "expiryDate": "2015-11-13T14:47:52.1183+00:00",
    "judoId": "100337815",
    "partnerServiceFee": 1.01,
    "paymentCancelUrl": "",
    "paymentSuccessUrl": "",
    "reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA",
    "allowedCardTypes": [
    "response": {
        "postUrl": "",
        "reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA"
    "status": "Expired",
    "transactionType": "SALE",
    "yourConsumerReference": "001",
    "yourPaymentMetaData": {},
    "yourPaymentReference": "003",
    "webPaymentOperation": 0

Check payment receipt

You can quickly check the transaction result by sending a request to our API using the receipt ID provided after the first payment request:


You will receive your receipt information from our API as per the following example:

    "receiptId": "2152023",
    "yourPaymentReference": "002",
    "type": "Payment",
    "createdAt": "2015-11-18T15:06:04.2478+00:00",
    "result": "Success",
    "message": "AuthCode: 808159",
    "judoId": 100337815,
    "merchantName": "trading",
    "appearsOnStatementAs": "trading                  ",
    "netAmount": "0.01",
    "amount": "0.01",
    "currency": "GBP",
    "cardDetails": {
        "cardLastfour": "3436",
        "endDate": "1215",
        "cardType": 0
    "consumer": {
        "consumerToken": "izFWlMVaNs92o72c",
        "yourConsumerReference": "001"
    "postCodeCheckResult": "Failed"

On your receipt screen we recommend displaying the order information, including:

  • Date and time
  • Amount
  • Result (Either a Successful or failure message)
  • appearsOnStatementAs (e.g. “This will appear on your card statement as ….”)

UI customization

Use our web payments UI for a frictionless web checkout on mobile. Minimize your PCI scope with a UI that can be customized to display:

  • Company logo – at the top of the payment form.
  • Button colors – background, shadow and text
  • Display name – The trading name.

To request a customisation for the above, please contact us.

Judopay also includes an API client for direct use of our RESTful API. This offers the most options for customization, but we recommend that you use our secure payments form to minimise your PCI scope and development time.

Ready to go live?

Follow the next steps in the Going live guide.