--- title: Authentication Methods slug: authentication-methods docTags: createdAt: 2024-05-20T15:09:06.298Z --- In online and mobile payments, **security is a number one concern**. Authentication and verification of the identity of the cardholder is important for preventing fraudulent transactions and refunds. Each request to Judopay’s Transaction API requires authentication. Depending on how you integrate with Judopay, the following methods are recommended to authenticate requests: - Using our [SDKs](docId:40dWE6LBub7vdKza1QYDC): - `/paymentsession` - Calling directly to our [Transaction API](docId\:bcXNM5keOk-nlNrZTafUT): - `/paymentsession`, or - TokenSecretAuth - The token and secret pair *** ### 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). *** ## Payment Session It is **recommended **to use `/paymentsession` to authenticate your requests, as this flow supports the full payment flow handling **Customer Initiated Transactions** for alternative payment methods and 3D Secure transactions. This method of authentication ensures that any intermediate steps are handled automatically by Judopay. :::hint{type="info"} We also recommend using **paymentSession** when authorising `/payments` or `/preauths` for **3D Secure 2 transactions** for the same reason. ::: ### 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**. ::: Store the **reference **returned in the response in your backend server. Then Invoke a `/payments` or `/preauths` transaction using the **paymentSession reference**. *** ### Create a paymentSession :::hint{type="warning"} Make sure you are using Judopay's API version **6.0.0.0** or higher. ::: Make a HTTP POST Request: `/paymentsession` :::CodeblockTabs Payment Session Request ```json { "judoId": "100100100", "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 10.99, "expiryDate": "2028-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes } ``` Payment Session Response Reference ```json //Store the reference returned in your backend server: { "postUrl": "https://pay-sandbox.judopay.com/v2", "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj_XDg" } ``` ::: *For the full schema details and descriptions, see Transaction API: *[/paymentsession](docId\:bcXNM5keOk-nlNrZTafUT) :::hint{type="info"} Your backend server should store the **paymentSession response reference **returned by Judopay's API. Use this reference from the response to populate paymentSession when calling `/payments` and `/preAuths` from your front-end client. ::: The following parameters need to remain consistent between the `/paymentsession` requests and the `/payments` and `/preauths` requests, otherwise the **transaction will fail**: - YourPaymentReference - YourConsumerReference - JudoID - Currency - Amount This is used to cross reference the validity of the transaction. *** ## Account Funding Transactions Account Funding Transactions (AFT) are **required **for merchants operating in specific **money movement and financial services categories**, as defined by card schemes. For these merchants, additional data **must be** included in the [payment session](docId\:ylKW5coh5NQnfQ3j_Wjk2) and payment requests to ensure transactions are processed in line with scheme and acquirer requirements. Failure to provide the [required AFT fields](docId:5ol_pTSGBHVGKwJwD0gHg) may result in transactions being **declined, flagged, or subject to additional scrutiny**. For more information on your integration, see: - [Transaction API](https://docs.judopay.com/api-reference) (**Version** **6.25 is required, **or higher). - [.NET SDK](docId\:hNgLLJxESInHS7PtfEvTN) - [Virtual Terminal (MOTO)](docId\:VTwytVhCNkqBRccOpdHfm) - [PayByLink via Judopay Portal](docId\:FR-wtitYYgtkcxLuDdma8) - **Mobile and Web SDKs**: No changes are needed to be made to the SDK, however additional AFT information must be provided when creating the [payment session.](docId\:ylKW5coh5NQnfQ3j_Wjk2) *** ### Create a paymentSession with AFT Data 1. Make a HTTP POST Request: `/paymentsession` 2. Submit the **required **AFT fields as part of the Payment Session request: For more information on the required AFT fields, see [Required Request Fields.](docId:5ol_pTSGBHVGKwJwD0gHg) 1. `businessApplicationId` 2. `aftRecipientInformation` 1. `firstName ` 2. `addressLine1 ` 3. `countryCode ` 4. `accountId ` 5. `accountType` :::CodeblockTabs Payment Session Request ```json { "judoId": "100100100", "yourConsumerReference": "2b45fd3f-cee5-4e7e-874f-28051db65408", "yourPaymentReference": "6482c678-cad3-4efd-b081-aeae7a89a134", "currency": "GBP", "amount": 10.99, "expiryDate": "2028-02-05T16:28:32.8596+00:00" //if not set, session will expire in 30 minutes }, "businessApplicationId": "AA", "aftRecipientInformation": { "firstName": "Jane", "addressLine1": "Recipient House", "countryCode": "GB", "accountId": "5432101111", "accountType": "03" } ``` Payment Session Response Reference ```json //Store the reference returned in your backend server: { "postUrl": "https://pay-sandbox.judopay.com/v2", "reference": "5QcAAAQAAAAPAAAACAAAABtGgvhBrF9BHTN7nqn1e0J4hVVmi-y27dGPjWBMtls3Gj_XDg" } ``` ::: *For the full schema details and descriptions, see Transaction API: *[/paymentsession](docId\:bcXNM5keOk-nlNrZTafUT) :::hint{type="info"} Your backend server should store the **paymentSession response reference **returned by Judopay's API. Use this reference from the response to populate paymentSession when calling `/payments` and `/preAuths` from your front-end client. ::: The following parameters need to remain consistent between the `/paymentsession` requests and the `/payments` and `/preauths` requests, otherwise the **transaction will fail**: - YourPaymentReference - YourConsumerReference - JudoID - Currency - Amount This is used to cross reference the validity of the transaction. *** ## Authenticating via API When authorising `/payments` or `/preauths` you can call directly to the API using: - `/paymentsession` - TokenSecretAuth - The token and secret pair - Specify your token in **Username **and secret in **Password** For more information on creating a `/paymentsession`, see [Transaction API /paymentSession](docId\:bcXNM5keOk-nlNrZTafUT). For more information on headers to authenticate a transaction using **TokenSecretAuth**, see [Authenticating using TokenSecretAuth](docId\:ApyEqDsYCdRKUxgGnLHup). *** ## Headers to Authenticate a Transaction ### Authenticating a Transaction using paymentSession **Prerequisites** - You are using Judopay's API version **6.0.0.0 **or higher. - To submit [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg) you are using Judopay's API version **6.25 **or higher. - You have the `/paymentsession` response reference. :::hint{type="info"} The **paymentSession** will expire in 30 minutes, unless an **ExpiryDate **is set in the `/paymentsession` request body. ::: **Request Message Structure**: | 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**:
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. | *** ### Authenticating a Transaction using Token and Secret **Request Message Structure**: | 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** |