Interact with the Transaction API
To get started with Judopay's Transaction API, here are a few important pieces of information to help you begin.
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.
Due to the GDPR regulations, please avoid using sensitive customer information in free text fields such as:
- YourPaymentReference
- YourConsumerReference
- YourPaymentMetaData
For more information on GDPR and what is considered personal data, see ICO - GDPR.
Interact with our Transaction API Reference in the following ways:
- Select your integration version
- See the authentication methods available
- How to create a /paymentsession
- Authenticate all requests or a specific request
- Manually test a request
- View example success and error responses
Select your integration version from the drop down:
To create a paymentsession:
Target endpoint: /paymentsession
HTTP Method: POST
- Call the Judopay Transaction API to create a paymentsession.
- Use your TokenSecretAuth to execute the POST /paymentsession request.
- Store the paymentsession response reference returned, in your backend server. This reference will be used to populate the PaymentSessionAuthReference when authenticating subsequent transaction requests.
- Click the Authorize button:
The pop up window prompts your authentication method to be entered:
Prerequisite
- You have the /paymentsession response reference.
Enter the following values: PaymentSessionAuthToken (apiKey)
- Supply the token used to authenticate the initial call to generate a paymentsession. The PaymentSessionAuthReference section must also be completed.
PaymentSessionAuthReference (apiKey)
- Supply the reference returned in the create paymentsession response.
The PaymentSessionAuthToken section must also be completed.
- Click Authorize
- Click Close
- Enter your sandbox Api token as the Username.
- Enter the associated secret as the Password.
- Click Authorize
- Click Close
- 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:
Prerequisite
- You have the /paymentsession response reference.
Enter the following values: PaymentSessionAuthToken (apiKey)
- Supply the token used to authenticate the initial call to generate a paymentsession The PaymentSessionAuthReference section must also be completed.
PaymentSessionAuthReference (apiKey)
- Supply the reference returned in the create paymentsession response.
The PaymentSessionAuthToken section must also be completed.
- Click Authorize
- Click Close
- Enter your sandbox Api token as the Username.
- Enter the associated secret as the Password.
- Click Authorize
- Click Close
To test out a request:
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.
To see the parameter descriptions, select the Schema link in the request body section:
Example requests are also provided to assist you. (Some methods have multiple examples for different use cases).
Click the Try it out button.
Make sure you have set your authentication method for the request, see Authentication Methods.
Modify the default request body:
- Replace your details to match your configuration (for example the judoId).
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.
Judopay applies rate limiting at an account level, based on the merchant’s profile. This helps us to accurately detect any anomalies in usual traffic rates that may occur to protect both Judopay and you.
Our team regularly reviews these to ensure our rate limits are sufficient for your requirements, but should you have any queries on this please contact Customer Support.
Judopay’s sandbox environment accommodates functional testing of your integration and is not designed for load or stress testing scenarios. Due to lower rate limits applied in sandbox, we recommend simulating test requests with a prudent level of latency applied.
The following important key fields need to be sent between your app and Judopay when making payments:
- 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
- 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 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.
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.
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 Overview.
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
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.
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.
For more information on enabling webhooks and to view an example webhook model, see Webhooks.