---
title: Deprecated Integration Methods
slug: deprecated-integration-methods
docTags: 
createdAt: 2024-06-03T11:07:37.141Z
---

# PHP Server SDK Integration

:::hint{type="warning"}
We no longer support the PHP SDK and it is now deprecated.
:::

### Prerequisites

- PHP** 5.5 **and above
- Composer Package Manager

### Integration

Using the Composer Package Manager:

1. Add the Judopay package to your composer.json file:
   `"require": {"judopay/judopay-sdk": "5.1.0"}`
2. Execute:
   `$ composer install`
3. Make the Judopay SDK classes available to your application, by adding the following to your file:
   `require 'vendor/autoload.php';`

***

:::hint{type="warning"}
Only sandbox API tokens and secrets will work in the sandbox.
Using the wrong tokens and secrets will result in an **authorisation failure**.
:::

## Setup

1. Ensure all integration steps are completed.
2. Add your app’s sandbox Token and Secret:
   `var client = JudoPaymentsFactory.Create(`
   ` JudoEnvironment.Sandbox,`
   `  <yourApiToken>,  `
   `<yourApiSecret> `
   `);`
3. Ensure the SDK is configured for the sandbox environment.
4. Use the test cards provided in the Judopay Portal:
   - **Tools** > **Generating transactions**

:::hint{type="info"}
Create a separate app for your backend with the **Make Payments** permission enabled.
:::

Test all your required payment types in the sandbox environment before going live.

1. Create a new Judopay object, with your API credentials:
   `$judopay = new \Judopay(`
   ` array(`
   ` 'apiToken' => 'your-token',`
   ` 'apiSecret' => 'your-secret',`
   ` 'judoId' => 'your-judo-id',`
   ` //Set to true on production, defaults to false which is the sandbox`
   ` 'useProduction' => false`
   ` )`
   `);`
2. Ensure the SDK is configured for the environment you are targeting.
   For example, if you are using the sandbox environment: **'useProduction' => false.**

:::hint{type="info"}
For the purpose of this exercise, the sandbox token and secret have been added.
:::

***

The Server SDK allows for further configuration:

**Logging**
To help debug you can attach a logger library.
Validation error details can be found in the **modelErrors** array.&#x20;
For example if a required field is missing from the model.

**Other Payment Methods using the Server SDKs**
To send payment requests with the wallet details from Apple Pay™ and Google Pay™, see our [Transaction API](docId\:bcXNM5keOk-nlNrZTafUT) for more information.

***

## Check Card

:::hint{type="info"}
When making [Token Payments](docId:_3g7a0RAxGlG9AiC4VCWP), you can obtain the **card token** from the Check Card response.
:::

**Create an instance of the CheckCard Model**:

:::CodeblockTabs
PHP

```php
//Prepare the CheckCard request
$checkCardRequest = $judopay->getModel('CheckCard');

$checkCardRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/30',
        'cv2' => '452',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => 'test.user@judopay.com',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $checkCardRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::hint{type="info"}
You do not need to set an amount.&#x20;
This is automatically set by Judopay's Transaction API in order to check the card.
:::

:::hint{type="warning"}
**\*Mastercard Recommends:**
These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied.&#x20;
See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow).
:::

| **Parameter**                                                                                                       | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font><br /><br />                                         | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font><br />                                | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `yourPaymentReference`<br />String<br /><font color="#ef5b2e">Required</font><br />                                 | Your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                                                                                                                                                                                                      |
| `phoneCountryCode`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br />   | The country code of the consumer's phone.<br />Format:<br />* Maximum length 3 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **mobileNumber** is set.<br />If not set, default = 44                                                                                                                                                                                                                                                                                                                                                                                            |
| `mobileNumber`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br /><br /> | Consumer’s valid mobile number.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.<br />Format:<br />* Maximum length 15 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **phoneCountryCode** is set.                                                                                                                                                                                                                                                                                               |
| `cardHolderName`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br />     | The card name of the consumer<br />If the cardHolderName field is displayed to the user in the payment form (**isCardHolderNameVisible: true&#x20;**&#x69;s set in the iFrame config), the value entered in the payment form will overwrite this value.                                                                                                                                                                                                                                                                                                                                                                                 |
| `challengeRequestIndicator`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />                      | Indicates the type of challenge request you wish to apply.<br />Set this to one of the following strings:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.<br />This **should not&#x20;**&#x62;e included in the same configuration object as **scaExemption**.                                                                                                                                                                                                                   |
| `scaExemption`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />                                   | To apply for an exemption from SCA, for a customer initiated transaction.<br />Set this to one of the following strings:<br />* `lowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `trustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `transactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.<br />This **should not** be included in the same configuration object as **challengeRequestIndicator**. |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>                                   | Indicates if this initial payment is part of a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `billingAddress`<br />Object<br /><font color="#42cbd4">Optional</font><br /><br />                                 | Card holder's billing address.<br />Properties:<br />* `address1` <font color="#ef5b2e">(</font><font color="#ef5b2e">Recommended)</font><font color="#ef5b2e">*</font>
* `address2` (optional)
* `town`
* `state`(only required if country is USA/Canada)
  - Format:
    - string
    - ISO Alpha-2 Code (e.g. California = "**CA**")
* `country`
  - Format:
    - string
    - See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
* `postCode`<br />If the billingAddress is provided, the postcode is **required**.                                                               |
| `emailAddress`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font>             | Consumer’s valid email address.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Save Card

Use `saveCard` to save the consumer's card details in Judopay's card vault.

:::hint{type="info"}
When making [Token Payments](docId:_3g7a0RAxGlG9AiC4VCWP), you can obtain the **card token** from the Save Card response.
:::

**Create an instance of the SaveCardModel**:

:::CodeblockTabs
PHP

```php
//Prepare the SaveCard request
$saveCardRequest = $judopay->getModel('SaveCard');

$saveCardRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/30'
    )
);

try {
    //Send the request to Judopay
    $response = $saveCardRequest->create();

    $receiptId = $response['receiptId'];
    if ($response['result'] == 'Success')
    {
        $cardToken = $response['cardDetails']['cardToken'];
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::hint{type="warning"}
**\*Mastercard Recommends:**
These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied.&#x20;
See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow).
:::

| **Parameter**                                                                                             | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardNumber`<br />String<br /><font color="#ef5b2e">Required</font>                                       | Submitted without whitespace or non-numeric characters.                                                                                                                                                                                                                                                                                                                                                                                             |
| `expiryDate`<br />String<br /><font color="#42cbd4">Optional</font>                                       | The expiry date of the card.<br />Format:<br />* MM/YY                                                                                                                                                                                                                                                                                                                                                                                              |
| `cardAddress`<br />Object<br /><font color="#ef5b2e">Re</font><font color="#ef5b2e">commended *</font>    | Card holder's address.<br />Values:<br />* `address1` <font color="#ef5b2e">(</font><font color="#ef5b2e">Recommended)</font><font color="#ef5b2e">*</font>
* `address2` (optional)
* `town`
* `state` (only required if country is USA/Canada)
* `country`&#xA;See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
* `postcode`<br />If the cardAddress is provided, the postcode is **required**. |
| `startDate`<br />String<br /><font color="#42cbd4">Optional</font>                                        | For Maestro cards:<br />Format:<br />* MM/YY                                                                                                                                                                                                                                                                                                                                                                                                        |
| `issueNumber`<br />Integer<br /><font color="#42cbd4">Optional</font>                                     | For Maestro cards:<br />* A number between 1 and 2 digits (from 0 to 99).
* Located on the front of the card.                                                                                                                                                                                                                                                                                                                                       |
| `yourConsumerReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>                 | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                              |
| `judoId
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>                                | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                         |
| `currency`<br />String<br /><font color="#42cbd4">Optional</font>                                         | The currency of the transaction. <br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                |
| `cardHolderName`<br />String<br /><font color="#ef5b2e">Re</font><font color="#ef5b2e">commended *</font> | The card name of the consumer.                                                                                                                                                                                                                                                                                                                                                                                                                      |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Token Payments

:::hint{type="info"}
You can create a token payment following a: **Payment&#x20;**| **PreAuth&#x20;**| **Save Card** operation, as a **card token** is always returned.
:::

**Create an instance of the TokenPaymentModel**:

:::CodeblockTabs
PHP

```php
//Prepare the TokenPayment request
$tokenPaymentRequest = $judopay->getModel('TokenPayment');

$tokenPaymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardToken' => 'cardTokenFromPreviousTransaction',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 customer-initiated transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => 'test.user@judopay.com',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        ),
        // Following are for merchant-initiated transactions
        'recurringPayment' => true,
        'recurringPaymentType' => 'mit', // Unscheduled, use recurring for scheduled payments
        'relatedReceiptId' => 'receiptIdOfOriginalCustomerInitiatedTransaction'
    )
);

try {
    //Send the request to Judopay
    $response = $tokenPaymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::hint{type="warning"}
**\*Mastercard Recommends:**
These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied.&#x20;
See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow).
:::

| **Parameter**                                                                               | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardToken`<br />String<br /><font color="#ef5b2e">Required</font>                          | Save the cardToken into your database to send back to Judopay, instead of inserting the consumer's card details.                                                                                                                                                                                                                                                                                                                                               |
| `yourConsumerReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>   | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />This must match the original **yourConsumerReference** when the token was initially created.                                                                                                                                                                                                                                                                         |
| `yourPaymentReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>    | Set your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.
* This value should be unique in order to protect your customers against duplicate transactions.&#x20;
* With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                          |
| `yourPaymentMetaData`&#xD;<br />IDictionary<br /><font color="#42cbd4">Optional</font>      | Additional information associated with a transaction to help reconcile.                                                                                                                                                                                                                                                                                                                                                                                        |
| `judoId
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>                  | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                                    |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font><br /><br />                | The amount to process.<br />Format:<br />* Two decimal places
* For currencies using a different structure please contact Judopay for support.                                                                                                                                                                                                                                                                                                                 |
| `currency`<br />String<br /><font color="#42cbd4">Optional</font>                           | The currency of the transaction. <br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                           |
| `userAgent`<br />String<br /><font color="#42cbd4">Optional</font>                          | Consumer's browser details.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `deviceCategory`<br />String<br /><font color="#42cbd4">Optional</font>                     | The type of device where the consumer is carrying out the transaction:<br />* Mobile                                                                                                                                                                                                                                                                                                                                                                           |
| `acceptHeaders`<br />String<br /><font color="#42cbd4">Optional</font>                      | Consumer's browser details.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `cardAddress`<br />Object<br /><font color="#42cbd4">Optional</font><br />                  | Card holder's billing address.<br />Values:<br />* `address1` <font color="#ef5b2e">(</font><font color="#ef5b2e">Recommended)</font><font color="#ef5b2e">*</font>
* `address2 `(optional)
* `town`
* `state` (only required if country is USA/Canada)
* `country`&#xA;See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
* `postcode`<br />If the billingAddress is provided, the postcode is **required**. |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>           | Indicates if this initial payment is part of a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                              |
| `recurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>                  | Indicates if this is a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `recurringPaymentType`<br />enum<br /><font color="#42cbd4">Optional</font><br /><br />**** | Type of recurring payment.<br />Values:<br />* **RECURRING**&#xA;Scheduled regular payment.
* **MIT&#x20;**(Merchant Initiated Transaction) Unscheduled regular payment.&#x20;<br />If a value is not set, the default value = **RECURRING**                                                                                                                                                                                                                   |
| `relatedReceiptId`<br />String<br /><font color="#42cbd4">Optional</font><br />             | The receiptId returned from the first subscription payment.<br />Adding the relatedReceiptId references the subsequent recurring transactions to the original transaction.                                                                                                                                                                                                                                                                                     |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Creating a PreAuth

**Create an instance of the CardPayment Model**:

:::CodeblockTabs
PHP

```php
//Prepare the Preauth request
$preauthRequest = $judopay->getModel('Preauth');

$preauthRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/30',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => 'test.user@judopay.com',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $preauthRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::hint{type="warning"}
**\*Mastercard Recommends:**
These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied.&#x20;
See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow).
:::

| **Parameter**                                                                                                           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font><br /><br />                                             | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font><br /><br />                                            | The amount to process.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font><br />                                                 | The currency of the transaction.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font>                                          | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `yourPaymentReference`<br />String<br /><font color="#ff6900">Required</font><br /><br />                               | Your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `phoneCountryCode`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br /><br /> | The country code of the consumer's phone.<br />Format:<br />* Maximum length 3 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **mobileNumber** is set.<br />If not set, default = 44                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `mobileNumber`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br /><br />     | Consumer’s valid mobile number.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.<br />Format:<br />* Maximum length 15 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **phoneCountryCode** is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `cardHolderName`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br />         | The card name of the consumer.<br />If the cardHolderName field is displayed to the user in the payment form (**isCardHolderNameVisible: true** is set in the iFrame config), the value entered in the payment form will overwrite this value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `challengeRequestIndicator`<br />String<br /><font color="#42cbd4">Optional</font><br /><br /><br />                    | Indicates the type of challenge request you wish to apply.<br />Set this to one of the following strings:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.<br />This **should not&#x20;**&#x62;e included in the same configuration object as **scaExemption**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scaExemption`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />                                       | To apply for an exemption from SCA, for a customer initiated transaction.<br />Set this to one of the following strings:<br />* `lowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `trustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `transactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.<br />This **should not** be included in the same configuration object as **challengeRequestIndicator**.                                                                                                                                                                                                                                                                                                                                |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>                                       | Indicates if this initial payment is part of a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `billingAddress`<br />Object<br /><font color="#42cbd4">Optional</font><br /><br />                                     | Card holder's billing address.<br />Properties:<br />* `address1` <font color="#ef5b2e">(</font><font color="#ef5b2e">Recommended)</font><font color="#ef5b2e">*</font>
* `address2` (optional)
* `town`
* `state` (only required if country is USA/Canada)
  - Format:
    - string
    - ISO Alpha-2 Code (e.g. California = "**CA**")
* `country`
  - Format:
    - string
    - See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
* `postCode`<br />If the billingAddress is provided, the postcode is **required**.                                                                                                                                                                                                                                                                                                                                                                                             |
| `emailAddress`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font>                 | Consumer’s valid email address.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `primaryAccountDetails`<br />Object<br /><font color="#42cbd4">Optional</font><br /><br />                              | This is **Mandatory&#x20;**&#x66;or merchants who have an MCC code of **6012**, **6051&#x20;**&#x61;nd **7299**.<br />Properties:<br />* `name`&#xA;**This is the surname.**
* `accountNumber`
* `postCode`
* `dateOfBirth`
  - Format: YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `businessApplicationId`<br />String<br /><font color="#A5F3FC">Optional</font>                                          | **Required for AFT transactions**.<br />Identifies the type / purpose of the transaction.<br />Format:<br />* Maximum 2 characters<br />Values:**&#xD;**<br />:::Paragraph{listStyleType="disc" indent="2"}
AA – Account to account
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
FD – Funds disbursement
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
FT – Funds transfer
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
PD – Payroll
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
TU – Top up
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
WT – Digital wallet
:::<br />* **Account Type**&#xA;Indicates the recipient's account type.****&#xA;Select from the following values:
  - 00 - Other
  - 01 - TRN & BAN
  - 02 - IBAN
  - 03 - Card (first6 & last4)
  - 06 - BAN & BIC (SWIFT code)<br />**Note**: If `businessApplicationId` is provided, `aftRecipientInformation` **must&#x20;**&#x61;lso be provided. |
| `aftRecipientInformation`<br />Object<br /><font color="#A5F3FC">Optional</font>                                        | **Required for AFT transactions**.<br />Contains recipient details.<br /><br />**Note**: If `aftRecipientInformation` is provided, `businessApplicationId` **must&#x20;**&#x61;lso be provided.<br />Values:<br />:::Paragraph{listStyleType="disc" indent="2"}
`firstName`&#xA;Recipient’s first name.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`addressLine1`&#xA;Recipient’s address line 1.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`countryCode`&#xA;ISO 3166-1 alpha-2 country code.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`accountType`&#xA;Type of recipient account.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`accountId`&#xA;Unique identifier of the recipient account.
:::<br />For more information, see [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg).                                                                                                                         |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Creating a Collection

:::hint{type="info"}
Partial collections are supported.&#x20;
Use the same **ReceiptId&#x20;**&#x74;o collect different amounts up to the original preauth amount.
**You cannot collect more than the original amount**.
:::

**Following the&#x20;**[preAuth](docId:_3g7a0RAxGlG9AiC4VCWP)**, prepare the collection**:

:::CodeblockTabs
PHP

```php
//Prepare the Collection request
$collectionRequest = $judopay->getModel('Collection');

$collectionRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourCollectionReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $collectionRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

| **Parameter**                                                                            | **Description**                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiptId`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>             | Judopay's reference for the pre authorisation that is to be collected.                                                                                                                                                       |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font>                         | The amount to collect must not exceed the amount of the original pre authorisation.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.               |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font>                        | If specified, the currency must match the original pre authorisation.<br />If not specified, the currency of the original pre authorisation will be used.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR |
| `yourPaymentReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font> | Your unique reference for this collection.<br />Format:<br />* Maximum length 50 characters.<br />**This is not the yourPaymentReference of the original pre authorisation**.                                                |
| `yourPaymentMetaData`<br />String<br /><font color="#42cbd4">Optional</font><br />       | Key-value map for additional metadata associated with this transaction.<br />Will be stored but not processed or passed to gateways.<br />Do not include sensitive information like card numbers.                            |

Check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Voiding a PreAuth Transaction

Cancel a pre-authorised transaction if the funds have not yet settled.

:::hint{type="warning"}
Voids cannot be performed on transactions that have been collected (partial or full).
:::

**Create a void request**:

:::CodeblockTabs
PHP

```php
//Prepare the Void request
$voidRequest = $judopay->getModel('VoidTransaction');

$voidRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId', // This attribute will not be required in the next version of the SDK
        'receiptId' => 'yourPreauthReceiptId',
        'yourPaymentReference' => 'yourVoidReference',
        'amount' => 1.01
    )
);

try {
    //Send the request to Judopay
    $response = $voidRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

| **Parameter**                                                                            | **Description**                                                                                                                                                                                                              |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiptId`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font>             | Judopay's reference for the pre authorisation that is to be voided.                                                                                                                                                          |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font>                         | The amount to void.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                               |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font>                        | If specified, the currency must match the original pre authorisation.<br />If not specified, the currency of the original pre authorisation will be used.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR |
| `yourPaymentReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font> | Your unique reference for this void.<br />Format:<br />* Maximum length 50 characters.<br />**This is not the yourPaymentReference of the original pre authorisation**.                                                      |
| `yourPaymentMetaData`<br />String<br /><font color="#42cbd4">Optional</font><br />       | Key-value map for additional metadata associated with this transaction.<br />Will be stored but not processed or passed to gateways.<br />Do not include sensitive information like card numbers.                            |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Creating a Payment

- Create an instance of the CardPayment Model:

:::CodeblockTabs
PHP

```php
//Prepare the Payment request
$paymentRequest = $judopay->getModel('Payment');

$paymentRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/30',
        'cv2' => '452',
        'amount' => 1.01,
        'currency' => 'GBP',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => 'test.user@judopay.com',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $paymentRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::hint{type="warning"}
**\*Mastercard Recommends:**
These fields are recommended rather than mandatory. Transactions will continue to be processed if not supplied.&#x20;
See, [Mastercard Recommended 3D Secure 2 Fields](docId\:WpFMF662qaIGEGrpU_Mow).
:::

| **Parameter**                                                                                                           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font><br /><br />                                             | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font><br /><br />                                            | The amount to process.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font><br />                                                 | The currency of the transaction.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font>                                          | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `yourPaymentReference`<br />String<br /><font color="#ff6900">Required</font><br /><br />                               | Your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `phoneCountryCode`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br /><br /> | The country code of the consumer's phone.<br />Format:<br />* Maximum length 3 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **mobileNumber** is set.<br />If not set, default = 44                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `mobileNumber`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br /><br />     | Consumer’s valid mobile number.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.<br />Format:<br />* Maximum length 15 characters.
* Only numbers allowed.
* Do not include special characters or spaces.<br />Must be set if **phoneCountryCode** is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `cardHolderName`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font><br />         | The card name of the consumer.<br />If the cardHolderName field is displayed to the user in the payment form (**isCardHolderNameVisible: true** is set in the iFrame config), the value entered in the payment form will overwrite this value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `challengeRequestIndicator`<br />String<br /><font color="#42cbd4">Optional</font><br /><br /><br />                    | Indicates the type of challenge request you wish to apply.<br />Set this to one of the following strings:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.<br />This **should not&#x20;**&#x62;e included in the same configuration object as **scaExemption**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `scaExemption`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />                                       | To apply for an exemption from SCA, for a customer initiated transaction.<br />Set this to one of the following strings:<br />* `lowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `trustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `transactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.<br />This **should not** be included in the same configuration object as **challengeRequestIndicator**.                                                                                                                                                                                                                                                                                                                                |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>                                       | Indicates if this initial payment is part of a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `billingAddress`<br />Object<br /><font color="#42cbd4">Optional</font><br /><br />                                     | Card holder's billing address.<br />Properties:<br />* `address1` <font color="#ef5b2e">(</font><font color="#ef5b2e">Recommended)</font><font color="#ef5b2e">*</font>
* `address2` (optional)
* `town`
* `state` (only required if country is USA/Canada)
  - Format:
    - string
    - ISO Alpha-2 Code (e.g. California = "**CA**")
* `country`
  - Format:
    - string
    - See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.
* `postCode`<br />If the billingAddress is provided, the postcode is **required**.                                                                                                                                                                                                                                                                                                                                                                                             |
| `emailAddress`<br />String<br /><font color="#ef5b2e">Recommended</font> <font color="#ef5b2e">*</font>                 | Consumer’s valid email address.<br /><br />Mastercard recommends providing at least **one contact method** for Mastercard 3D Secure authenticated transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `primaryAccountDetails`<br />Object<br /><font color="#42cbd4">Optional</font><br /><br />                              | This is **Mandatory&#x20;**&#x66;or merchants who have an MCC code of **6012**, **6051&#x20;**&#x61;nd **7299**.<br />Properties:<br />* `name`&#xA;**This is the surname.**
* `accountNumber`
* `postCode`
* `dateOfBirth`
  - Format: YYYY-MM-DD                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `businessApplicationId`<br />String<br /><font color="#A5F3FC">Optional</font>                                          | **Required for AFT transactions**.<br />Identifies the type / purpose of the transaction.<br />Format:<br />* Maximum 2 characters<br />Values:**&#xD;**<br />:::Paragraph{listStyleType="disc" indent="2"}
AA – Account to account
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
FD – Funds disbursement
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
FT – Funds transfer
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
PD – Payroll
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
TU – Top up
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
WT – Digital wallet
:::<br />* **Account Type**&#xA;Indicates the recipient's account type.****&#xA;Select from the following values:
  - 00 - Other
  - 01 - TRN & BAN
  - 02 - IBAN
  - 03 - Card (first6 & last4)
  - 06 - BAN & BIC (SWIFT code)<br />**Note**: If `businessApplicationId` is provided, `aftRecipientInformation` **must&#x20;**&#x61;lso be provided. |
| `aftRecipientInformation`<br />Object<br /><font color="#A5F3FC">Optional</font>                                        | **Required for AFT transactions**.<br />Contains recipient details.<br /><br />**Note**: If `aftRecipientInformation` is provided, `businessApplicationId` **must&#x20;**&#x61;lso be provided.<br />Values:<br />:::Paragraph{listStyleType="disc" indent="2"}
`firstName`&#xA;Recipient’s first name.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`addressLine1`&#xA;Recipient’s address line 1.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`countryCode`&#xA;ISO 3166-1 alpha-2 country code.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`accountType`&#xA;Type of recipient account.
:::<br />:::Paragraph{listStyleType="disc" indent="2"}
`accountId`&#xA;Unique identifier of the recipient account.
:::<br />For more information, see [Account Funding Transactions](docId:5ol_pTSGBHVGKwJwD0gHg).                                                                                                                         |

If **result.HasError = false**, check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## 3D Secure 2 Transaction Flow

Authenticate a **3D Secure 2** transaction to allow for additional transaction checks required for compliance with Strong Customer Authentication (SCA).&#x20;
For more information on 3D Secure 2 and SCA, see [Managing SCA Compliance](docId\:uLg1uCaYg3ljb7t0SVcw5).

:::hint{type="warning"}
Make sure your account has **3D Secure 2 API credentials&#x20;**&#x65;nabled.&#x20;
Contact ​Customer Support​​ to set this up.
:::

The instance of the **CardPaymentModel** you created for [Creating a Payment](docId:_3g7a0RAxGlG9AiC4VCWP), just needs the following **additional 3D Secure 2 parameters** to be included:

:::CodeblockTabs
PHP

```php
// See Payment, PreAuth sections for details of how to trigger an initial transaction with required 3DS2 attributes

// If the response indicated device details check are required, POST the returned md (as an attribute named
// threeDSMethodData) to the returned methodUrl, and wait for a call from ACS to the methodNotificationUrl supplied on
// the initial transaction

// Once the call to the methodNotificationUrl has been received, resume the transaction flow to Judopay
$resumeRequest = $judopay->getModel('ResumeThreeDSecureTwo');
$resumeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'methodCompletion' => 'yes',
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $resumeResponse = $resumeRequest->update();

    if ($resumeResponse['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $resumeResponse['challengeUrl'];
        $creq = $resumeResponse['creq'];
    }
    else
    {
        // Transaction has been processed
        $receiptId = $response['receiptId'];
        $status = $response['result'];
    }
}
catch (\Judopay\Exception\ApiException $resumeApiException)
{
    $resumeErrorResponse = "{\"error\":\"{$resumeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $resumeValidationErrors)
{
    // Required attributes are missing from the request
    $resumeErrorResponse = "{\"error\":\"{$resumeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $resumeException)
{
    $resumeErrorResponse = "{\"error\":\"".$resumeException->getMessage()."\",\"result\":\"Error\"}";
}


// If either the initial transaction response, or the resume response, indicated a challenge is required, POST the
// returned creq to the returned challengeUrl, and wait for a call from ACS to the challengeNotificationUrl supplied on
// the initial transaction

// Once the call to the challengeNotificationUrl has been received, complete the transaction flow to Judopay

$completeRequest = $judopay>getModel('CompleteThreeDSecureTwo');
$completeRequest->setAttributeValues(
    array(
        'receiptId' => $response['receiptId'], // receiptId of the original transaction
        'cv2' => '452',
        // primaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        )
    )
);

try {
    //Send the request to Judopay
    $completeResponse = $completeRequest->update();

    // Transaction has been processed
    $receiptId = $completeResponse['receiptId'];
    $status = $completeResponse['result'];
}
catch (\Judopay\Exception\ApiException $completeApiException)
{
    $completeErrorResponse = "{\"error\":\"{$completeApiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $completeValidationErrors)
{
    // Required attributes are missing from the request
    $completeErrorResponse = "{\"error\":\"{$completeValidationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $completeException)
{
    $completeErrorResponse = "{\"error\":\"".$completeException->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

:::ExpandableHeading
### Additional 3D Secure 2 Parameters

| **Parameter**                                                             | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cardHolderName`<br />String<br /><font color="#bf5b2e">Required</font>   | The full name of the card holder.<br />**When testing in the sandbox environment, it is the cardHolderName that is used to determine the test card for 3D Secure 2 authentication.**<br />Format:<br />* Alphanumeric
* Length: 2-45 characters
* Allowed special characters: \[.-'␣]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `mobileNumber`<br />String<br /><font color="#42cbd4">Optional</font>     | Consumer’s valid UK mobile number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `phoneCountryCode`<br />String<br /><font color="#42cbd4">Optional</font> | The country code of the consumer's phone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `emailAddress`<br />String<br /><font color="#42cbd4">Optional</font>     | Consumer’s valid email address.<br />**It is recommended but not required for 3D Secure 2 authentication.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `threeDSecure`<br />Object<br /><font color="#bf5b2e">Required</font>     | For any 3D Secure 2 requests.<br />`authenticationSource` indicates the type of channel used to initiate the transaction.<br />Format:<br />* enum<br />Values:<br />* Unknown
* Browser
* Merchant\_Initiated
* Mobile\_Sdk<br />`challengeRequestIndicator` indicates the type of 3D Secure 2 challenge request.<br />Format:<br />* enum<br />Values:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.<br />`scaExemption` The customer initiated transaction type, that is exempt from SCA.<br />Format:<br />* enum<br />Values:<br />* `LowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `TrustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `TransactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.<br /><br />Make sure when testing:<br />* `methodNotificationUrl`&#xA;and&#x20;
* `challengeNotificationUrl`<br />you use a **real URL** for the values.<br />**If you use a localhost URL, it will not work**.<br />`methodNotificationUrl` The URL that will receive the method completion message, confirming the Issuer has completed the device details check.<br />* URL
* Length: 1-256 characters<br />`challengeNotificationUrl` The URL that will receive the outcome of the challenge request to the consumer.<br />* URL
* Length: 1-256 characters |


:::

If no additional transaction checks are required, you will receive the usual **paymentReceipt&#x20;**&#x72;esponse.

If additional transaction checks are required, you will receive the **challenge&#x20;**&#x72;esponse.

:::ExpandableHeading
### ResumeThreeDSecureTwo Model Parameters

| **Parameter**                                                                  | **Description**                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cv2`<br />String<br /><font color="#bf5b2e">Required</font>                   | The 3 or 4 digit number on the back of a credit card.<br />Also known as the card verification value (CVV) or security code.                                                                                                                           |
| `primaryAccountDetails`<br />Object<br /><font color="#42cbd4">Optional</font> | For **MCC 6012, 6051&#x20;**&#x61;nd **7299&#x20;**&#x6D;erchants, this object needs to be added to the request. Without this, 3D Secure 2 transactions **will not** be successful.<br /> Values:<br />* name
* accountNumber
* dateOfBirth
* postCode |
| `methodCompletion`<br />enum<br /><font color="#bf5b2e">Required</font>        | Indicates if the 3DS ACS method to collect the device details was completed successfully.<br />Values:<br />* Unknown
* Yes
* No
* Unavailable                                                                                                         |


:::

:::ExpandableHeading
### CompleteThreeDSecureTwo Model Parameters

| **Parameter**                                                                        | **Description**                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cv2`<br />String<br /><font color="#bf5b2e">Required</font><br />                   | The 3 or 4 digit number on the back of a credit card.<br />Also known as the card verification value (CVV) or security code.                                                                                                                           |
| `primaryAccountDetails`<br />Object<br /><font color="#42cbd4">Optional</font><br /> | For **MCC 6012, 6051&#x20;**&#x61;nd **7299&#x20;**&#x6D;erchants, this object needs to be added to the request. Without this, 3D Secure 2 transactions **will not** be successful.<br /> Values:<br />* name
* accountNumber
* dateOfBirth
* postCode |
:::

Check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

### Payment Receipt

:::ExpandableHeading
### Payment Receipt Model Parameters

| **Parameter**                                            | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiptId`<br />String                                  | Judopay's reference for the transaction.<br />Used to process refunds or collections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `yourPaymentReference`<br />String                       | Your unique reference for this payment. <br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed.                                                                                                                                                                                                                                                                                                                 |
| `type`<br />String                                       | Type of transaction:<br />* Payment
* Refund
* PreAuth
* Collection<br />**This transaction type is available from API Version 6.4.1 onwards**.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `acquirerTransactionID`<br />String                      | The unique ID of a transaction set by the acquirer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `createdAt`<br />Date                                    | An ISO8601 formatted date and time.<br />Includes time zone offset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `result`<br />String                                     | Result of transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `message`<br />String                                    | Message detailing the outcome.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `externalBankResponseCode`<br />String                   | Reason code provided by the bank for declined transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `judoId`<br />String                                     | Unique ID supplied by Judopay. <br />Specific to a merchant and/or location.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `merchantName`<br />String                               | Merchant's trading name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `appearsOnStatementAs`<br />String                       | How the Merchant appears on the consumer's statement.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `originalAmount`<br />Decimal                            | Amount of transaction.<br />**This field will not be included for Refund and PreAuth transaction types.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `amountCollected`<br />Decimal                           | Amount collected.<br />**This field will be included for the PreAuth transaction type.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `netAmount`<br />Decimal                                 | The remaining balance of the transaction after a refund.<br />You cannot refund more than the original transaction amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `amount`<br />Decimal                                    | The amount to process.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `currency`<br />String                                   | The currency of the transaction.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `cardDetails`<br />Object                                | Information on the card used in this transaction:<br />* cardLastFour
* endDate
* cardToken
* cardType
* startDate
* cardScheme
* cardFunding
* cardCategory
* cardCountry
* bank                                                                                                                                                                                                                                                                                                                                                                                                 |
| `consumer`<br />Object                                   | Details of the consumer.<br />Used for repeat transactions.<br />Details:<br />* yourConsumerReference                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `device`<br />Object                                     | Specific device details to identify a consumer:<br />* identifier                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `riskScore`<br />Integer                                 | Consumer's risk score.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `yourPaymentMetaData`<br />String                        | Additional information associated with a transaction to help reconcile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `threeDSecure`<br />Object                               | For any 3DSecure requests.<br />Includes the result of the authentication process:<br />* attempted
* result<br />**This block will not be returned for voids / refunds or collections responses**.                                                                                                                                                                                                                                                                                                                                                                               |
| `challengeRequestIndicator`<br />String                  | Indicates the type of challenge request you wish to apply.<br />Values:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.                                                                                                                                                                                                                                                                                                    |
| `scaExemption`<br />String                               | To apply for an exemption from SCA, for a customer initiated transaction.<br />Values:<br />* `lowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `secureCorporate`
  - Request exemption for payments made using a corporate card.
* `trustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `transactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed. |
| `risks`<br />Object                                      | Risk checks on:<br />* postCodeCheck
* cv2Check
* merchantSuggestion
* merchantStatistics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `recurring`<br />Boolean                                 | Is the transaction a recurring transaction?<br />**If false, the field will not be returned**.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `recurringPaymentType`<br />enum<br /><br /><br /><br /> | Type of recurring payment.<br />Values:<br />* RECURRING
  - Scheduled regular payment.
* MIT (Merchant Initiated Transaction)
  - Unscheduled regular payment.<br />recurringPaymentType is required if `recurringPayment `= **true**.                                                                                                                                                                                                                                                                                                                                           |


:::

***

## Creating a Refund

You can process a **full&#x20;**&#x6F;r **partial&#x20;**&#x72;efund.

:::hint{type="warning"}
Ensure the **Refund Payments** permission is enabled on your API token.
:::

**Create a refund request**:

:::CodeblockTabs
PHP

```php
//Prepare the Refund request
$refundRequest = $judopay->getModel('Refund');

$refundRequest->setAttributeValues(
    array(
        'receiptId' => 'yourPaymentReceiptId',
        'yourPaymentReference' => 'yourRefundReference',
        'amount' => 1.01 // Optional, if not specified full payment amount will be refunded
    )
);

try {
    //Send the request to Judopay
    $response = $refundRequest->create();

    $receiptId = $response['receiptId'];
    $status = $response['result'];
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}
```
:::

| **Parameter**                                                                            | **Description**                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiptId`<br />String<br /><font color="#ef5b2e">Required</font>                       | Judopay's reference for the transaction that is to be refunded.                                                                                                                                                  |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font>                         | The amount to refund.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                 |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font>                        | If specified, the currency must match the original transaction.<br />If not specified, the currency of the original transaction will be used.<br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR |
| `yourPaymentReference
`<br />String&#xD;<br />&#xD;<font color="#ef5b2e">Required</font> | Your unique reference for this refund.<br />Format:<br />* Maximum length 50 characters.<br />**This is not the yourPaymentReference of the original transaction**.                                              |

Check the [Payment Receipt Model](docId:_3g7a0RAxGlG9AiC4VCWP) response.&#x20;

***

## Going Live

Test all your required transaction types in the **live environment** before deploying your app.

:::hint{type="warning"}
You will need to have tested your app in the sandbox environment before going live.
:::

:::::WorkflowBlock
:::WorkflowBlockItem
Activate your Account.
To process live payments, ensure you have a live account.

- Complete the activation form for us to make the necessary changes to your account.&#x20;

We will contact you as soon as you are live.
:::

::::WorkflowBlockItem
Point to the Live Environment.

- Replace your sandbox API Token and Secret for the live API Token and Secret&#x20;
  - Find these in **Judopay Portal** > **Your apps** > \{**app name**} >**&#x20;Live Tokens**

:::CodeblockTabs
PHP

```php
//In the Judopay object change the production environment setting from false to true: 'useProduction' => true

$judopay = new \Judopay(    
array(       
    'apiToken' => 'your-token,       
    'apiSecret' => 'your-secret',        
    'judoId' => 'your-judo-id',    
    
    //Set to true on production, defaults to false which is the sandbox  
      
    'useProduction' => true    )
);
```
:::
::::

:::WorkflowBlockItem
Test Live Payments.

- Ensure the SDK is properly configured for the **live&#x20;**&#x65;nvironment.
- Use real debit or credit cards.
  - Test cards provided will not work in live.
  - We recommend to perform pre-authorizations followed by a void, or regular payments followed by a refund.&#x20;
  - Send a refund through the **Judopay Portal** > **History.**
- Test all payment scenarios and security features to verify the expected behaviour.
:::
:::::

***

# WooCommerce Plugin

:::hint{type="warning"}
We are no longer supporting the WooCommerce plugin. This is now deprecated.
:::

This version of the Judopay WooCommerce plugin uses Judopay's Web Payments solution, to take online card payments as well as Apple Pay™ and Google Pay™.
The plugin supports **3D Secure 2.0** transactions, if the issuing bank requires.

### Prerequisites

Below are the versions of systems this plugin has been developed and tested on. Although other versions may work, they are not guaranteed:

- WordPress: Version **6.8.1**
- WooCommerce: Version **9.9.3**
- PHP: Version **8.1.2**
- Contact [Developer Support](mailto\:developersupport@judopay.com) for the **WooCommerce plugin file**.

:::hint{type="warning"}
If you are not using these versions the lower versions may work but are **not guaranteed**.&#x20;
Judopay will not be making any modifications to accommodate lesser working versions.

Equally, any new versions that may cause functionality to fail will be looked at on a best-case scenario.
:::

***

## WordPress Configuration Requirement

It is important that the Permalink configuration within WordPress is set to Post name.

For example:
`https://www.yourdomain.com/wordpress/sample-post/`

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/bpfjf7y6_RAX-4TZoobmx_permalinks.png" size="32" width="385" height="280" position="flex-start" alt="permalinks" darkWidth="385" darkHeight="280" showCaption="false"}

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/FcR0sh8OOhAaIZVQxiBvX_post-name.png" size="66" width="1627" height="562" position="flex-start" alt="post name" darkWidth="1627" darkHeight="562" showCaption="false"}

:::hint{type="warning"}
Ensure you are careful when changing this, if any other plugins require a different configuration this may cause issues with other plugins.

If you are unsure then **do not use&#x20;**&#x74;his plugin.
:::

***

## Installation

Ensure you have WooCommerce installed and working as desired.

Go to the WordPress **Plugins&#x20;**&#x73;ection
Select **Add New**

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/nDlcwLGDljvZhElB8MCGY_add-new-plugin.png" size="20" width="151" height="637" position="flex-start" alt="add new plugin" darkWidth="151" darkHeight="637" showCaption="false"}

Selec&#x74;**&#x20;Upload Plugin**
Click **Choose File**

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/zqXo34v-SZRiOmRvbmnVQ_choose-file.png" size="60" width="1242" height="260" position="flex-start" alt="choose plugin file" darkWidth="1242" darkHeight="260" showCaption="false"}

Locate the **judopayhosted.zip&#x20;**&#x66;ile, then click **Install Now**

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/By5KQw-f6a_GTSePG3o-h_install-plugin.png" size="60" width="1330" height="283" position="flex-start" alt="install plugin" darkWidth="1330" darkHeight="283" showCaption="false"}

Click **Activate Plugin** to activate the plugin

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/6NFYOgRAjAV9c3mpuCC2f_activate-plugin.png" size="56" width="580" height="229" position="flex-start" darkWidth="580" darkHeight="229" showCaption="false"}

The installation is now complete.

***

## Configure WooCommerce

In plugins for **WooCommerce**
Click **Settings**&#x20;

![woocommerce settings](https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/NK9yDQjSRyLx0q_t4D32i_settiings.png)

Click on the **Payments&#x20;**&#x74;ab

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/A45GTJRlBViP9j7IXYPBF_payments-woocommerce.png" size="82" width="1735" height="759" position="flex-start" alt="woocommerce configuration" darkWidth="1735" darkHeight="759" showCaption="false"}

Toggle the **Enabled&#x20;**&#x62;utton to enable Judopay Hosted Gateway.

To configure your Judopay Plugin Details, click **Manage**

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/dIk8GfcVT6FP_50p33YMY_toggle.png" size="94" width="1684" height="64" position="flex-start" alt="enable plugin" darkWidth="1684" darkHeight="64" showCaption="false"}

***

## Configure the Judopay Plugin

:::hint{type="info"}
Sandbox mode is enabled by default and will use the **Sandbox Account**.
:::

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/LGoJvse0X-P0OudZAjaMY_configure.png" size="82" width="639" height="307" position="flex-start" alt="configure plugin" darkWidth="639" darkHeight="307" showCaption="false"}

When you are ready t&#x6F;**&#x20;go live** and have a live account, **de-select Enable Sandbox Mode** to receive live payments.

Contact your sales adviser (sales\@judopayments.com) in order to set up a live transacting account.

**Debug Mode** will log to the WordPress log file if required.

:::hint{type="info"}
This **will not** log card details in any way.
:::

- **apiToken**: This your unique API Token from your Judopay Account.
- **apiSecret**: This your unique API Secret from your Judopay Account.
- **judoId**: This is your unique JudoId.

For assistance with your Judopay Account, contact [help@judopay.com
](https://help@judopay.com)Sign up for a free Sandbox Account [here](https://www.judopay.com/apply-sandbox-account).

***

### Checkout View

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/yFL85Bz00bIlCHKkF66TV_place-order.png" size="70" width="1120" height="584" position="flex-start" alt="place order" darkWidth="1120" darkHeight="584" showCaption="false"}

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/E-OJ1cbLBkv1o3xNQSJHv_pay-now.png" size="28" width="205" height="311" position="flex-start" alt="pay now" darkWidth="205" darkHeight="311" showCaption="false"}

***

### Success and Failure URLs

- Once the plugin is set up, login to **portal.judopay.com** and set up your success and failure URLs.
- The API token used by the plugin needs to use the following as its success / failure URL:
  `https://www.yoursite.com/wc-api/judopay_webhook`
  - Where **yoursite.com** is your WordPress site.
- This is the return URL for Judopay to call the WooCommerce site and update the transaction status.

***

# Register Card

:::hint{type="warning"}
We are no longer supporting or updating Register Card as it is an outdated method to verify cards, and **is now deprecated**.
[Check Card](https://docs.judopay.com/net-and-php-integrations#LUbTm) is the recommended card verification method required by the Card Schemes.&#x20;
:::

Use `registerCard` to save the consumer's card details in Judopay's card vault.

:::hint{type="info"}
When making [Token Payments](docId\:hNgLLJxESInHS7PtfEvTN), you can obtain the **card token** from the Register Card response.
:::

**Create an instance of the RegisterCard Model:**

:::CodeblockTabs
.NET

```apex
//Create an instance of the RegisterCard Model
var registerCardRequest = new RegisterCardModel
{
    JudoId = "yourJudoId",
    YourConsumerReference = "yourConsumerReference",
    YourPaymentReference = "yourPaymentReference",
    CardNumber = "4976000000003436",
    ExpiryDate = "12/25",
    CV2 = "452",
    CardAddress = new CardAddressModel
    {
        Address1 = "41 Luke St",
        PostCode = "EC2A 4DP",
        Town = "London",
        CountryCode = 826
    },
    // PrimaryAccountDetails only required for MCC6012 merchants
    PrimaryAccountDetails = new PrimaryAccountDetailsModel
    {
        Name = "Smith",
        AccountNumber = "1234567",
        DateOfBirth = "2000-12-31",
        PostCode = "EC2A 4DP"
    },
    // Following are for 3DS2 transactions
    PhoneCountryCode = "44",
    MobileNumber = "7999123456",
    EmailAddress = "test.user@judopay.com",
    CardHolderName = "John Smith",
    ThreeDSecure = new ThreeDSecureTwoModel
    {
        AuthenticationSource = ThreeDSecureTwoAuthenticationSource.Browser,
        ChallengeRequestIndicator = ThreeDSecureTwoChallengeRequestIndicator.ChallengeAsMandate,
        MethodNotificationUrl = "https://yourMethodNotificationUrl",
        ChallengeNotificationUrl = "https://yourChallengeNotificationUrl"
    }
};

//Send the request to Judopay
var response = await client.RegisterCards.Create(registerCardRequest);

if (response.HasError)
{
    if (response.Error.Code == (int)HttpStatusCode.Forbidden)
    {
        // Failed to authenticate - check your credentials
    }
    else if (response.Error.ModelErrors != null)
    {
        // Validation failed on the request, check each list entry for details
    }
    else
    {
        // Refer to https://docs.judopay.com/Content/Developer%20Tools/Codes.htm#Errors
        var errorCode = response.Error.Code;
    }
}
else if (response.Response is PaymentRequiresThreeDSecureTwoModel threeDSecureTwoResponseModel)
{
    if (threeDSecureTwoResponseModel.MethodUrl != null)
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        var methodUrl = threeDSecureTwoResponseModel.MethodUrl;
        var md = threeDSecureTwoResponseModel.Md;
    }
    else if (threeDSecureTwoResponseModel.ChallengeUrl != null)
    {
        // Challenge is required - POST creq to challengeUrl
        var challengeUrl = threeDSecureTwoResponseModel.ChallengeUrl;
        var creq = threeDSecureTwoResponseModel.CReq;
    }
}
else if (response.Response is PaymentReceiptModel receipt)
{
    var receiptId = receipt.ReceiptId;
    var status = receipt.Result;
    if (receipt.Result == "Success")
    {
        var cardToken = receipt.CardDetails.CardToken;
    }
}
```

PHP - Deprecated.

```php
//Prepare the RegisterCard request
$registerCardRequest = $judopay->getModel('RegisterCard');

$registerCardRequest->setAttributeValues(
    array(
        'judoId' => 'yourJudoId',
        'yourConsumerReference' => 'yourConsumerReference',
        'yourPaymentReference' => 'yourPaymentReference',
        'cardNumber' => '4976000000003436',
        'expiryDate' => '12/25',
        'cv2' => '452',
        'cardAddress' => array(
            'address1' => '41 Luke St',
            'postCode' => 'EC2A 4DP',
            'town' => 'London',
            'countryCode' => 826
        ),
        // PrimaryAccountDetails only required for MCC6012 merchants
        'primaryAccountDetails' => array(
            'name' => 'Smith',
            'accountNumber' => '1234567',
            'dateOfBirth' => '2000-12-31',
            'postCode' => 'EC2A 4DP'
        ),
        // Following are for 3DS2 transactions
        'phoneCountryCode' => '44',
        'mobileNumber' => '7999123456',
        'emailAddress' => 'test.user@judopay.com',
        'cardHolderName' => 'John Smith',
        'threeDSecure' => array(
            'authenticationSource'      => 'Browser',
            'challengeRequestIndicator' => 'ChallengeAsMandate',
            'methodNotificationUrl'     => 'https://yourMethodNotificationUrl',
            'challengeNotificationUrl'  => 'https://yourMethodNotificationUrl'
        )
    )
);

try {
    //Send the request to Judopay
    $response = $registerCardRequest->create();

    if ($response['methodUrl'])
    {
        // Device details are required - POST md as threeDSMethodData to methodUrl
        $methodUrl = $response['methodUrl'];
        $md = $response['md'];
    }
    else if ($response['challengeUrl'])
    {
        // Challenge is required - POST creq to challengeUrl
        $challengeUrl = $response['challengeUrl'];
        $creq = $response['creq'];
    }
    else
    {
        $receiptId = $response['receiptId'];
        if ($response['result'] == 'Success')
        {
            $cardToken = $response['cardDetails']['cardToken'];
        }
    }
}
catch (\Judopay\Exception\ApiException $apiException)
{
    $errorResponse = "{\"error\":\"{$apiException->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Judopay\Exception\ValidationError $validationErrors)
{
    // Required attributes are missing from the request
    $errorResponse = "{\"error\":\"{$validationErrors->getSummary()}\",\"result\":\"Error\"}";
}
catch (\Exception $e)
{
    $errorResponse = "{\"error\":\"".$e->getMessage()."\",\"result\":\"Error\"}";
}

```
:::

:::hint{type="info"}
You do not need to set an amount.&#x20;
This is automatically set by Judopay's Transaction API in order to register the card.
:::

The receipt response will show the payment: **Type = PreAuth**.

| **Parameter**                                                                             | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `yourConsumerReference
`<br />String&#xD;<br />&#xD;<font color="#bf5b2e">Required</font> | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `yourPaymentReference
`<br />String&#xD;<br />&#xD;<font color="#bf5b2e">Required</font>  | Judopay's Server SDK sets this value automatically. If you insert a value, the SDK will change it. This value is unique in order to protect your customers against duplicate transactions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `yourPaymentMetaData`&#xD;<br />IDictionary<br /><font color="#42cbd4">Optional</font>    | Additional information associated with a transaction to help reconcile.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `judoId
`<br />String&#xD;<br />&#xD;<font color="#bf5b2e">Required</font>                | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100&#xD;
* Maximum length 9 characters.&#xD;
* Do not include spaces or dashes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `cardNumber`<br />String<br /><font color="#bf5b2e">Required</font>                       | Submitted without whitespace or non-numeric characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `currency`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />             | The currency of the transaction. <br />Any ISO 4217 alphabetic currency code:<br />* GBP
* USD
* EUR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `cv2`<br />String<br /><font color="#bf5b2e">Required</font><br />                        | The 3 or 4 digit number on the back of a credit card.<br />Also known as the card verification value (CVV) or security code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `startDate`<br />String<br /><font color="#42cbd4">Optional</font>                        | For Maestro cards:<br />Format:<br />* MM/YY                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `expiryDate`<br />String<br /><font color="#42cbd4">Optional</font>                       | The expiry date of the card.<br />Format:<br />* MM/YY                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `issueNumber`<br />Integer<br /><font color="#42cbd4">Optional</font>                     | For Maestro cards:<br />* A number between 1 and 2 digits (from 0 to 99).
* Located on the front of the card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `initialRecurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>         | Indicates if this initial payment is part of a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `recurringPayment`<br />Boolean<br /><font color="#42cbd4">Optional</font>                | Indicates if this is a recurring payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `relatedReceiptId`<br />String<br /><font color="#42cbd4">Optional</font><br />           | The receiptId returned from the first subscription payment.<br />Adding the relatedReceiptId references the subsequent recurring transactions to the original transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `threeDSecure`<br />Object<br /><font color="#bf5b2e">Required</font>                     | For any 3D Secure 2 requests.<br />`authenticationSource` indicates the type of channel used to initiate the transaction.<br />Format:<br />* enum<br />Values:<br />* Unknown
* Browser
* Merchant\_Initiated
* Mobile\_Sdk<br />`challengeRequestIndicator`<br />Indicates the type of 3D Secure 2 challenge request.<br />Format:<br />* enum<br />Values:<br />* `noPreference`
* `noChallenge`
  - No challenge required.
* `challengePreferred`
  - A challenge is preferred for this transaction.
* `challengeAsMandate`
  - Must challenge this transaction.<br />`scaExemption`<br />The customer initiated transaction type, that is exempt from SCA.<br />Format:<br />* enum<br />Values:<br />* `LowValue`
  - Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.
* `SecureCorporate`
  - Request exemption for payments made using a corporate card.
* `TrustedBeneficiary`
  - Provides the cardholder the option to add the merchant to their trusted list.
* `TransactionRiskAnalysis`
  - Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed. |

If **result.HasError = false**, check the [Payment Receipt Model](docId\:hNgLLJxESInHS7PtfEvTN) response.&#x20;

***

## Testing RegisterCard

:::hint{type="warning"}
We are no longer supporting or updating Register Card as it is an outdated method to verify cards, and **is now deprecated**.
[Check Card](https://docs.judopay.com/net-and-php-integrations#LUbTm) is the recommended card verification method required by the Card Schemes.&#x20;
:::

These scenarios do not include 3D Secure 2 authentication testing.
See [Testing 3D Secure 2 Flows](docId\:BdCGiYQDm3mlE-UBxp1yR) for 3D Secure 2 authentication testing for your app.

***

### RegisterCard Scenarios (Positive Flow)

`RegisterCard` conducts a pre-authorisation by reserving a pre-configured amount in the customer's account.

:::hint{type="info"}
The pre-configured amount is set during your on-boarding process (**the default amount is 1.01**).
:::

RegisterCard will tokenise the card information into an encrypted string, which can be used for future transactions.

:::hint{type="info"}
The POST `/transactions/voids` endpoint can be used to cancel this pre-authorisation so it does not appear in the customer's statement.
:::

**Important to Consider**

- RegisterCard tests involve **verification&#x20;**&#x6F;f:
  - The **card**:
    - cardNumber
    - cardExpiryDate
    - cv2
  - The **account**:
    - Is not blocked or blacklisted
    - Exists
- Tokenises the card number into an encrypted string.
- Store **yourConsumerReference&#x20;**&#x61;nd **cardToken&#x20;**&#x61;nd supply these in future card payment, preAuth, or Merchant Initiated Transaction requests.

A successful registerCard request verifies the card with the issuer and can be authenticated using 3D Secure 2, providing you with the confidence the card is **valid&#x20;**&#x74;o make future payments.

| **Suggested Test Scenario**                                                                                                                                                              | **Expected Outcome** | **Tip**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Process a registerCard request with the CV2/CVV security code included in the request.<br />This will check the CV2/CVV is valid for that card.                                          | 200<br />Successful  | The CV2 field check will be performed during the transaction process.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Process a registerCard request without the CV2/CVV security code included in the request.                                                                                                | Declined             | The CV2 field check will not be performed during the transaction process.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Process a registerCard request with the billing address information (cardAddress block) included in the request.<br />This will validate the billing address is registered to that card. | 200<br />Successful  | Ensure the **cardAddress** block has the correct fields:<br />* `address1`
* `address2`
* `town`
* `postCode`
  - Required
* `countryCode`
  - See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.<br />Example cardAddress block:<br />:::BlockQuote
"cardAddress": \{ &#xA;"address1": "CardHolder House", &#xA;"address2": "1 CardHolder Street", &#xA;"address3": "CardHolder Area", &#xA;"town": "CardHolder Town", &#xA;"postCode": "AB1 2CD", &#xA;"countryCode": 826, &#xA;"state": "FL", &#xA;},
:::<br />To validate the card is registered to the correct post code, ensure the following permission on your sandbox API Credentials is enabled:<br />* **Enforce AVS checks**.<br />**The default setting = disabled**. |
| Process a registerCard request without the billing address information (cardAddress block) included in the request.                                                                      | 200<br />Successful  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

For more information on API credentials and permissions, see [Permissions](docId\:S_8hOAMytkgY13t0P657-).

***

### Test Card Data

To simulate a successful registerCard request use the [Test Cards](docId:_OBafnuC1Umhk-vIhHs5D).

***

### Register Card Request Parameters

Sandbox endpoint:
`https://api-sandbox.judopay.com/transactions/registercard`

HTTP Method: **POST**

**Header Parameters:**

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<br />For the latest version of the Judopay Transaction API, see [Latest Version](docId\:bcXNM5keOk-nlNrZTafUT).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Content-Type:                                                    | application/json                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Accept:                                                          | application/json                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Authorization Method**:<br />TokenSecretAuth                   | In the Authorization Header:<br />* Supply: **Basic** \{`authstring`}<br />Example:<br />**Basic**`TXpFdPdRSzWmSGk4djhxeTpjBTS4YjQ5OTdkZmO7CTk1YTE0OWEyMDg1MmY3YWYyZWEyZTcwYmQyZGY3O`<br />Replace \{`authstring`} with **base64 encoding** of:<br />* <font color="#6a4ee1">**API Token**</font> (username)
* <font color="#ef5b2e">**Colon**</font>
* **API Secret** (password)<br />Example:<br /><font color="#6a4ee1">**MzPdkQK1mGi8v3ky**</font><font color="#ef5b2e">**:**</font>**y158n4732dfc7595a149a20381f7af2ea2e70gr6df794b8rnwc019cc5f799kk3** |
| **Authorization Method**:<br />PaymentSessionAuthToken<br />     | **For Payment Session authentication**<br />In the Api-Token header:<br />* Supply the token used to authenticate the call to generate a payment session<br />Th&#x65;**&#x20;Payment-Session header** value must also be supplied.                                                                                                                                                                                                                                                                                                                          |
| **Authorization Method**:<br />PaymentSessionAuthReference<br /> | **For Payment Session authentication**<br />In the Payment-Session header:<br />* Supply the reference returned in the create payment session response<br />Th&#x65;**&#x20;Api-Token header** value must also be supplied.                                                                                                                                                                                                                                                                                                                                  |

***

**Body Parameters**:

**Configuration Property Descriptions**

| **Parameter**                                                                             | **Description**                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `judoId`<br />String<br /><font color="#42cbd4">Optional</font><br /><br />               | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                         |
| `cardNumber`<br />String<br /><font color="#ef5b2e">Required</font>                       | The unique number printed on the card (13 to 19 digits depending on card type).<br />Submitted without whitespace or non-numeric characters.                                                                                                                                                                        |
| `expiryDate`<br />String<br /><font color="#ef5b2e">Required</font>                       | The expiry date of the card.<br />Format:<br />* MM/YY                                                                                                                                                                                                                                                              |
| `cv2`<br />String<br /><font color="#42cbd4">Optional</font>                              | The 3 or 4 digit number on the back of the card.<br />Also known as the card verification value (CVV) or security code.                                                                                                                                                                                             |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font>            | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                              |
| `yourPaymentReference`<br />String<br /><font color="#42cbd4">Optional</font><br /><br /> | Your unique reference for this payment. <br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed. |
| `cardHolderName`<br />String<br /><font color="#42cbd4">Optional</font>                   | The full name of the card holder.                                                                                                                                                                                                                                                                                   |

:::CodeblockTabs
Register Card Request Example

```json
{
    "yourConsumerReference": "testcustomer@example.com",
    "yourPaymentReference": "5312b7b1-e89c-4155-971a-6e6fa3fb1e26",
    "judoId": "100873697",
    "cardNumber": "4976000000003436",
    "expiryDate": "12/24",
    "cv2": "452",
    "cardHolderName": "Lonnie Rath V"
}
```

Response Example

```json
{
    "receiptId": "955140933322228704",
    "yourPaymentReference": "5312b7b1-e89c-4155-971a-6e6fa3fb1e26",
    "type": "Register",
    "createdAt": "2023-03-20T16:29:07.8907+00:00",
    "result": "Success",
    "message": "AuthCode: 852549",
    "judoId": 100042597,
    "merchantName": "Shodan - Ai Routing",
    "appearsOnStatementAs": "APL*/ShodanAiRouting    ",
    "originalAmount": "1.01",
    "netAmount": "1.01",
    "amount": "1.01",
    "currency": "GBP",
    "acquirerTransactionId": "02448183756786407808",
    "externalBankResponseCode": "",
    "authCode": "852549",
    "cardDetails": {
        "cardLastfour": "3436",
        "endDate": "1224",
        "cardToken": "SOF-VjSSceeee4aDidgQFQpijg",
        "cardType": 11,
        "cardScheme": "Visa",
        "cardFunding": "Debit",
        "cardCategory": "Classic",
        "cardQualifier": 0,
        "cardCountry": "FR",
        "bank": "Credit Industriel Et Commercial",
        "cardHolderName": "Lonnie Rath V"
    },
    "consumer": {
        "consumerToken": "qLYdGBOmQgMsWqGd",
        "yourConsumerReference": "testcustomer@example.com"
    },
    "threeDSecure": {
        "attempted": false
    },
    "risks": {
        "postCodeCheck": "UNKNOWN",
        "cv2Check": "PASSED",
        "merchantSuggestion": "Allow"
    }
}
```
:::

***

### RegisterCard Scenarios (Negative Flow)

Declines can occur for various reasons, it can be impossible to simulate all the negative flows in a sandbox environment.

**Important to Consider**

- How your app handles negative flows
- Your customer's experience should a negative flow occur:
  - Logic to communicate error messages
  - Customise how your app responds
- How to maintain application consistency

Follow our suggested guidelines to simulate negative scenarios, to test your app’s error handling:

| **Suggested Negative Test Scenario**                                                                                                                   | **Expected Error Code** | **Error Description**<br />                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attempt to perform a registerCard request using an invalid card expiry date.                                                                           | 161                     | Sorry, but the card expiry date must be in the future.                                                                                                         |
| Attempt to perform a registerCard request using an invalid card number.                                                                                | 196                     | Unable to process transaction as the card number is invalid. Please try again with a different card.                                                           |
| Attempt to perform a registerCard request with an invalid CV2.                                                                                         | 74                      | The CV2 entered is invalid.                                                                                                                                    |
| Attempt to perform a registerCard request with a missing CV2.<br />The sandbox token has cv2 enabled, the registerCard request has an empty cv2 field. |                         | Sorry, you've not supplied the 3-digit card security code. Please check your details and try again.<br />This is a [model error](docId:_zrsihomUEW-XnRQ4PBtJ). |
| **Simulate a decline using the following test card details:**                                                                                          |                         |                                                                                                                                                                |
| Attempt to perform a registerCard decline using the following:<br />* **cardNumber**: 4221690000004963
* **cv2**: 452
* **expiryDate**: 12/24          | Declined<br />          | Card declined.                                                                                                                                                 |

:::hint{type="warning"}
Where the codes remain fixed, the descriptions may change.&#x20;
You **should not&#x20;**&#x62;uild any error handling logic based on these descriptions.
:::

***

# Integrating iDEAL

:::hint{type="warning"}
The iDEAL alternative payment method for a Web SDK and Mobile SDK integration, has been decommissioned.
:::

## Integrating iDEAL for React Native

To add iDEAL support to your Payments Widget:

1. Set the currency code to EUR (Euro)
2. Set the judoId
3. Include iDEAL as a payment method

An example of a valid iDEAL configuration:

:::BlockQuote
const configuration: JudoConfiguration = \{&#x20;
...
&#x20;judoId: 'myJudoId',
&#x20;paymentMethods: JudoPaymentMethod.iDEAL
&#x20;...
}

const response = await judo.invokePaymentMethodScreen(
&#x20;mode,
&#x20;configuration,
)
:::

Once the currency and judoId are set, iDEAL will be available as a payment method in the Payments Widget.

***

## Integrating iDEAL for Android

To add iDEAL support to your Payments Widget, set:

1. The currency code to EUR (Euro)
2. The JudoId

The `judoId`parameter can be set by calling `setJudoId`on the Judo builder.
An example of a valid iDEAL configuration:

:::BlockQuote
&#x20;val judo = Judo.Builder(PaymentWidgetType.PAYMENT\_METHODS)&#x20;
...&#x20;
.setJudoId("my-judo-id")&#x20;
.setCurrency("EUR")&#x20;
.build()
:::

Once the currency and judoId are set, iDEAL will be available as a payment method in the Payments Widget.

***

## Integrating iDEAL for iOS

To add iDEAL support to your Payments Widget, set:

1. Currency code to EUR (Euro)
2. The `judoId` parameter in the **JPConfiguration** instance:

An example of a valid iDEAL configuration:
`configuration.judoId = @"my-judo-id";`

Once the currency and judoId are set, iDEAL will be available as a payment method in the Payments Widget.

***

## Integrating iDEAL via Web SDK

Ideal is an online payment method that enables consumers to pay through their own bank.

### Prerequisites

Make sure you have implemented the following prerequisites from the **Web SDK integration** guide:

- [Create a paymentSession](docId:40dWE6LBub7vdKza1QYDC)
- [Add the Payment Form to your Website](docId:40dWE6LBub7vdKza1QYDC)

***

### Step One: Add the iDEAL payment tab

The fields referred to in this step are part of the iFrame configuration object supplied in Step Two in the Prerequisites:&#x20;
**createCardDetails()**&#x20;

Call:
`judo.createCardDetails('payment-iFrame', iFrameConfiguration)`

**To add the iDEAL payment tab**:

- Ensure the array set for the **enabledPaymentMethods** field includes ‘IDEAL’.
- For example:
  `enabledPaymentMethods: ['CARD', 'IDEAL']`

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/vBednkO2IWFc9lPf7dsAe_image-20231019-123445.png" size="80" width="825" height="166" position="flex-start" alt="ideal payment tab" darkWidth="825" darkHeight="166" showCaption="false"}

***

### Transaction Timeout

You can alter the timeout for iDEAL transactions by setting the fiel&#x64;**&#x20;idealPollingTimeout**.
Set it as the number of **ms&#x20;**&#x79;ou want the timeout to be.

For example:
`idealPollingTimeout: 40000` would set the transaction timeout to 40000ms (40 seconds).

:::hint{type="info"}
If the field is not provided, the default value is **60000ms**
:::

***

### Step Two: Making an iDEAL Transaction

1. Define th&#x65;**&#x20;idealConfiguration** object for the payment


Ensure the details used when creating the **paymentSession&#x20;**&#x6D;atch the values set in the following configuration:

:::CodeblockTabs
iDEAL Configuration Example

```javascript
const idealConfiguration = {
    judoId: "yourJudoId",
    merchantPaymentReference: "yourPaymentReference",
    merchantConsumerReference: "yourConsumerReference",
    currency: "EUR",
    amount: 10,
    country: "NL",
    accountHolderName: "Account Holder Name",
    paymentMethod: "IDEAL"
}

```
:::

:::hint{type="info"}
To successfully process an iDEAL transaction, the currency must be ‘**EUR**’ (Euros).
:::

:::ExpandableHeading
### iDEAL Configuration Parameter Descriptions

| **Parameter**                                                                  | **Description**                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font>                | Unique ID supplied by Judopay.<br />Specific to a merchant and/or location.<br />Format:<br />* 100100100
* Maximum length 9 characters.
* Do not include spaces or dashes.                                                                                                                                        |
| `amount`<br />Decimal<br /><font color="#ef5b2e">Required</font><br /><br />   | The amount to process.<br />Format:<br />* Two decimal places<br />For currencies using a different structure please contact Judopay for support.                                                                                                                                                                  |
| `currency`<br />String<br /><font color="#ef5b2e">Required</font>              | The currency of the transaction. <br />The ISO 4217 alphabetic currency code:<br />For iDEAL payments this must be **EUR**.                                                                                                                                                                                        |
| `yourConsumerReference`<br />String<br /><font color="#ef5b2e">Required</font> | Unique reference to anonymously identify your customer.<br />Advisable to use GUIDs.<br />Must be below 40 characters.                                                                                                                                                                                             |
| `yourPaymentReference`<br />String<br /><font color="#ef5b2e">Required</font>  | Your unique reference for this payment.<br />Format:<br />* Maximum length 50 characters.<br />This value should be unique in order to protect your customers against duplicate transactions. <br />With a server side integration, if a payment reference is not supplied, the transaction will not be processed. |
| `paymentMethod`<br />String<br /><font color="#ef5b2e">Required</font>         | The payment method being used.<br />* Ensure this is set to **IDEAL**.                                                                                                                                                                                                                                             |
| `accountHolderName`<br />String<br /><font color="#ef5b2e">Required</font>     | The name of the account holder related to this transaction.                                                                                                                                                                                                                                                        |
| `country`<br />String<br /><font color="#ef5b2e">Required</font>               | The 2-letter ISO country code from which the consumer will be paying.<br />* This must be set to **NL** for iDEAL payments.                                                                                                                                                                                        |


:::

2\. Call `getPaymentMethod()` in your function that handles the payment button click for card payments.
(If this is not already set up, add a function to handle this).


`getPaymentMethod()` returns information on which tab is open in the iFrame.&#x20;
Call the appropriate Web SDK **method&#x20;**&#x74;o trigger the correct transaction.


For example:

- If the **card form** tab is open, getPaymentMethod will return “CARD”.
  - For a payment, call:
    `invokePayment()`
  - For a preAuth, call:
    `invokePreauth()`
- If the **iDEAL&#x20;**&#x74;ab is open, getPaymentMethod will return “IDEAL”.
  - Call:
    `invokePaymentWithIDEAL()`

:::CodeblockTabs
Get Payment Method Example

```javascript
 function handlePaymentButtonClick() {
    const paymentMethod = judo.getPaymentMethod()
    
    if(paymentMethod === 'CARD') {
          judo.invokePayment(paymentSession, paymentConfiguration)
          .then(handleSuccess)
          .catch(handleError)
    }
    else if(paymentMethod === 'IDEAL') {
          judo.invokePaymentWithIDEAL(paymentSession, idealConfiguration)
          .then(handleSuccess)
          .catch(handleError)
    }
}
```
:::

If you do not already have an event handler on your payment button to invoke the **handlePaymentButtonClick()**:

- Add the **onclick&#x20;**&#x61;ttribute to your payment button:
  `<button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>`

:::hint{type="info"}
Make sure you have set :**id ="submit-payment-button"**.
This is required to perfor&#x6D;**&#x20;form validation**, where the Pay button will be greyed out until **all&#x20;**&#x74;he information has been entered.
:::

***

### Step Three: Handle the Response

All the Judopay Web SDK transaction methods return a promise.
Once the authorisation is complete, the promise will be either fulfilled or rejected.

**Fulfilled**

- You will receive a JSON object response (a Judopay receipt object).
  - For more information and schema on the JSON object, see [API Transaction Response](docId\:bcXNM5keOk-nlNrZTafUT).
- Depending on the result the consumer should be redirected to the appropriate outcome page.
  - For example, if the result = SUCCESS redirect the consumer to the Success Page.
- This page should display the necessary transaction information (found in the Judopay receipt object).

**Rejected**

- You will receive an error object
  - For more information on error responses returned, see [Web SDK Error Responses](docId\:qfxaWPAQl_-2EVfP8y94d).
- The consumer should be redirected to an Error Page.

:::CodeblockTabs
Response Example

```json
const onFulfillment = (receiptObject) => {
  const { result } = receiptObject
  //redirect to appropriate page depending on the result (success/failure/declined page)
}

const onRejection = (error) => {
  //redirect to error page and handle error
}
```
:::

For more information on the response codes, see [Codes](docId:_zrsihomUEW-XnRQ4PBtJ).

***

# Integrating Klarna

:::hint{type="warning"}
The Klarna alternative payment method for a Web SDK integration, has been decommissioned.
:::

## Integrating Klarna via Web SDK

Klarna is a payment method that allows consumers to pay for items in instalments, or at a later date.
This does not impact the merchant as they will receive all of the funds upfront as Klarna pays the merchant in full, taking on the debt themselves.

### Prerequisites

:::hint{type="info"}
Make sure you are using Web SDK Version **0.0.18** (or higher).
:::

Make sure you have implemented the following prerequisites from the **Web SDK integration** guide:

- [Create a paymentSession](docId:40dWE6LBub7vdKza1QYDC)
- [Add the Payment Form to your Website](docId:40dWE6LBub7vdKza1QYDC)

:::hint{type="info"}
The payment form iFrame must be loaded onto the page in order for payments to work.&#x20;
However displaying the form to the consumer is not required for this transaction type.
:::

To hide the payment form iFrame, use:&#x20;
`<div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>`

:::hint{type="info"}
To automatically receive non-breaking changes, you can pin to the minor version **(0.0)** rather than the current patch version (**0.1.0**).
:::

***

### Step One: Display the Klarna Button

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/JTg8ui75_zU_pAYDUNdFx_klarna-button.png" size="36" width="283" height="38" position="flex-start" alt="klarna payment button" darkWidth="283" darkHeight="38" showCaption="false"}

Add the Klarna button to your web page:

:::CodeblockTabs
Add Klarna Button

```javascript
<body>

  <div id="klarna-button-container" ></div>
  
<script>
  
  const klarnaButton = judo.getKlarnaButton({
    	backgroundColor: '#ffb3c7',
    	borderRadius: 4,
    	color: '#171717',
    	height: 36,
    	width: 280,
    	label: 'Pay now'
  })
  
  const container = document.getElementById("klarna-button-container")
  container.append(klarnaButton)
      
</script>
</body>
```
:::

### Klarna Button Style

| **Parameter**     | **Value**                        |
| ----------------- | -------------------------------- |
| `backgroundColor` | - #171717
- #ffffff
- #ffb3c7    |
| `color`           | * #ffffff
* #171717              |
| `label`           | - Pay now
- Pay later
- Slice it |
| `width`           | number                           |
| `height`          | number                           |
| `borderRadius`    | number                           |

***

### Step Two: Handle the Klarna Button

Make sure the following parameters are the **same values** as those entered in [Create a paymentSession](docId:40dWE6LBub7vdKza1QYDC), otherwise the transaction will fail:

- merchantPaymentReference
- merchantConsumerReference
- JudoID
- Currency
- Amount

*This is used to cross reference the validity of the transaction.*

Your backend server should store the **paymentSession response reference** returned by Judopay's API.&#x20;
Use this reference from the response to populate **yourPaymentSession**.

:::hint{type="warning"}
Make sure you replace the **klarnaConfiguration** object values with your own.
:::

:::CodeblockTabs
Handle the Klarna Button

```javascript
<script>

klarnaButton.onclick = handleKlarnaButtonClick

function handleKlarnaButtonClick() {

    const klarnaConfiguration = {
        judoId: "yourJudoId",
        currency: "GBP",
        amount: 10,
        country: "GB",
        accountHolderName: "Account Holder Name",
        merchantPaymentReference: "yourPaymentReference",
        merchantConsumerReference: "yourConsumerReference",
        taxAmount: 0.01,
        mobileNumber: "00441895808221",
        emailAddress: "john@doe.com",
        apmData: {
            firstName: "John",
            lastName: "Doe",
            mobileNumber: "00441895808221",
            billingAddress: {
                address1: "13 New Burlington St",
                address2: "Apt 214",
                town: "London",
                country: "GB",
                postcode: "W13 3BG"
            }
        },
        paymentMethod: "Klarna"
    }

    judo.invokePaymentWithKlarna('yourPaymentSession', klarnaConfiguration)
        .then(handleSuccess)
        .catch(handleError)
}

</script>
```
:::

For the specific input parameters of the **products&#x20;**&#x76;ariable, refer to the [Klarna Documentation](https://docs.klarna.com/api/api-urls/#payments-api__create-a-new-credit-session__order_lines).&#x20;

***

### Step Three: Handle the Response

All the Judopay Web SDK transaction methods return a promise.
Once the authorisation is complete, the promise will be either fulfilled or rejected.

**Fulfilled**

- You will receive a JSON object response (a Judopay receipt object).
  - For more information and schema on the JSON object, see [API Transaction Response](docId\:bcXNM5keOk-nlNrZTafUT).
- Depending on the result the consumer should be redirected to the appropriate outcome page.
  - For example, if the result = SUCCESS redirect the consumer to the Success Page.
- This page should display the necessary transaction information (found in the Judopay receipt object).

**Rejected**

- You will receive an error object
  - For more information on error responses returned, see [Web SDK Error Responses](docId\:qfxaWPAQl_-2EVfP8y94d).
- The consumer should be redirected to an Error Page.

:::CodeblockTabs
Response Example

```json
const onFulfillment = (receiptObject) => {
  const { result } = receiptObject
  //redirect to appropriate page depending on the result (success/failure/declined page)
}

const onRejection = (error) => {
  //redirect to error page and handle error
}
```
:::

For more information on the response codes, see [Codes](docId:_zrsihomUEW-XnRQ4PBtJ).

***

# Integrating PayByBankApp for React Native

:::hint{type="warning"}
PayByBankApp payment method for React Native is no longer supported and will no longer be updated.
:::

## Integrating PayByBankApp using the Payments Widget for React Native

### Displaying PayByBankApp as a Payment Method

To display the PayByBankApp as a Payment Method for **ReactNative**:

1. Create a JudoPBBAConfiguration:

:::BlockQuote
export interface JudoPBBAConfiguration \{
&#x20;mobileNumber?: string
&#x20;emailAddress?: string
&#x20;appearsOnStatement?: string
&#x20;deeplinkScheme?: string
&#x20;deeplinkURL?: string
}
:::

| **Parameter**                    | **Description**                                                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mobileNumber`<br />String       | Consumer's mobile number.<br />Sent with the transaction as an additional parameter.                                                                                   |
| `emailAddress`<br />String       | Consumer's email address.<br />Sent with the transaction as an additional parameter.                                                                                   |
| `appearsOnStatement`<br />String | Sent with the transaction as an additional parameter.                                                                                                                  |
| `deeplinkScheme`<br />String     | Used in the deeplinking process to identify your app.                                                                                                                  |
| `deeplinkURL`<br />String        | Specifies the app has opened as result of a redirect from the Bank App.<br />The deeplink URL contains the information needed to start polling the transaction status. |

:::CodeblockTabs
Display PBBA

```typescript
//With the JudoPBBAConfiguration set, pass it to the main JudoConfiguration:

const pbbaConfig: JudoPBBAConfiguration = {
    mobileNumber: "myMobileNumber",
    emailAddress: "myEmailAddress",
    appearsOnStatement: "myStatement",
    deeplinkScheme: 'my://app'
}
const config: JudoConfiguration = {
    ...
    pbbaConfiguration: pbbaConfig
    ...
}

//Call the invokePayByBankApp method
//Handle the response:

try {
    const judo = new JudoPay(token, secret)
    const response = await judo.invokePayByBankApp(config)
    // Handle response
} catch (exception) {
    // Handle exception
}
```
:::

***

### DeepLink Scheme

When the consumer invokes the PaybyBankApp transaction, in order to complete the transaction, the app redirects to the user's bank app. When the interaction is finished, the bank app redirects back to your app via the deeplinkScheme sending a **deeplinkURL**.

:::hint{type="info"}
The deeplink scheme has to be set manually for iOS and Android, via the Info.plist (iOS) and the AndroidManifest.xml (Android).
:::

The **deeplinkURL** can be used to start polling the transaction status. The deeplink events can be captured with the linking package already built in ReactNative.

:::hint{type="info"}
Check the ReactNative sample app for the implementation reference.
:::

Once you have captured the deeplinkURL, pass it to the deeplinkURL parameter of the **JudoPBBAConfiguration**. If this parameter is set once the **invokePayByBankApp** is called, the polling process should automatically start.

***

## Integrating PayByBankApp directly to your App for React Native

Not using the Mobile SDK Payments Widget?

To Integrate directly to your app:

1. Instead of calling invokePayByBankApp:
   - Add the branded PaybyBankApp button
   - Add the method as a button press action
   - Expose the PaybyBankApp button as follows:

:::BlockQuote
import \{ JudoPBBAButton } from 'judokit-react-native'

\<TouchableOpacity onPress=\{this.invokePayByBankApp}>
&#x20;\<JudoPBBAButton style=\{\{ flex: 1 }} />
\</TouchableOpacity>
:::

:::hint{type="warning"}
Although, the **JudoPBBAButton&#x20;**&#x69;s referred to as a button, it does not handle button-related events, such as onPress.&#x20;
The JudoPBBAButton will need to be wrapped in a component that handles touch events, for example the **TouchableOpacity&#x20;**&#x63;omponent.
:::

***

# Xamarin Integration

:::hint{type="warning"}

Xamarin SDK has been deprecated and will no longer be updated.
:::

**Prerequisites**:

-
  You have set up your Judopay account.
  - Sign up for your sandbox account, to receive access to your Judopay dashboard and the sandbox environment.
- Your judoIds and tokens are configured and enabled as appropriate.
  - For more information on  permissions, see Permissions.
- You have the latest version of the Android SDK.&#x20;
  - For more details, see Integrating Android with Judopay.
- You have the latest version of the iOS SDK.&#x20;
  - For more details, see Integrating iOS with Judopay.

:::hint{type="info"}
For Mobile apps, we recommend using **payment session authentication.**
:::


**Integration Requirements**:

-
  Xamarin Studio 6.1 / Visual Studio 2015
- Xamarin Forms 2.3.2.127
- Xcode 8
- Android 7.0 (API 24) SDK and build tools 24.0.3 installed
- The SDK is compatible with Android Jelly Bean (4.1) and above and iOS 8 and above.
   

Integrate Judopay into your project by visiting the Xamarin component store:

- Search for Judopay
- Add the component to your Android and iOS projects

***



**Setting up Xamarin**
Ensure all integration steps are completed.

Add your app’s sandbox token and secret to your Judo instance in your Xamarin Forms page:

:::BlockQuote

var judo = new Judo
\{
JudoId = "\<JUDO\_ID>",
Token = "\<API\_TOKEN>",
Secret = "\<API\_SECRET>",
Environment = JudoEnvironment.Sandbox,
Amount = 1.50m,
Currency = "GBP",
ConsumerReference = "YourUniqueReference"
};
:::



Add additional configuration depending on the project you are integrating, as follows:

:::::Tabs
::::Tab{title="Android"}
:::hint{type="info"}

Due to a bug in Xamarin.Forms the page does not resize correctly when the keyboard is visible.
:::

An additional piece of code must be added to your Android Activity:
Add the code snippet after th&#x65;**&#x20;Xamarin.Forms.Forms.Init** method call inside the **OnCreate&#x20;**&#x6D;ethod of your Activity:

:::BlockQuote

Window\.SetSoftInputMode(SoftInput.AdjustResize);
AndroidBugfix5497.assistActivity(this);
:::

***
::::

::::Tab{title="iOS"}
:::hint{type="info"}
Xamarin.Forms has issues resolving dependencies using DependencyService unless they have been registered.
:::

Add the following in your AppDelegate.cs after the LoadApplication(new App()) method call in your FinishedLaunching method:

:::BlockQuote

DependencyService.Register();
DependencyService.Register();
// Required if using Apple Pay
DependencyService.Register();
:::
::::
:::::


**Going Live with Xamarin**


You will need to have tested your app in the sandbox environment before going live.
**Point to the Live Environment**
Within your app’s Xamarin Forms page change the line specifying the targeted environment from SANDBOX to LIVE:&#x20;

Environment =` JudoEnvironment.Live,`

Replace your sandbox API Token and Secret for the live API Token and Secret 

:::BlockQuote
ApiToken = "\<API\_TOKEN>",
ApiSecret = "\<API\_SECRET>",
:::


Find these in **JudopayPortal** > **Your apps** > \{**app name**} > **Live Tokens**
Use the live environment for testing before deploying your app.

***

#  PayByBankApp

:::hint{type="warning"}
PayByBankApp payment method is no longer supported and will no longer be updated.
:::

PayByBankApp is a new, easy and secure alternative payment method, that enables your consumers to pay online quickly and securely via their trusted mobile Bank app.

PayByBankApp facilitates the enablement of consumers using bank transfers to easily pay for goods and services online.

Without the need to enter card details or additional passwords every time a purchase is made, it is designed to simplify the checkout experience, giving consumers more control and visibility of their finances when making a purchase.

***

### Consumer Journey on a Merchant's Mobile App

The consumer's journey on a mobile app, when selecting the PayByBankApp button:

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/wSzApioRMMX-5bwc1wZml_pbba-1.png" size="34" width="320" height="800" position="flex-start" alt="pbba customer journey" darkWidth="320" darkHeight="800" showCaption="false"}

***

### Features of PayByBankApp

Features of PayByBankApp:

- Strong authentication.
- PSD2 Compliant - Meeting the Strong Customer Authentication (SCA) Requirements.
- Increased Consumer Trust - Existing bank brands are known to the consumer.
- Works through the consumer’s existing Bank app.
- Merchant Liability Shifted to the Issuer:
  - All transactions are authenticated via the consumers Bank app, so all liability is shifted away from the merchant to the issuing bank.
  - Everything is tokenised:
  - The merchant, Judopay and the distributor does not have any bank details of the consumer.

***

### Benefits of PayByBankApp to your Consumers

Your consumers:

- Can check their balances in real time.
- Choose which account to pay from.
- No need to enter card details, or any additional passwords.
- Can see money move from their account in seconds.
- Stay secure with payment authorisation taking place in their Bank app.
- Consumers will be auto-enrolled when their online Bank app is installed.

If a consumer uses PayByBankApp with more than one Bank app on their phone, they will get the choice of which Bank app to open at the point of purchase, with the choice of setting their default option.

Once the consumer clicks the PayByBankApp button, they will be taken to their Bank app to complete the payment.

***

## Integrating PayByBankApp - Android

:::hint{type="warning"}
PayByBankApp payment method is no longer supported and will no longer be updated.
:::

To add the PayByBankApp button:

:::CodeblockTabs
Add PBBA Button

```java
//Insert the button in the layout file:

<com.judopay.judokit.android.ui.common.PayByBankButton        
android:id="@+id/payByBankButton"       
android:layout_width="wrap_content"        
android:layout_height="wrap_content" />

//Set OnClickListener to the PayByBankApp button
//The JudoActivity will start and pass the result to merchant:

payByBankButton.setOnClickListener {           
    val intent = Intent(this, JudoActivity::class.java)            
    intent.putExtra(JUDO_OPTIONS, judo)            
    startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)      
 }

//Enable the PayByBankApp in the Payment Selector Screen:
//Build the Judo configuration object:
//Set the payment widget type to:

PaymentWidgetType.PAYMENT_METHODS

//Set the currency:

GBP

val amount = Amount.Builder()
            .setAmount("1")
            .setCurrency(Currency.GBP)
            .build()
            
Judo.Builder(PaymentWidgetType.PAYMENT_METHODS)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()
//Start JudoActivity with the JudoConfiguration object:

val intent = Intent(this, JudoActivity::class.java)           
    intent.putExtra(JUDO_OPTIONS, judo)           
    startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
```
:::

:::hint{type="info"}
For the PayByBankApp button to appear in the Payments Widget, a banking app must already be installed.
:::

The PayByBankApp Button is displayed:

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/vfccr0FpqLgNsjvsUCwd__pbba-button.png" size="28" width="1080" height="2220" position="flex-start" alt="pbba button" darkWidth="1080" darkHeight="2220" showCaption="false"}

***

**To display the PayByBankApp as a Payment Method for Android:**

:::CodeblockTabs
Display PBBA as a Payment Method

```java
//Add the intent-filter to the AndroidManifest.xml file.
//This registers the deep link URL:

<activity
  android:name=".MainActivity"
  android:launchMode="singleTask">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />

    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />

        <data
           android:scheme="your"
           android:host="scheme" />
  </intent-filter>
</activity>

//Create the Judo  object:
//Set PaymentWidgetType to:
//PAY_BY_BANK_APP, or
//PAYMENT_METHODS

//If using the payments widget.
//Set currency:GBP
//Create the PBBAConfiguration object:Set deepLinkScheme to the defined scheme in the AndroidManifest.xml file:

 val pbbaConfiguration = PBBAConfiguration.Builder()
        .setDeepLinkScheme("your://scheme")
        .build()
Judo.Builder(PaymentWidgetType.PAY_BY_BANK_APP)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//Override the onNewIntent method to catch the deeplink URL
//Add the deepLinkURL to the PBBAConfiguration object
//Start JudoActivity with the desired payment widget type
//Add the same logic in onCreate

 override fun onNewIntent(intent: Intent?) {
        checkForDeepLink(intent)
        super.onNewIntent(intent)
    }
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        checkForDeepLink()
        ...
    }
    
    private fun checkForDeepLink(intent: Intent? = this.intent) {
        val uri = intent?.data
        val newIntent = Intent(this, JudoActivity::class.java)
        if (uri.contains("your://scheme")) {  
            val newPbbaConfig = pbbaConfiguration.newBuilder()
                .setDeepLinkURL(uri)
                .build()
            val judo = getJudo(PaymentWidgetType.PAY_BY_BANK_APP).newBuilder()
                .setPBBAConfiguration(newPbbaConfig)
                .build()
            newIntent.putExtra(JUDO_OPTIONS, judo)
            startActivityForResult(newIntent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
        }
    }
    
    private fun getJudo(widgetType: PaymentWidgetType): Judo {
        return Judo.Builder(widgetType)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//To catch the first response, create a broadcastReceiver:

private val broadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
    val result = intent?.getParcelableExtra<JudoResult>(PBBA_RESULT)
        // Handle result
    }
}

//Register the defined receiver in onCreate:

LocalBroadcastManager.getInstance(this).registerReceiver(
    orderIdReceiver,
    IntentFilter(BR_PBBA_RESULT)
)

//Catch the result in the onActivityResult method:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
   super.onActivityResult(requestCode, resultCode, data)

     if (requestCode == JUDO_PAYMENT_WIDGET_REQUEST_CODE) {
       when (resultCode) {
         PAYMENT_SUCCESS -> {
         val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
             //Process successful payment
              }
         PAYMENT_CANCELLED -> {
         val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
            //Process cancelled payment
              } 
         PAYMENT_ERROR -> {
         val error = data?.getParcelableExtra<JudoError>(JUDO_ERROR)
            //Process unsuccessful payment
              }    
          }
      }
}
```
:::

***

### Integrating PayByBankApp Directly to your App for Android

Not using the Mobile SDK Payments Widget?

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/kTJLswTc1DGm2kVucp4gr_pbba-button2.png" size="26" width="1080" height="2220" position="flex-start" alt="pbba button" darkWidth="1080" darkHeight="2220" showCaption="false"}

To Integrate directly to your app:

:::CodeblockTabs
Integrate PBBA Directly

```java
//Insert the button in the layout file:

<com.judokit.android.ui.common.PayByBankButton
  android:id="@+id/payByBankButton"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content" 
  />

//Add intent-filter to the AndroidManifest.xml file.
//This will register the deep link URL:

activity
 android:name=".MainActivity"
 android:launchMode="singleTask">
 <intent-filter>
 <action android:name="android.intent.action.VIEW" />

 <category android:name="android.intent.category.DEFAULT" />
 <category android:name="android.intent.category.BROWSABLE" />

 <data
   android:scheme="your"
   android:host="scheme" />
 </intent-filter>
 </activity>

//Create the Judo object:
//Set the PaymentWidgetType to PAY_BY_BANK_APP
//Create the PBBAConfiguration object
//Set deepLinkScheme to the defined scheme in the AndroidManifest.xml file:

 val pbbaConfiguration = PBBAConfiguration.Builder()
        .setDeepLinkScheme("your://scheme")
        .build()
Judo.Builder(PaymentWidgetType.PAY_BY_BANK_APP)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//Override the onNewIntent method to catch the deeplink URL:
//Add the deepLinkURL to the PBBAConfiguration object
//Start JudoActivity with the desired payment widget type
//Add the same logic in onCreate

 override fun onNewIntent(intent: Intent?) {
        checkForDeepLink(intent)
        super.onNewIntent(intent)
    }
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        checkForDeepLink()
        ...
    }
    
    private fun checkForDeepLink(intent: Intent? = this.intent) {
        val uri = intent?.data
        val newIntent = Intent(this, JudoActivity::class.java)
        if (uri.contains("your://scheme")) {  
            val newPbbaConfig = pbbaConfiguration.newBuilder()
                .setDeepLinkURL(uri)
                .build()
            val judo = getJudo(PaymentWidgetType.PAY_BY_BANK_APP).newBuilder()
                .setPBBAConfiguration(newPbbaConfig)
                .build()
            newIntent.putExtra(JUDO_OPTIONS, judo)
            startActivityForResult(newIntent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
        }
    }
    
    private fun getJudo(widgetType: PaymentWidgetType): Judo {
        return Judo.Builder(widgetType)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//To catch the first response, create a broadcastReceiver:

private val broadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
    val result = intent?.getParcelableExtra<JudoResult>(PBBA_RESULT)
        // Handle result
    }
}

//Register the defined receiver in onCreate:

LocalBroadcastManager.getInstance(this).registerReceiver(
    orderIdReceiver,
    IntentFilter(BR_PBBA_RESULT)
)

//Set OnClickListener to the previously defined PayByBankApp button
//JudoActivity will start and pass the result to merchant:

payByBankButton.setOnClickListener {
  val intent = Intent(this, JudoActivity::class.java)
  intent.putExtra(JUDO_OPTIONS, judo)
  startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
 }

//Catch the result in the onActivityResult method:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == JUDO_PAYMENT_WIDGET_REQUEST_CODE) {
       when (resultCode) {
       PAYMENT_SUCCESS -> {
       val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
           //Process successful payment
             }
       PAYMENT_CANCELLED -> {
       val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
           //Process cancelled payment
             } 
       PAYMENT_ERROR -> {
       val error = data?.getParcelableExtra<JudoError>(JUDO_ERROR)
           //Process unsuccessful payment
                }    
            }
        }
    }
<com.judokit.android.ui.common.PayByBankButton
  android:id="@+id/payByBankButton"
  android:layout_width="wrap_content"
  android:layout_height="wrap_content" 
  />

//Add intent-filter to the AndroidManifest.xml file.
//This will register the deep link URL:

activity
 android:name=".MainActivity"
 android:launchMode="singleTask">
 <intent-filter>
 <action android:name="android.intent.action.VIEW" />

 <category android:name="android.intent.category.DEFAULT" />
 <category android:name="android.intent.category.BROWSABLE" />

 <data
   android:scheme="your"
   android:host="scheme" />
 </intent-filter>
 </activity>

//Create the Judo object:
//Set the PaymentWidgetType to PAY_BY_BANK_APP
//Create the PBBAConfiguration object
//Set deepLinkScheme to the defined scheme in the AndroidManifest.xml file:

 val pbbaConfiguration = PBBAConfiguration.Builder()
        .setDeepLinkScheme("your://scheme")
        .build()
Judo.Builder(PaymentWidgetType.PAY_BY_BANK_APP)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//Override the onNewIntent method to catch the deeplink URL:
//Add the deepLinkURL to the PBBAConfiguration object
//Start JudoActivity with the desired payment widget type
//Add the same logic in onCreate

 override fun onNewIntent(intent: Intent?) {
        checkForDeepLink(intent)
        super.onNewIntent(intent)
    }
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        checkForDeepLink()
        ...
    }
    
    private fun checkForDeepLink(intent: Intent? = this.intent) {
        val uri = intent?.data
        val newIntent = Intent(this, JudoActivity::class.java)
        if (uri.contains("your://scheme")) {  
            val newPbbaConfig = pbbaConfiguration.newBuilder()
                .setDeepLinkURL(uri)
                .build()
            val judo = getJudo(PaymentWidgetType.PAY_BY_BANK_APP).newBuilder()
                .setPBBAConfiguration(newPbbaConfig)
                .build()
            newIntent.putExtra(JUDO_OPTIONS, judo)
            startActivityForResult(newIntent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
        }
    }
    
    private fun getJudo(widgetType: PaymentWidgetType): Judo {
        return Judo.Builder(widgetType)
            .setJudoId(judoId)
            .setApiToken(token)
            .setApiSecret(secret)
            .setAmount(amount)
            .setReference(reference)
            .setIsSandboxed(isSandboxed)
            .setSupportedCardNetworks(networks)
            .setPaymentMethods(paymentMethods)
            .setUiConfiguration(uiConfiguration)
            .setGooglePayConfiguration(googlePayConfiguration)
            .setPBBAConfiguration(pbbaConfiguration)
            .build()

//To catch the first response, create a broadcastReceiver:

private val broadcastReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
    val result = intent?.getParcelableExtra<JudoResult>(PBBA_RESULT)
        // Handle result
    }
}

//Register the defined receiver in onCreate:

LocalBroadcastManager.getInstance(this).registerReceiver(
    orderIdReceiver,
    IntentFilter(BR_PBBA_RESULT)
)

//Set OnClickListener to the previously defined PayByBankApp button
//JudoActivity will start and pass the result to merchant:

payByBankButton.setOnClickListener {
  val intent = Intent(this, JudoActivity::class.java)
  intent.putExtra(JUDO_OPTIONS, judo)
  startActivityForResult(intent, JUDO_PAYMENT_WIDGET_REQUEST_CODE)
 }

//Catch the result in the onActivityResult method:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == JUDO_PAYMENT_WIDGET_REQUEST_CODE) {
       when (resultCode) {
       PAYMENT_SUCCESS -> {
       val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
           //Process successful payment
             }
       PAYMENT_CANCELLED -> {
       val result = data?.getParcelableExtra<JudoResult>(JUDO_RESULT)
           //Process cancelled payment
             } 
       PAYMENT_ERROR -> {
       val error = data?.getParcelableExtra<JudoError>(JUDO_ERROR)
           //Process unsuccessful payment
                }    
            }
        }
    }
```
:::

***

## Integrating PayByBankApp - iOS

:::hint{type="warning"}
PayByBankApp payment method is no longer supported and will no longer be updated.
:::

Integrating PayByBankApp using the Payments Widget for iOS

Displaying PayByBankApp as a Payment Method for iOS

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/CVtoh4Dh615XnG1UNpp7j_mobile-sdk-ios.png" size="26" width="389" height="800" position="flex-start" alt="paybank app" darkWidth="389" darkHeight="800" showCaption="false"}

To display the PayByBankApp as a Payment Method for iOS:

:::CodeblockTabs
Display PBBA as a Payment Method

```java
//In the info.plist of app and LSApplicationQueriesSchemes add the URL scheme of the merchant(CFBundleURLSchemes)::

<key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>judo</string>
            </array>
        </dict>
    </array>
    <key>LSApplicationQueriesSchemes</key>
    <array>
        <string>zapp</string>
    </array>
 

//Add deeplink to the pbbaConfiguration object:

  self.pbbaConfig = [JPPBBAConfiguration new];
  self.pbbaConfig.deeplinkScheme = @"judo://pay";

//To enable the PayByBankApp set the following options:
//Add the pbba method to:
//The paymentMethods  array in JPConfiguration
//Set currency: GBP
```
:::

***

## Integrating PayByBankApp Directly to your App for iOS

Not using the Mobile SDK Payments Widget?

To Integrate directly to your app:

**Prerequisites**

- "Bank3 Test App" - Contact: **developersupport\@judopayments.com** to get access, so you can test the PayByBankApp flow.
- You have set your app's URL Scheme.
- You have added **zapp** to the **ApplicationQueriesSchemes**:

An example of the **Info.plist** file:

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/HBy55B_JAn8Uc8uL55QjG_mobile-sdk-ios.jpg" size="20" width="368" height="131" position="flex-start" alt="info plist example" darkWidth="368" darkHeight="131" showCaption="false"}

**Step 1: Initialising the SDK**

To integrate with the Judopay SDK directly to your iOS app, you can use either a:

- **basic&#x20;**&#x61;uthorization
- **session&#x20;**&#x61;uthorization

:::hint{type="info"}
You can select the sandbox mode for testing purposes.
Set the value:**isSandboxed = true**
:::

:::BlockQuote
let authorization: JPAuthorization = JPBasicAuthorization(token: JUDO\_TOKEN,
&#x20;andSecret: JUDO\_SECRET)
&#x20;judoKit = JudoKit(authorization: authorization)
&#x20;judoKit.isSandboxed = true
:::

**Step 2: Check for Installed Bank Apps**

To ensure a good customer experience, it is recommended to only display the PayByBankApp button when the consumer has a compatible mobile Banking app.

Before adding the PayByBankApp button in Step 3, check if any compatible PayByBankApp Bank apps are installed, using the JudoKit **isBankingAppAvailable&#x20;**&#x6D;ethod:

:::BlockQuote
if (JudoKit.isBankingAppAvailable()) \{
&#x20;// Add the PBBA button
}
:::

**&#x20;Step 3: Adding the PayByBankApp Button**

We recommend you use the branded button to invoke a PayByBankApp transaction, however it is not mandatory.

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/c_BtrWkCF9DAab4Iebo6V_mobile-sdk-ios-1.jpg" size="30" width="800" height="225" position="flex-start" alt="pbba button" darkWidth="800" darkHeight="225" showCaption="false"}

The PayByBankApp Button uses the **delegate&#x20;**&#x70;roperty.
The delegate property points to any class that implements the **JPPBBAButtonDelegate** interface:

:::BlockQuote
let pbbaButton = JPPBBAButton(frame: container.bounds);
&#x20;pbbaButton.delegate = self
&#x20;view\.addSubview(pbbaButton)
:::

:::hint{type="warning"}
The JPBBAButton is a subclass of **UIView**, not UIButton.
Take this into consideration when integrating the PayByBankApp button via the Interface Builder.
:::

The **JPPBBAButtonDelegate** interface has only one method: **pbbaButtonDidPress(sender:)**, which is responsible for handling the button tap action.

Recommended PayByBankApp Button Size:

- Minimum: Width 160pt | Height 40pt
- Maximum: Width 310pt | Height 48pt

**Step 4: Adding the Delegate Method**

The delegate method is responsible for the button tap action.

To add the delegate method:

1. Call the **invokePBBA&#x20;**&#x6D;ethod in the Judopay SDK and provide the required configuration parameters:

:::CodeblockTabs
Invoke PBBA Method

```java
func pbbaButtonDidPress(_ sender: JPPBBAButton) {

    let amount = JPAmount(AMOUNT_VALUE, currency: "GBP")
    let reference = JPReference(consumerReference: CONSUMER_REF)

    configuration = JPConfiguration(judoID: JUDO_ID, amount: amount, reference: reference)

    let pbbaConfiguration = JPPBBAConfiguration()
    pbbaConfiguration.mobileNumber = YOUR_MOBILE_NUMBER
    pbbaConfiguration.emailAddress = YOUR_EMAIL_ADDRESS
    pbbaConfiguration.appearsOnStatement = YOUR_APPEARS_ON_STATEMENT
    pbbaConfiguration.deeplinkScheme = YOUR_DEEPLINK_SCHEME

    configuration.pbbaConfiguration = pbbaConfiguration

    judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in
        if let response = response {
            // Handle response
        }

        if let error = error {
            // Handle error
        }
    }
}
```
:::

- Each Judopay transaction takes a **JPConfiguration** instance as a parameter.The configuration object sets up all the required parameters for a successful transaction. It also sets any optional parameters which you can configure to personalise the payment flow.
- PayByBankApp transactions require some extra parameters to be set up, in addition to the basic transaction configuration. These optional parameters are defined in the **JPPBBAConfiguration** class, and used to add additional information to the transaction. The following two parameters are recommended:
  - deeplinkScheme
  - deeplinkURL
- Call the **invokePBBA** method from the Judopay SDK.

The PayByBankApp flow will be triggered, opening the Bank app for consumers to make their transactions.

***

### The deeplinkScheme

A deeplinkScheme identifies your app during the redirect process. When a consumer has completed their transaction using their bank app, the bank app will attempt to redirect the consumer back to your app.

:::hint{type="warning"}
The deeplinkScheme name should match the URL scheme defined in the **Info.plist&#x20;**&#x66;ile.
For example: myapp -> myapp\:/
:::

**The deeplinkURL**

The deeplink URL enables the app to open the consumer's mobile Banking app, so they can complete the transaction.

When the Bank app redirects the consumer back to your app, it also provides you with a URL that you can use to poll the transaction status.

Add the deeplinkURL to the main configuration object. This will be sent as a parameter to the transaction method.

:::hint{type="info"}
It is a good idea to handle the errors within this step.
:::

The most important information from the response is the **orderId**, accessed via **response.orderDetails.orderId**.

The orderId is used to manually check the transaction status.

**Step 5: Handling the deeplinkURL**

Following the completed transaction, the bank flow will be triggered when th&#x65;**&#x20;invokePBBA** method is called, even if the deeplinkURL parameter is not provided.

However, if the deeplinkURL parameter is provided, calling **invokePBBA&#x20;**&#x77;ill trigger the transaction status polling logic.

To handle the deeplinkURL:

1. Listen to this event.
2. Capture the redirect URL.

To capture the redirect URL:

- In your **AppDelegate** file, add the following methods:
  - application(\_:open\:options:)
  - application(\_:didFinishLaunchingWithOptions:)

Pass the URL to the JPPBBAConfiguration instance.



For the purpose of this exercise, the deeplinkURL is saved in the app's UserDefaults.

You can save the deeplinkURL in the Keychain or any alternative.

:::CodeblockTabs
Deeplink URL Example

```java
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

     if let url = launchOptions?[.url] as? URL {
         UserDefaults.standard.set(url, forKey: "deeplinkURL")
     }

     ...
}

func application(
    _ app: UIApplication, open url: URL,
    options: [UIApplication.OpenURLOptionsKey : Any] = [:]
    ) -> Bool {

     UserDefaults.standard.set(url, forKey: "deeplinkURL")

     ...
}
```
:::

**&#xD;Step 6: Polling the Transaction Status**

Once the Bank app has redirected the consumer back to your app, you can start polling the transaction status.

To start the PayByBankApp polling status:

- Add the deeplinkURL to the configuration

Call the invokePBBA(configuration:) method:

:::CodeblockTabs
Call Invoke PBBA Method

```java
func handleDeeplink() {
     guard let url = UserDefaults.standard.url(forKey: "deeplinkURL") else {
         return
     }

     configuration.pbbaConfiguration?.deeplinkURL = url

     judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in
         if let response = response {
             // Handle response
         }

         if let error = error {
             // Handle error
         }
     }
 }
```
:::


In the **JPResponse** object, you can inspect the **orderDetails** containing information about the transaction status.

:::hint{type="info"}
Another option is to put a check in your **viewDidAppear(animated:)** method.
If a deeplinkURL is set up, add it to the configuration and call the **invokePBBA(configuration:)** method again.&#x20;
This will start the polling status.&#x20;
:::

**Manually Checking the Transaction Status**

There may be cases where the Bank app closes before the transaction flow completes. This would mean the deeplinkURL is not returned and the polling process to check the transaction status will not begin.

To manually check the transaction status:

1. Invoke a manual order status request:
2. Get the orderId from the initial request:

When the Bank app is invoked during the PayByBankApp request, (Step 4) the **orderId&#x20;**&#x69;s captured from the callback response:

:::CodeblockTabs
Response Example

```java
judoKit.invokePBBA(with: configuration) { [weak self] (response, error) in 
    if let response = response { 
        let orderId = response.orderDetails?.orderId 
            // Persist the orderId for later use 
} 
}
```
:::

Use the orderId to manually check the transaction status:
You would do this in the same way as Initialising the Judopay SDK, see Step 1: Initialising the SDK.

Call the invokeOrderStatus method, with the orderId:

:::BlockQuote
let apiService = JPApiService(authorization: authorization, isSandboxed: true)

&#x20;apiService.invokeOrderStatus(withOrderId: orderId) \{ (response, error) in
&#x20;// Handle response
}
:::

The response will contain both the transaction status, and the order details of the transaction.

For a sample app, see Judopay's Judokit for iOS on [Github](https://github.com/Judopay/JudoKit-iOS/tree/master/Examples).