cpp-react-native v0.2.5

CPP React Native SDK

The CPP React Native SDK provides easy to use UI elements which can be used within your react native applications to collect your users payment details.

Features

Simplified Security

We make it simple for you to collect sensitive data such as credit card numbers and remain PCI compliant. This means: 1. sensitive data is sent directly to CPP instead of passing through your server. 2. sensitive data is passed from our UI components to our API's under the hood so developers are not exposed to any sensitive data.

Getting Started

Installation

Install the package:

npm install cpp-react-native

Initialize CPP

const cpp = useCpp();

You can connect to CPP's test environment by passing in options {env: 'TEST'}

const cpp = useCpp({env: 'TEST'});

Create a session

Any time you want to collect your customers payment details you must first create a session. This session should be created securely by your server and the hppId should be returned to your front end.

Setup session

Setup the session.

const {completeSession, loading, error} = cpp.setupSession(hppId);

The call to setup session accepts a single parameter hppId which should be obtained from your server after it makes a request to create a session. This call will internally execute an asynchronous call to request session context and return three properties. 1. completeSession - a callback used to submit payment method details to CPP to complete the session. 2. loading - indicator to show when either asynchronous call to setup session or complete session is pending. 3. error - field to indicate whether an error occured while setting up the session. Value is undefined if no error occured however do note this field could be populated at a later point if the internal asynchronous call fails, therefore it is recommended the error is handled inside a useEffect hook.

Complete session

Complete the session.

const data = {
    type: 'card' // specify the type of payment method based on the UI component used e.g. 'card' for CardField
};

const {sessionResult, error } = await completeSession(data);

The call to complete session accepts a data parameter which requires that the 'type' property is specified this should be based on the UI component being used e.g. 'Card' when the 'CardField' UI component is used. The complete session is asynchronous and will return two properties. 1. sessionResult - a field indicating the result of the session. Possible values include: - 'Approved' - transaction was successful. - 'Declined' - transaction was declined. - 'Cancelled' - the session was cancelled. - 'Error' - an error occured attempting to complete the session. - 'Expired' - the session expired. 2. error - indicates whether an error occured. Value will be undefined if no error occured (refer to the error section at the very bottom for more info).

When completing the session the loading property returned in the original setupSession call can be used to indicate the operation is pending to your users.

Usage example (Card)

// App.ts
function App() {
    // On the client, request a Session from your server and store its hppId
    const [hppId, setHppId] = useState('');

    const fetchHppId = async () => {
        const hppId = await fetchHppId(); // fetch hppId from your server here
        setHppId(hppId);
    };

    useEffect(() => {
        fetchHppId();
    }, []);

    return (
        <PaymentScreen hppId={hppId} />
    );
}

// PaymentScreen.ts
import { CardField, useCpp } from 'cpp-react-native';

export default function PaymentScreen({hppId}) {
    const cpp = useCpp();

    // setup session context will make an asynchronous call to load the session context from the CPP API
    const {completeSession, loading, error} = cpp.setupSession(hppId);

    // handle a potential asynchronous setup session error
    useEffect(() => {
        if (error !== undefined) {
            console.log('an error occured loading the session context');
        }
    }, [error])

    const onPayPress = async () => {
        const data = {
            type: 'card' // specify the type of payment method based on the UI component used e.g. 'card' for CardField
        };

        const {sessionResult, error } = await completeSession(data);

        if (error !== undefined) {
            console.log('an error occured completing the session');
        } else if (sessionResult === 'Approved') {
            console.log('success');
        }
    }

    return (
      <View>
          <CardField />
          <Button onPress={onPayPress} title="Pay" disabled={loading} />
      </View>
    );
}

Props

Card Field

Status Codes and Errors

Errors have the following format and may include additional properties depending on the error.

{ reasonCode: 1, reasonFull: 'Unexpected error' }

Generic Errors (0-99)

Session Errors (100-199)

Card Errors (200-299)