Judopay Documentation

Web Payments


Web Payments is not the same as using the Web SDK.

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


Web Payments Set Up


Web Payments is not the same as using the Web SDK.

From the Judopay Portal Dashboard:

  1. Enable the web payments configuration

    1. Set up the success and failure URLs

  2. Verify your app has the required permissions enabled

  3. Build the transaction header

  4. Get your Token and Secret

    1. Add them to the basic authorization object, base64 encoded:

Example 3. Payment Request:

HTTP Header

POST https://gw1.judopay-sandbox.com/webpayments/payments
API-Version: 5.6
Accept: application/json
Authorization: Basic {authstring}

  1. Replace {authstring} with base64 encoding of:

  • API Token (username)

  • Colon

  • API Secret (password)

Enable Web Payments Configuration


Web Payments do not apply for Mobile and your Server Side or Mobile only integrations

web payments configuration




From the side menu, select Your apps.

Select the app you wish to edit. For the purpose of this exercise, Document Testing App is selected.

This configuration is to be set up for each of your web payments apps.


Select Web payments configuration.


The Web payments configuration screen appears.


Select the Enable Web payments (hosted redirect web payment) tickbox

Specify the Success and Failure URLs.


(Depending on the transaction result, this is where the consumer will be redirected once the transaction process is completed).


Click Save configuration.


Success and Failure URLs should be configured using the https protocol.

This will prevent the browser’s pop-up messages warning the consumer of insecure connectivity.

Verify Permissions

Set your app's permissions:

edit app permissions




From the side menu, select Your apps.

Select the app you wish to edit.


For the purpose of this exercise, Document Testing App is selected.


Select the environment to set permissions:

  • Sandbox tokens

  • Live tokens

For the purpose of this exercise, Sandbox tokens is selected


The token information is displayed.

Native apps have the following default permissions:

  • Make Payments

  • PreAuth Transactions

  • Register Card Transactions

Click Edit.


The Permissions window appears.

Select or deselect a permission.


For the purpose of this exercise, List all Transactions is selected


Click Save Permissions.


The added permission appears in the list.

Test to validate the change has taken effect.

User Interface

Customise your User Interface to display:

  • Company Logo: Top of the Payment Form

  • Button Colours: Background | Shadow | Text

  • Display Name: Your Trading Name


You can use an API client which offers most options for customization.

We recommend using our secure payments form to minimise your PCI scope and development time.

Wrap your checkout button with the following:

  1. Form Tag: Checkout Button

  2. Form Action: postUrl 

  3. Reference: hidden field

    <form action="{postUrl}" method="post">
    <input id="Reference" name="Reference" type="hidden" value="{reference}">
    <input type="submit" value="Pay now">
  4. Consumer is redirected to Judopay’s hosted secure web payments form 

  5. Consumer’s card details are requested

  6. Once the transaction is complete, consumer is redirected to your success or failure URL. 

  7. This call will include some extra data in the POST request to your success URL: application/x-www-form-urlencoded

    • Receipt ID – Unique identifier for that particular transaction

    • Card Token - Unique to allow repeat payments.

    • Reference – Transaction key to check the result of a payment and get receipt information.

Check Transaction Results and Receipts


Do not confuse reference with yourPaymentReference. 

Reference: push and pull information with our API. 

yourPaymentReference: a variable to track the transaction.

To check the transaction result, send a request to our API using the Reference:


HTTP Method: GET

You will receive the following transaction receipt information:

    "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": "http://www.marca.com/",
"paymentSuccessUrl": "http://www.20minutos.es/",
"reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA",
"allowedCardTypes": [
"response": {
"postUrl": "https://pay.judopay-sandbox.com/v1",
"reference": "3wcAAAsAAAANAAAADgAAAJ_C3aHop-cZcb5PTdUGOH8ceQ1_wn8fP46UmY_CWYMZ8jcUgA"
    "status": "Expired",
    "transactionType": "SALE",
    "yourConsumerReference": "001",
    "yourPaymentMetaData": {},
    "yourPaymentReference": "003",
    "webPaymentOperation": 0

We recommend displaying the following order information on your receipt screen:

  • Date and Time

  • Amount

  • Result (Success or Failure message)

  • appearsOnStatementAs (This will appear on your card statement as ….)

Token and Secret

  1. Find your account’s API token and secret in the Judopay Portal. 

  2. Add them to the basic authorization object, base64.

Sandbox Token and Secret

Each Token and Secret pair will have specific permissions configured.


Double check these permissions before using the Token and Secret.

From the Judopay Portal:

To view the Sandbox Token and Secret:

view sandbox token and secret




From the side menu, select Your apps

Select the app to view the Token and Secret credentials


Select Sandbox tokens to see both the Token and Secret for the Sandbox Environment.


The Sandbox Token information is displayed.

You can:

View the Token | Secret | View and Edit Permissions | Disable the token | Add a new Sandbox token


A live Token and Secret will only be visible within the app once your account is activated.

Test Web Payments - Sandbox

To test your web payment integration:

  • Ensure the project is configured for the sandbox environment

  • Use the test cards provided




Example 4. Requesting a Transaction

Create a transaction request including all the mandatory objects.

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


Retrieve Judopay’s API response:

"postUrl": "https://pay.judopay-sandbox.com/v1",
"reference": "yth67_82nhjmf903jnmaiine…"


The reference example has an expiration time of 30 minutes.

If the transaction is not completed within this time, the transaction will Fail and the status = Expired.

Going Live with Web Payments

Use the live environment for testing before deploying your app.


You will need to have tested your app in the sandbox environment before going live.

1. Activate your Account

  • To process live payments, ensure you have a live account.

  • Complete the activation form for us to make the necessary changes to your account. 

    We will contact you as soon as you are live.

2. Point to the Live Environment


When you change environments, remembe to use the correct API Token and API Secret for that environment. Using the wrong tokens and secrets will result in an authorisation failure.

  • Delete sandbox in the header URL

  • Replace your sandbox API Token and Secret for the live API Token and Secret 

    • Find these in Judopay Portal > Your apps > {app name} > Live Tokens

    HTTP Header

    POST https://gw1.judopay.com/webpayments/payments
    API-Version: 5.6
    Accept: application/json
    Authorization: Basic {authstring}

3. Test Live Payments

  • Ensure the SDK is properly configured for the live environment

  • Use real debit or credit cards

    • Test cards provided will not work in the live environment

    • We recommend performing pre-authorizations followed by a void, or regular payments followed by a refund 

      • Send a refund through the Judopay PortalHistory

Test all payment scenarios and security features to verify the expected behaviour:

Successful Result 

  • Ensure the payment process redirects the consumer to the Success URL 

Declined Result 

  • Ensure the payment process redirects the consumer to the Failure URL

Cancelled Transaction 

  • Click Cancel in the web payments UI

  • We recommend you return the consumer to the URL they visited before the web payment was initiated.