--- title: Interact with the Transaction API slug: interact-with-the-transaction-api docTags: createdAt: 2024-05-20T15:09:40.620Z --- To get started with Judopay's Transaction API, here are a few important pieces of information to help you begin. :::hint{type="info"} 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. ::: :::hint{type="warning"} 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](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/personal-information-what-is-it/what-is-personal-information-a-guide/). ::: *** # 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: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/MjxgzgsYg44NIrt8d0kob_version-dropdown.png" size="42" width="417" height="215" position="flex-start" alt="api version dropdpwn list" showCaption="false"} *** ### 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** :::hint{type="info"} 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**. :::hint{type="warning"} 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 and Secret Authentication](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": "2028-10-06T17:43:21+01:00"` :::hint{type="info"} 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** ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/DjJUXpkr-90IQeQxoNnmX_paymentsession-auth.png" size="82" width="1432" height="104" position="flex-start" alt="payment session endpoint" showCaption="false"} 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: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/Q410bncer1S37va61XmUa_authorise-button.png" size="20" width="154" height="39" position="flex-start" alt="authorize button" showCaption="false"} The pop up window prompts your authentication method to be entered: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/Xww7gOZfNSwvM9B-G97lH_auth-types-window.png" size="60" width="610" height="917" position="flex-start" alt="available authorization types" showCaption="false"} *** ### 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: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/_c0KhECgzXXGO81SGmKnD_auth-request.png" size="82" width="1433" height="105" position="flex-start" alt="payment endpoint" showCaption="false"} *For the purpose of this exercise, the *`/transactions/payments`* request is selected*. - The pop up window prompts your authentication method to be entered: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/PyE-MMgcC0Ict8K9Qis3K_auth-types-window.png" size="48" width="610" height="917" position="flex-start" alt="available authorization types" showCaption="false"} **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: :::::WorkflowBlock :::WorkflowBlockItem 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.* ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/5Ukgd9qfDJ7-4SfsRQTd8_payments-schema.png" size="80" width="1439" height="683" position="flex-start" alt="payments request" showCaption="false"} ::: :::WorkflowBlockItem To see the parameter descriptions, select the **Schema **link in the request body section: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/kguu14XU4KoGVcCAvbnTS_request-schema.png" size="80" width="1404" height="932" position="flex-start" alt="request schema" showCaption="false"} ::: :::WorkflowBlockItem Example requests are also provided to assist you. (*Some methods have multiple examples for different use cases)*. ::: ::::WorkflowBlockItem Click the **Try it out **button. :::hint{type="info"} Make sure you have set your authentication method for the request, see [Authentication Methods](docId\:ylKW5coh5NQnfQ3j_Wjk2). ::: :::: :::WorkflowBlockItem Modify the default request body: - Replace your details to match your configuration (for example the judoId). ::: :::WorkflowBlockItem When all request attributes have been set, click **Execute**. ::: ::::: *Note the example response code and response body returned below:* **Example success response**: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/me51IWTEXl_dQ65g2dq9J_response-success.png" size="76" width="1422" height="1087" position="flex-start" alt="response success" showCaption="false"} **Example error response**: ::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/aJ3r7CHLu073-0bIZDMbw_response-failure.png" size="80" width="1426" height="863" position="flex-start" alt="response eror" showCaption="false"} :::hint{type="info"} 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 :::hint{type="info"} 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](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/personal-information-what-is-it/what-is-personal-information-a-guide/). ::: ### Your Payment Reference - Your reference for a payment - Should be unique to protect your customers against duplicate transactions - Maximum length 50 characters :::hint{type="warning"} 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.26
For the latest version of the Judopay Transaction API, see [Latest Version](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** (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](https://www.judopay.com/applysandboxaccount) 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 :::hint{type="info"} 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](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).