---
title: PayPal
slug: paypal
docTags: 
createdAt: 2024-06-03T14:17:08.518Z
---

:::hint{type="warning"}
PayPal is currently in **BETA.**
:::

PayPal is a popular eWallet, whereby their users are able to send and receive money using funds directly from their wallet and / or from their credit / debit card. 

- Link your existing PayPal account to Judopay, to enable an easy integration of PayPal alongside other payment methods. 
- Reconcile your PayPal payments within the Judopay Portal.

***

## Integrating PayPal (BETA)

Integrate PayPal using our **Web SDK**.

:::hint{type="warning"}
Contact Developer Support to link your production PayPal account to your Judopay account.
Currently, you are only able to link your **production **PayPal account.
For more details on **testing**, contact Developer Support.
:::

### 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. 
However displaying the form to the consumer is not required for this transaction type.
:::

To hide the payment form iFrame, use: 
`<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 PayPal Button

::Image[]{src="https://api.archbee.com/api/optimize/QGXTyW3MgdNcMjdEa0v8r/k8U2KjBmMatqtykokdn8S_paypal.png" size="38" width="278" height="34" position="flex-start" alt="paypal button" darkWidth="278" darkHeight="34" showCaption="false"}

Currently `/payments` (immediate capture) is supported when implementing PayPal via the Web SDK.

Make sure the following parameters are the **same values** as those entered in [Creating 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 **payPalConfiguration** object values with your own.
:::

:::CodeblockTabs
Display the PayPal Button

```javascript
<body>

  <div id="#paypal-button-container" ></div>
  
<script>
  
  const payPalConfiguration = {
      style: {color: 'blue', height: 34},
      merchantId: 'yourPaypalMerchantId',
      amount: '1.01',
      currency: 'GBP',
      merchantPaymentReference: 'yourPaymentReference',
      judoId: 'yourJudoId',
      dynamicDescriptor: 'dynamicDescriptor',
      paymentSession: 'yourPaymentSession',
      consumer: {
          merchantConsumerReference: 'yourConsumerReference',
          firstName: 'John',
          surname: 'Doe',
          emailAddress: 'example@domain.com'
      },
      billingAddress: {
          address1: 'My House',
          address2: 'My Street',
          city: 'My City',
          country: 'GB',
          postcode: 'TR14 8PA',
      },
      shippingAddress: {
          address1: 'My House',
          address2: 'My Street',
          city: 'My City',
          country: 'GB',
          postcode: 'TR14 8PA',
      },
      onSuccess: handleSuccess,
      onError: handleError
  }
  
  judo.getPayPalButton(payPalConfiguration) 
      .then(button => {
          button.render(document.getElementById("#paypal-button-container"));    
          })
      .catch(error => handleError(error))
      
</script>
</body>
```
:::

When the PayPal button is clicked, the Web SDK will call the method to make the transaction.
For more information on the PayPal button, see PayPal's documentation [Button Render Options](https://developer.paypal.com/docs/business/javascript-sdk/javascript-sdk-reference/#paypalbuttonsrender-container-).

See below for more details on the parameters that create the **payPalConfiguration** object:

:::ExpandableHeading
### &#x20;PayPal Configuration Parameter Descriptions

| **Parameter**                                                                     | **Description**                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `style`<br />String<br /><font color="#42cbd4">Optional</font>                    | Set the style for the PayPal button.<br />For a full list of styling options, see [Styling](https://developer.paypal.com/docs/business/checkout/reference/style-guide/#customize-the-payment-buttons).                                                                                                                                                                                                                |
| `merchantId`<br />String<br /><font color="#42cbd4">Optional</font>               | Your PayPal Merchant ID.<br />To get your PayPal Merchant ID: Navigate to your PayPal Account **Settings -> Business Information -> PayPal Merchant ID.**                                                                                                                                                                                                                                                             |
| `amount`<br />Float<br /><font color="#ef5b2e">Required</font>                    | 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. Any ISO 4217 alphabetic currency code:<br />- GBP<br />- USD<br />- EUR                                                                                                                                                                                                                                                                                                              |
| `merchantPaymentReference`<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. If you set this reference it will be used.<br /><br />Otherwise a reference will be internally generated.                                                                                                               |
| `judoId`<br />String<br /><font color="#ef5b2e">Required</font>                   | Unique ID supplied by Judopay.Specific to a merchant and/or location.<br />Format:<br />- 100100100<br />- Maximum length 9 characters.<br />- Do not include spaces or dashes.                                                                                                                                                                                                                                       |
| `dynamicDescriptor`<br />String<br /><font color="#42cbd4">Optional</font>        | The merchant’s ‘Trading Name’ that will appear on the consumer’s statement.<br />The value is returned in the response within the appearsOnStatement field.<br />Format:<br />- Maximum 25 characters in length.                                                                                                                                                                                                      |
| `paymentSession`<br />String<br /><font color="#ef5b2e">Required</font>           | The additional way to authenticate a 3D Secure 2 payments or preauths transaction.                                                                                                                                                                                                                                                                                                                                    |
| `consumer`<br />Object<br /><font color="#ef5b2e">Required</font>                 | Consumer details:<br />- `merchantConsumerReference`<br />- `firstName`<br />- `surname`<br />- `emailAddress`                                                                                                                                                                                                                                                                                                        |
| `billingAddress`<br />Object<br /><font color="#42cbd4">Optional</font>           | Billing address details:<br />- `address1`<font color="#ef5b2e">**\***</font><br />- `address2`<br />- `city`<font color="#ef5b2e">**\***</font><br />- `country`<font color="#ef5b2e">**\*** </font><br />See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.<br />- `postcode`<font color="#ef5b2e">**\***</font><br /><font color="#ef5b2e">Required **\***</font> |
| `shippingAddress`<br />Object<br /><font color="#42cbd4">Optional</font>          | Shipping address details:<br />- `address1`<font color="#ef5b2e">**\***</font><br />- `address2`<br />- `city`<font color="#ef5b2e">**\***</font><br />- `country`<font color="#ef5b2e">**\***</font><br />See [here](docId\:XZE369mFK5UVOSaNzM8UO) for the list of valid **ISO 3166-1** format country codes.<br />- `postcode`<font color="#ef5b2e">**\***</font><br /><font color="#ef5b2e">Required **\***</font> |
| `onSuccess`<br />Object<br /><font color="#ef5b2e">Required</font>                | Callback invoked when the payment is successful.<br />The response object is provided as a parameter, with the following properties:<br />- `receiptId`<br />- `orderId`<br />- `transactionType`<br />- `createdAt`<br />- `status`                                                                                                                                                                                  |
| `onError`<br />Object<br /><font color="#ef5b2e">Required</font>                  | Callback invoked when the payment fails.<br />The error object is provided as a parameter                                                                                                                                                                                                                                                                                                                             |


:::

***

## Step Two: 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).

***

# PayPal Webhooks

During the PayPal checkout flow, the redirect that takes place means we recommend setting up **webhook notifications** to receive transaction status updates.

***

### Prerequisites

:::hint{type="info"}
If you are already receiving webhook notifications from Judopay, there are no additional steps required to begin receiving webhooks for PayPal.
:::

If you are not currently configured to receive webhooks from Judopay, you can enable webhooks via the Judopay Portal.
For more information, see [Enable Webhooks](docId\:mQjiiZXmCRo1cpvAUaWuD).

***

## Webhook Notification Examples

### Preauth

:::CodeblockTabs
Example

```json
{
  "receiptId": "879332866188656640",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-ZSMRSwUNSGul0cr4qUftiQ",
    "orderStatus": "AUTHORISED",
    "timestamp": "2022-08-23T11:56:17.908Z",
    "currency": "GBP",
    "amount": 25,
    "refundedAmount": 0,
    "capturedAmount": 0
  },
  "merchantPaymentReference": "2d6dae09-33fd-46f3-bc36-989396bec766",
  "merchantConsumerReference": "Brielle"
}
```
:::

### Partial Capture

:::CodeblockTabs
Example

```json
{
  "receiptId": "879333769331359744",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-ZSMRSwUNSGul0cr4qUftiQ",
    "orderStatus": "PARTIALLY_CAPTURED",
    "timestamp": "2022-08-23T11:58:30.016Z",
    "currency": "GBP",
    "amount": 25,
    "refundedAmount": 0,
    "capturedAmount": 20
  },
  "merchantPaymentReference": "4f89ddf1-cf23-4877-88f0-8bfaac56ce64",
  "merchantConsumerReference": "Brielle"
}
```
:::

### Full Capture

:::CodeblockTabs
Example

```json
{
  "receiptId": "879333941989892096",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-ZSMRSwUNSGul0cr4qUftiQ",
    "orderStatus": "FULLY_CAPTURED",
    "timestamp": "2022-08-23T11:59:10.930Z",
    "currency": "GBP",
    "amount": 25,
    "refundedAmount": 0,
    "capturedAmount": 25
  },
  "merchantPaymentReference": "af1934a7-1ef0-4115-bff9-38671503fed9",
  "merchantConsumerReference": "Brielle"
}
```
:::

### Payment 

:::CodeblockTabs
Example

```json
{
  "receiptId": "879322869014740992",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-SJa5CrPER1--87cCH1XXAw",
    "orderStatus": "FULLY_CAPTURED",
    "timestamp": "2022-08-23T11:16:11.388Z",
    "currency": "GBP",
    "amount": 21,
    "refundedAmount": 0,
    "capturedAmount": 21
  },
  "merchantPaymentReference": "385af203-6658-4b5a-961d-d67824b891d2",
  "merchantConsumerReference": "Jarrell",
  "merchantPaymentMetadata": {
    "Field 1": "Merchant Meta Data"
  }
}
```
:::

### Partial Refund

Collected funds outstanding.

:::CodeblockTabs
Example

```json
{
  "receiptId": "879331999045672960",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-SJa5CrPER1--87cCH1XXAw",
    "orderStatus": "PARTIALLY_REFUNDED",
    "timestamp": "2022-08-23T11:51:27.509Z",
    "currency": "GBP",
    "amount": 21,
    "refundedAmount": 10,
    "capturedAmount": 21
  },
  "merchantPaymentReference": "385af203-6658-4b5a-961d-d67824b891d2",
  "merchantConsumerReference": "Jarrell",
  "merchantPaymentMetadata": {
    "Field 1": "Merchant Meta Data"
  }
}
```
:::

### Partial Refund

All collected funds.

:::CodeblockTabs
Example

```json
{
  "receiptId": "879331999045672960",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-SJa5CrPER1--87cCH1XXAw",
    "orderStatus": "REFUNDED",
    "timestamp": "2022-08-23T11:51:27.509Z",
    "currency": "GBP",
    "amount": 21,
    "refundedAmount": 10,
    "capturedAmount": 10
  },
  "merchantPaymentReference": "385af203-6658-4b5a-961d-d67824b891d2",
  "merchantConsumerReference": "Jarrell",
  "merchantPaymentMetadata": {
    "Field 1": "Merchant Meta Data"
  }
}
```
:::

### Full Refund

:::CodeblockTabs
Example

```json
{
  "receiptId": "879332209947860992",
  "paymentMethod": "PAYPAL",
  "siteId": "100817485",
  "orderDetails": {
    "orderId": "APM-SJa5CrPER1--87cCH1XXAw",
    "orderStatus": "CLOSED",
    "timestamp": "2022-08-23T11:52:17.529Z",
    "currency": "GBP",
    "amount": 21,
    "refundedAmount": 21,
    "capturedAmount": 21
  },
  "merchantPaymentReference": "385af203-6658-4b5a-961d-d67824b891d2",
  "merchantConsumerReference": "Jarrell",
  "merchantPaymentMetadata": {
    "Field 1": "Merchant Meta Data"
  }
}
```
:::

## Webhook Parameter Descriptions

| **Parameter**                           | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `receiptId`<br />String                 | Unique ID that references the payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `siteId`<br />String                    | Unique ID supplied by Judopay.<br />Specific to a merchant and / or location.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `transactionType`<br />String           | Type of Transaction.<br />Values:<br />- Payment<br />- PreAuth<br />- Collection<br />- Refund                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `paymentMethod`<br />String             | Payment method used. <br />Values:<br />- PAYPAL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `orderDetails`<br />Object              | Details of the order.<br />Properties:<br />- `orderDetails.orderId`<br />Unique ID for the order.<br />- `orderDetails.orderStatus`<br />- AUTHORISED<br />Your authorisation request has been successfully processed.<br />You may now capture or void the authorised funds.<br />Subsequent Operations:<br />- Capture<br />- Void<br />- PARTIALLY\_CAPTURED<br />Your order has been partially captured, there are captured funds now available to refund.<br />Further authorised funds remain available to capture or void.<br />Subsequent Operations:<br />- Capture<br />- Void<br />- Refund<br />- FULLY\_CAPTURED<br />Your authorisation has been fully captured, there are no further authorised funds available to capture.<br />The captured funds in this order can be refunded.<br />Subsequent Operations:<br />- Refund<br />- FAILED<br />Sorry, an error has occurred whilst processing your request.<br />- CANCELLED<br />The payee has abandoned the transaction during the PayPal redirect flow.<br />- PARTIALLY\_REFUNDED<br />Your order has been partially refunded, there are further captured funds available to refund.<br />Subsequent Operations:<br />- Capture<br />- Void<br />- Refund<br />- REFUNDED<br />Your order has been fully refunded, there are no outstanding captured funds available to refund.<br />There are authorised funds available to capture or void.<br />Subsequent Operations:<br />- Capture<br />- Void<br />- CLOSED<br />Your order is now closed, all funds have been collected and subsequently refunded.<br />There are no further operations available in regards to this order.<br />- `orderDetails.timestamp`<br />The time of the transaction. <br />- `orderDetails.currency`<br />The currency of the transaction.<br />- `orderDetails.amount`<br />The amount of the transaction. <br />- `orderDetails.refundedAmount`<br />The refund amount. <br />- `orderDetails.capturedAmount`<br />The amount captured. |
| `merchantPaymentReference`<br />String  | The unique reference for this payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `merchantConsumerReference`<br />String | Unique reference to anonymously identify your customer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `merchantPaymentMetadata`<br />String   | Additional data for this payment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |