Judopay Documentation

React Native

Prerequisites

React Native Integration with Judopay

Tip

For Mobile apps, it is recommended not to make a transaction from the app, as the Token and Secret could become compromised. Use the server to make the transaction.

Create a Register Card app and enable the Register Card Transactions permission.

Adding the Judopay SDK

The Judopay SDK for React Native is available as a node package and can be added to the project via npm or yarn.

To integrate the Mobile SDK into your app:

  1. Enter the following line into the terminal: npm install judo-react-native

For the purpose of this exercise, below is an example of a package.json file with the Judopay SDK dependency:

{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    ...
  },
  "dependencies": {
    ...
    "judo-react-native": "^2.1.0",
    ...
  },
  "devDependencies": {
    ...
  }
}

To start using the SDK for React Native:

  1. Import the JudoPay class from the judo-react-native package: import JudoPay from 'judo-react-native'

  2. Provide your token and secret: const judoPay = new JudoPay('my-token', 'my-secret')

  3. Set the SDK in sandbox mode: judoPay.isSandboxed = true

Tip

See Judopay's JudoKit for React Native on Github.

Making a Transaction

The method for making a transaction and configuring the flow:

async invokeTransaction(
    type: JudoTransactionType,
    configuration: JudoConfiguration
): Promise<JudoResponse>

Parameter

Description

type

JudoTransactionType

An enum value that describes the transaction type.

configuration

JudoConfiguration

An instance that configures the payment flow.

The response is handled via a Promise which resolves to a JudoResponse.

 

To make a transaction:

import { ..., JudoPay, JudoTransactionType, ... } from 'judo-react-native'
    const judo = new JudoPay('token', 'secret')
        judo.isSandboxed = true
    judo.invokeTransaction(JudoTransactionType.Payment, configuration)
        .then((response) => {/* Handle response */})
        .catch((error) => {/* Handle error */})

React Native Server to Server Transactions

To specify a server to server transaction:

  1. Set the JudoTransactionMode to ServerToServer when calling the Judo methods:

judo.invokePaymentMethodScreen(JudoTransactionMode.ServerToServer, configuration)
  .then((response) => {/* Handle response */})
  .catch((error) => {/* Handle error */})
  1. To specify an Apple Pay™ server to server transaction:

judo.invokeApplePay(JudoTransactionMode.ServerToServer, configuration)
  .then((response) => {/* Handle response */})
  1. To specify a Google Pay™ server to server transaction:

judo.invokeGooglePay(JudoTransactionMode.ServerToServer, configuration)
  .then((response) => {/* Handle response */})

Token Payments

If you are building your own card wallet, and not using a UI you can make a preauth or transaction using a stored card token.

To make a token payment or preauth tokenpayment:

  1. Use the /savecard endpoint to return a card token For details on endpoints, see API Reference.

The method signature is as follows:

public async performTokenTransaction(
mode: JudoTransactionMode,
configuration: JudoConfiguration,
token: string
): Promise<JudoResponse>

Parameter

Description

mode

JudoTransactionMode

A type used to specify either a pre-auth or transaction.

configuration

JudoConfiguration

An object used to configure the payment flow.

Also used to customise the user experience.

token

string

Describes the card token used for the token transaction.

 

The result is a JudoResponse object containing the transaction details:

try {
    const judo: Judo = new JudoPay('myToken', 'mySecret')
    const configuration: JudoConfiguration = {
        judoId: 'myJudoId',
        amount: amount,
        reference: reference
    }
    const response = await judo.performTokenTransaction(
        JudoTransactionMode.Payment,
        configuration,
        'myCardToken',
        )
// Handle response
    } catch (exception) {
// Handle exception
}

Customising the Payment Experience

Configuring the UI

You can customise the payment experience for the consumer by configuring the following UI behaviour properties in the JudoUIConfiguration object:

The JudoUIConfiguration object allows you to:

  • Enable | disable the Address Verification Service

  • Enable | disable consumers entering the CV2 code

  • Show | hide the amount in the payment button

  • Show | hide the amount in the Payments Widget

To create the JudoUIConfiguration object:

const uiConfiguration: JudoUIConfiguration = {
    isAVSEnabled: false,
    isCV2Enabled: true,
    isPaymentButtonAmountVisible: true,
    shouldDisplayAmount: true,
    theme: theme,
}
const configuration: JudoConfiguration = {
...
uiConfiguration: uiConfiguration,
...

Parameter

Description

isAVSEnabled

Boolean

Required

Enable | disable the Address Verification Service when making card transactions.

Default = False

isCV2Enabled

Boolean

Required

Enable | disable the merchant entering the CV2 code for every Token Payment | PreAuth transaction in the Payment Method Selection screen.

Default = True

isPaymentButtonAmountVisible

Boolean

Required

Show | hide the transaction amount on the Payment | PreAuth button.

Default = False

shouldDisplayAmount

Boolean

Required

Show | hide the transaction amount from the Payments Widget.

Default = True

React Native - Configuring the Payment Flow

Every transaction requires a JudoConfiguration object to be passed as a parameter. The JudoConfiguration object sets all the required parameters for configuring the payment flow, including all optional parameters to customise the payment experience.

To configure the payment flow:

1. Import:

  • JudoConfiguration

  • JudoAmount

  • JudoReference

from the judo-react-native package:

import JudoPay, {
      JudoConfiguration,
      JudoAmount,
      JudoReference
    } 
from 'judo-react-native'

Setting up the Transaction Reference

Setting up the transaction reference enables you to also set up your consumerReference and paymentReference which are included within the transaction.

These references help you to identify your consumer and transaction.

To set up the transaction reference:

  1. From the imported JudoReference interface:

interface JudoReference {
    consumerReference: string,
    paymentReference?: string,
    metadata?: Record<string, any>,
}
  1. Use the interface to set your consumerReference.

    A unique reference to identify your consumer.

  2. You can also set optional fields, for example:

    paymentReference: A unique payment reference for the transaction.

    metaData: any additional organisation or system details

to be included in the transaction.

 

For the purpose of this exercise a consumerReference is set:

const reference: JudoReference = {
  consumerReference: 'my-consumer-reference'
}
  1. For the purpose of this exercise, the:

  • amount

  • reference

  • judoID

are set in the JudoConfiguration instance:

const configuration: JudoConfiguration = {
    judoId: 'my-judo-id',
    amount: amount,
    reference: reference,
}

All the required parameters are now set up, and ready to make a transaction.

A complete JudoConfiguration example:

import { JudoAmount, JudoReference, JudoConfiguration } from 'judo-react-native'
    const amount: JudoAmount = {
        value: '1.00',
        currency: 'GBP',
        }
    const reference: JudoReference = {
    consumerReference: 'myConsumerReference',
    paymentReference: 'myPaymentReference',
    metadata: {
        'metadatakey': 'metadataValue',
        'metadatakey2': 'metadataValue',
            }
        }
    const configuration: JudoConfiguration = {
        judoId: 'my-judo-id',
        amount: amount,
        reference: reference,
}

Setting up the Transaction Amount

To set up the transaction amount:

  1. From the imported JudoAmount interface:

interface JudoAmount {
    value: string,
    currency: string,
}
  1. Create a new variable that implements the JudoAmount interface

  2. Add the variable to the configuration object:

const amount: JudoAmount = {
  value: '999.99',
  currency: 'GBP'
}

Setting the Primary Account Details

Note

To set the primary account details when using an alternative payment method, see Alternative Payment Method Configuration.

An example of the JudoAccountDetails interface:

interface JudoAccountDetails {
    name?: string,
    accountNumber?: string,
    dateOfBirth?: string,
    postCode?: string,
}
  1. To set the primary account details to be sent with the transaction:

const myAcccountDetails: JudoAccountDetails = {
  accountNumber: '4015434234',
  name: 'test-account-name',
}

const configuration: JudoConfiguration = {
  ...
  primaryAccountDetails: myAccountDetails,
  ...
}

Tip

The above properties are optional, so set only the ones you need.

Changing Default Supported Card Networks

To change the default supported card networks:

  1. Set your own supportedCardNetworks value

An example of the JudoCardNetwork:

enum JudoCardNetwork {
    Visa = 1 << 0,
    Mastercard = 1 << 1,
    Maestro = 1 << 2,
    Amex = 1 << 3,
    ChinaUnionPay = 1 << 4,
    JCB = 1 << 5,
    Discover = 1 << 6,
    DinersClub = 1 << 7,
    All = 1 << 8,
}

 

  1. For the purpose of this exercise, Visa and MasterCard are set as the only supported card networks:

const cardNetworks = JudoCardNetwork.Visa | JudoCardNetwork.Mastercard

 

  1. To explicitly set all card networks to be supported, instead of using the | operator to combine all the card networks, set:

const cardNetworks = JudoCardNetwork.All

Setting a Card Address

Note

To set the card address when using an alternative payment method, see Alternative Payment Method Configuration.

To send additional card address details with the transaction:

  1. Set the cardAddress parameter in the JudoConfiguration object:

const myCardAddress: JudoAddress = {
  line1: 'My Example Street 42',
  postCode: 'EX4 MPL3',
  town: 'Example Town',
  countryCode: 'GB',
}

const configuration: JudoConfiguration = {
  ...
  cardAddress: myCardAddress
  ...
}

Changing the Default Payment Methods

By default, all payment methods are displayed in the Payments Widget (as long as the required parameters are set).

As a merchant, you have flexibility over which payment methods to support.

  1. Change the paymentMethods property to the JudoPaymentMethod value in the JudoConfiguration instance:

An example of the JudoPaymentMethod:

enum JudoPaymentMethod {
    Card = 1 << 0,
    ApplePay = 1 << 1,
    GooglePay = 1 << 2,
    iDEAL = 1 << 3,
    All = 1 << 4,
}
  1. You can set multiple values using the | operator.

    For the purpose of this exercise, Card and Apple Pay™ are set as available payment methods:

const myPaymentMethods = JudoPaymentMethod.Card | JudoPaymentMethod.ApplePay
  1. To explicitly state all payment methods are to be displayed, instead of using the | operator to combine all the payment methods,

    set:

const myPaymentMethods = JudoPaymentMethod.All

React Native Styles and Themes

Note

To make custom fonts work, they must be added to your client app first.

The JudoTheme property handles the:

  • Font families

  • Font sizes

  • Font colors

Caution

Please note this will only apply styles and themes to the iOS platform.

Custom Fonts
const theme: JudoTheme = {     
largeTitleFont: "Quicksand-Bold",     
largeTitleSize: 18,     
titleFont: "Quicksand-Italic",     
titleSize: 16,     
headlineFont: "Quicksand-Regular",     
headlineSize: 15,     
headlineLightFont: "Quicksand-Regular",     
headlineLightSize: 15,     
bodyFont: "Quicksand-Regular",     
bodySize: 15,     
bodyBoldFont: "Quicksand-Bold",     
bodyBoldSize: 17,     
captionFont: "Quicksand-Regular",     
captionSize: 18,     
captionBoldFont: "Quicksand-Light",     
captionBoldSize: 16,     
jpBlackColor: "#262626",     
jpDarkGrayColor: "#999999",     
jpGrayColor: "#E5E5E5",     
jpLightGrayColor: "#F6F6F6",     
jpRedColor: "#E21900",     
jpWhiteColor: "#FFFFFF",     
buttonColor: "#999999",     
buttonTitleColor: "#000000", 
backButtonImage: "back-button.png",     
buttonCornerRadius: 5 
} 

An example of a complete custom theme:

const myTheme: JudoTheme = {
  largeTitleFont: 'Avenir',
  largeTitleSize: 20,
  buttonColor: '#FFFFFF',
  buttonCornerRadius: 4.0,
  backButtonImage: 'my-custom-icon-filename'
}

const uiConfiguration: JudoUIConfiguration {
  ...,
  theme: myTheme,
  ...,
}

const configuration: JudoConfiguration = {
  ...,
  uiConfiguration: uiConfig,
  …
}

Payments Widget

To set up the Payments Widget for React Native:

1. Set up the JudoConfiguration instance:

const configuration: JudoConfiguration = {
...
    paymentMethods: JudoPaymentMethods.All,
        applePayConfiguration: applePayConfiguration,
        googlePayConfiguration: googlePayConfiguration,
...
}
    judo.invokePaymentMethodScreen(JudoTransactionMode.Payment, configuration)
        .then((response) => {/* Handle response */})
        .catch((error) => {/* Handle error */})

PayByBankApp

PayByBankApp enables consumers to use bank transfers to easily pay for goods and services online.

For more details on using the PayByBankApp as an alternative payment method, see:

iDEAL

iDEAL enables consumers to easily pay online for goods and services in the Netherlands.

For more details using iDEAL as an alternative payment method, see:

Displaying iDEAL as a Payment Method

To add iDEAL support to your Payments Widget, set:

  1. The currency code to EUR (Euro)

  2. The judoId

An example of a valid iDEAL configuration:

const	configuration:	JudoConfiguration	= {				
...				
judoId:	'myJudoId'				
...
}

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