API Integration Version

Select your integration version from the drop down:

 

Authentication Methods

We offer the following methods to authenticate requests when calling directly to our Transaction API:

• /paymentsession - Reference

  • It is recommended to create a /paymentsession reference to authenticate requests.

    (This flow supports the full payment flow handling Customer Initiated Transactions for alternative payment methods and 3D Secure transactions).

  • Create a paymentsession and store the response reference returned, in your backend server.
    This reference will be used to populate the PaymentSessionAuthReference when authenticating subsequent transaction requests.

  • Use TokenSecretAuth to execute the POST /paymentsession request.

     

• TokenSecretAuth

  Use TokenSecretAuth to execute POST /paymentsession requests.

  • We recommend using Token and Secret for Merchant Initiated Transactions (refunds, recurring) when calling directly to our Transaction API.

  • A token and secret pair is a method to authenticate and enable access to secure data.

    Token:The token is used in conjunction with the secret to authenticate the request.

    Secret:The secret is the ‘password’ that is used to authenticate against the token. It is known as a token and secret pair because a token is associated with its secret (the pair). Together they work to confirm the identity and authentication of a payment.

  • Each app has a Token and Secret Pair for Sandbox and Live. 

Only sandbox API tokens and test cards will work in the sandbox.
Using the wrong tokens and secrets will result in an authorisation failure.

For more information on the Token and Secret pair, see Token:Secret Permissions.

 

 

Creating a POST /paymentsession

Important to Consider:

• The paymentSession can be used for up to three transaction attempts for the same transaction.

  • If the block duplicate transactions permission has been applied on your API tokens, the paymentSession can only be used for one transaction attempt.

    • If you want to have this permission removed, contact Customer Support.

• A payment session can be used again to re-submit a failed transaction attempt.

• Once a transaction attempt is successful, the paymentSession can no longer be used even if there are any remaining attempts available.

• The paymentSession will expire in 30 minutes, unless an ExpiryDate is set in the /paymentsession request body.

  • The expiry date must be within one year: "ExpiryDate": "2023-10-06T17:43:21+01:00"

  As soon as the payment session is used for the initial transaction attempt, this will initiate the 30 minute expiry time.

 

To create a paymentsession:

Target endpoint: /paymentsession

HTTP Method: POST

1. Call the Judopay Transaction API to create a paymentsession.

2. Use your TokenSecretAuth to execute the POST /paymentsession request

3. Store the paymentsession response reference returned, in your backend server.
   

 

This reference will be used to populate the PaymentSessionAuthReference when authenticating subsequent transaction requests.

 

How to Authenticate all Requests

• Click the Authorize button:

  

The pop up window prompts your authentication method to be entered:

Authenticating using Payment-Session

Prerequisite

• You have the /paymentsession response reference.

Enter the following values:

PaymentSessionAuthToken (apiKey)

1. Supply the token used to authenticate the initial call to generate a paymentsession

The PaymentSessionAuthReference section must also be completed.

PaymentSessionAuthReference (apiKey)

2. Supply the reference returned in the create paymentsession response.

The PaymentSessionAuthToken section must also be completed.

• Click Authorize

• Click Close

 

Authenticating using TokenSecretAuth

• Enter your sandbox Api token as the Username.

• Enter the associated secret as the Password.

See the Transaction API Reference documentation for full schema details and descriptions on each endpoint and try out requests.

 

How to Authenticate a Specific Request

• Click the padlock icon associated to that request:

  

  For the purpose of this exercise, the /transactions/payments request is selected.

• The pop up window prompts your authentication method to be entered:

  

  Authenticating using Payment-Session

  Prerequisite

  • You have the /paymentsession response reference.

  Enter the following values:

  PaymentSessionAuthToken (apiKey)

  1. Supply the token used to authenticate the initial call to generate a paymentsession

  The PaymentSessionAuthReference section must also be completed.

  PaymentSessionAuthReference (apiKey)

  2. Supply the reference returned in the create paymentsession response.

  The PaymentSessionAuthToken section must also be completed.

• Click Authorize

• Click Close

 

Authenticating using TokenSecretAuth

• Enter your sandbox Api token as the Username.

• Enter the associated secret as the Password.

• Click Authorize

• Click Close

See the Transaction API Reference documentation for full schema details and descriptions on each endpoint and try out requests.

 

Testing a Request

To test out a request:

1. Click the header of the request you want to test to expand the section

   For the purpose of this exercise, the /transactions/payments request is selected.

2. To see the parameter descriptions, select the Schema link in the Request body section:

3. Example requests are also provided to assist you.

   (Some methods have multiple examples for different use cases)

4. Click the Try it out button

   Make sure you have set your authentication method for the request, see Authentication Methods

5. Modify the default request body:

   1. Replace your details to match your configuration ( for example the judoId)

6. When all request attributes have been set, click Execute.

 

Note the example response code and response body returned below:

Example success response:

Example error response:

Descriptions of the response codes are listed.
Descriptions of each response attribute can be seen in the Schema link in the Responses section.

 

 

Important Fields

The following important key fields need to be sent between your app and Judopay when making payments:

 

Unique Judo ID

• Add the JudoId to the request body

• Specific to a merchant or location you wish to pay

• String of numbers

• Maximum length 9 characters

• Format: 100100100

• Do not include spaces or dashes

Your Consumer Reference

• Allows you to uniquely identify your customer

• Must be supplied in a payment request

• Can be used to help merchants to reconcile

• Can be used to prevent fraud from occurring through the system

• All subsequent transactions must exactly match the Consumer Reference as it is case sensitive

• String field 40 characters in length

We do not recommend using the consumer’s email address. Instead, we recommend you use a Global Unique Identifier (GUID) generated internally by your system.
Due to the GDPR regulations, please avoid using sensitive customer information in free text fields. See ICO - GDPR.

Your Payment Reference

• Your reference for a payment 

• Should be unique to protect your customers against duplicate transactions

• Maximum length 50 characters

With a server side integration, if a Payment Reference is not supplied, any transactions will not be processed.
With our native Mobile SDKs, a Payment Reference is generated and linked to a transaction if one is not supplied.

 

Request Message Structure

All examples within the Judopay developer and Transaction API reference documentation use the sandbox environment so you can process test transactions while developing your app.

Depending on how you integrate with Judopay, you can authenticate requests by:

• /paymentsession, or

• TokenSecretAuth

  • The token and secret pair

For more information, see Authentication Methods.

API-Version:	6.20   For the latest version of the Judopay Transaction API, see Latest Version.
Content-Type:	application/json
Accept:	application/json
Authorization Method TokenSecretAuth	In the Authorization Header: Supply: Basic {authstring} Example: Basic TXpFdPdRSzWmSGk4djhxeTpjBTS4YjQ5OTdkZmO7CTk1YTE0OWEyMDg1MmY3YWYyZWEyZTcwYmQyZGY3O     Replace {authstring} with base64 encoding of: API Token (username) Colon API Secret (password) Example: MzPdkQK1mGi8v3ky:y158n4732dfc7595a149a20381f7af2ea2e70gr6df794b8rnwc019cc5f799kk3
Authorization Method: PaymentSessionAuthToken	For Payment Session authentication In the Api-Token header: Supply the token used to authenticate the call to generate a payment session The Payment-Session header value must also be supplied.
Authorization Method: PaymentSessionAuthReference	For Payment Session authentication In the Payment-Session header: Supply the reference returned in the create payment session response The Api-Token header value must also be supplied.

 

 

Testing your Integration

Prior to Testing - Prerequisites

Make sure you have the following set up prior to testing:

• You are using sandbox tokens in the sandbox environment.

• You are using test cards in the sandbox environment.

• Your judoIds and tokens are configured and enabled as appropriate.

You need your sandbox account so you can process test transactions while developing your app.

Test all your required payment types in the sandbox environment, using Test Cards to test your integration is working correctly. This will give you confidence for when your integration goes live.

 

For more information, see Testing your Integration.

 

Token:Secret Permissions

You can create more than one set of tokens for a single app, depending on your requirements and app usage.

Each token and secret pair will have specific permissions, they are not shared between all your apps.

 

You will have to configure and set the following permissions separately for each app :

• JudoPayTransactionsGet - Retrieve Transactions

• JudoPayApiTransactionsPaymentPost - Send Payments

• JudoPayApiTransactionsRefundsPost - Send Refunds

• JudoPayWebPaymentsGet - Obtain Web Payment Token

• JudoPayWebPaymentsPost - Send Web Payment

• JudoPayApiTransactionsPreAuthsPost - Send PreAuth

• JudoPayApiTransactionsRegisterCardPost - Register Cards  

It is not recommended to have all permissions on the same APIToken/APISecret.
For example, refund should be a special token for back office use only.

For more information, see Edit Token and Secret App Permissions

 

Webhook Model

Webhooks are an optional secure service provided by Judopay to use to notify your system when a transaction or event has taken place.

The benefit of using webhooks means you do not need to pull information from the Judopay Transaction API for every event.

Enabling Webhooks

To enable webhooks, use the Judopay Portal.

See, Enable Webhooks.

 

If you have any issues enabling webhooks, contact Customer Support and provide the notificationUrl.
This is the URL where you would like Judopay's Transaction API to POST the webhook message to.

 

Example Webhook Model

The transaction or event data is passed via a POST request to your notificationUrl using the content parameter.

The time-out default value is 15 seconds.

 

The example below shows the information the webhook message can contain:

 

It is recommended you create a script to retrieve the data from the content parameter in the receipt model.
The data can then be parsed and used as normal.