Judopay Documentation

Web Payments

Warning

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.

judoresponsive-overview.png

Web Payments Set Up

Caution

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

Note

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

web payments configuration

Step

Description

One.png

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.

Two.png

Select Web payments configuration.

Three.png

The Web payments configuration screen appears.

Four.png

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

Five.png

Click Save configuration.

Tip

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

Step

Description

One.png

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.

Two.png

Select the environment to set permissions:

  • Sandbox tokens

  • Live tokens

For the purpose of this exercise, Sandbox tokens is selected

Three.png

The token information is displayed.

Native apps have the following default permissions:

  • Make Payments

  • PreAuth Transactions

  • Register Card Transactions

Click Edit.

Four.png

The Permissions window appears.

Select or deselect a permission.

 

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

Five.png

Click Save Permissions.

Six.png

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

Tip

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

  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

Caution

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:

https://partnerapi.judopay-sandbox.com/webpayments/{reference}

HTTP Method: GET

You will receive the following transaction receipt information:

{
    "amount": 1.01,
    "cardAddress": {
    "countryCode": 826
},
"clientIpAddress": "127.0.0.1",
"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": [
    1,
    2,
    3,
    8,
    10,
    11,
    12,
    13
    ],
"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.

Tip

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

STEP

DESCRIPTION

One.png

From the side menu, select Your apps

Select the app to view the Token and Secret credentials

Two.png

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

Three.png

The Sandbox Token information is displayed.

You can:

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

Note

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

Request:

https://gw1.judopay-sandbox.com/webpayments/payments

HTTP Method: POST

Example 4. Requesting a Transaction

Create a transaction request including all the mandatory objects.

{
   "judoId":"100016172",
    "amount": 125.00,
    "currency": "GBP",
    "yourConsumerReference": "example_customer_reference_00001",
    "yourPaymentReference": "example_payment_reference_00001",
    "yourPaymentMetaData":{
    "invoiceNumber": "000546" ,
    "customerNumber": "ABC123456"
    },
"clientIpAddress": "127.0.0.1",
"clientUserAgent": "example browser 5.25"
}


Response

Retrieve Judopay’s API response:

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

Caution

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.

Note

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

Caution

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 Portal >  History

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.

See also: