PayPal

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.

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

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

Add the Payment Form to your Website

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>

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

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 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. Use this reference from the response to populate yourPaymentSession.

Make sure you replace the payPalConfiguration object values with your own.

<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: '[email protected]'
      },
      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.

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

Parameter	Description
style String Optional	Set the style for the PayPal button. For a full list of styling options, see Styling.
merchantId String Optional	Your PayPal Merchant ID. To get your PayPal Merchant ID: Navigate to your PayPal Account Settings -> Business Information -> PayPal Merchant ID.
amount Float Required	The amount to process. Format: Two decimal places For currencies using a different structure please contact Judopay for support.
currency String Required	The currency of the transaction. Any ISO 4217 alphabetic currency code: GBP USD EUR
merchantPaymentReference String Required	Your unique reference for this payment. Format: Maximum length 50 characters. This value should be unique in order to protect your customers against duplicate transactions. If you set this reference it will be used. Otherwise a reference will be internally generated.
judoId String Required	Unique ID supplied by Judopay.Specific to a merchant and/or location. Format: 100100100 Maximum length 9 characters. Do not include spaces or dashes.
dynamicDescriptor String Optional	The merchant’s ‘Trading Name’ that will appear on the consumer’s statement. The value is returned in the response within the appearsOnStatement field. Format: Maximum 25 characters in length.
paymentSession String Required	The additional way to authenticate a 3D Secure 2 payments or preauths transaction.
consumer Object Required	Consumer details: merchantConsumerReference firstName surname emailAddress
billingAddress Object Optional	Billing address details: address1* address2 city* country* See here for the list of valid ISO 3166-1 format country codes. postcode* Required *
shippingAddress Object Optional	Shipping address details: address1* address2 city* country* See here for the list of valid ISO 3166-1 format country codes. postcode* Required *
onSuccess Object Required	Callback invoked when the payment is successful. The response object is provided as a parameter, with the following properties: receiptId orderId transactionType createdAt status
onError Object Required	Callback invoked when the payment fails. 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.
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.
The consumer should be redirected to an Error Page.

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.

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

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.

Webhook Notification Examples

Preauth

{
  "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

{
  "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

{
  "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

{
  "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.

{
  "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.

{
  "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

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

PayPal

Integrating PayPal (BETA)

Prerequisites

Step One: Display the PayPal Button

PayPal Configuration Parameter Descriptions

Step Two: Handle the Response

PayPal Webhooks

Prerequisites

Webhook Notification Examples

Preauth

Partial Capture

Full Capture

Payment

Partial Refund

Partial Refund

Full Refund

Webhook Parameter Descriptions