Interact with the Transaction API

from q4 2025 we will no longer be supporting old versions of our api this means you will need to upgrade to version 6 0 (or higher) by q4 2025 see our transaction api reference documentation for the latest version 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 how to use our transaction api reference documentation interact with our transaction api reference docid\ bcxnm5keok nlnrztafut 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 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 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 authentication methods docid\ ylkw5coh5nqnfq3j wjk2 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 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 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) 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 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 docid\ bcxnm5keok nlnrztafut 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 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 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 docid\ bcxnm5keok nlnrztafut documentation for full schema details and descriptions on each endpoint and try out requests testing a request 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 docid\ ylkw5coh5nqnfq3j wjk2 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 api rate limits 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 mailto\ help\@judopay com functional and load testing 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 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 docid\ ylkw5coh5nqnfq3j wjk2 api version 6 23 for the latest version of the judopay transaction api, see transaction api reference docid\ bcxnm5keok nlnrztafut 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 api token (username) colon colon api secret (password) example mzpdkqk1mgi8v3ky 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 docid obafnuc1umhk vihhs5d to test your integration is working correctly this will give you confidence for when your integration goes live for more information, see testing overview docid\ a4hyvok4t7v0dvsm7fqyi 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 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 introduction docid\ s 8hoamytkgy13t0p657 webhooks 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 docid\ mqjiizxmcro1cpvauawud