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

| Property | Type | Description | | --- | --- | --- | |autoFocus | PropTypes.bool | Automatically focus Card Number field on render| |onFocus | PropTypes.func | Receives the name of currently focused field | |placeholders | PropTypes.object | Defaults to { number: "1234 5678 1234 5678", expiry: "MM/YY", cvc: "CVC" } | |inputStyle | Text.propTypes.style | Style for credit-card form's textInput | |validColor | PropTypes.string | Color that will be applied for valid text input. Defaults to: "{inputStyle.color}" | |invalidColor | PropTypes.string | Color that will be applied for invalid text input. Defaults to: "red" | |placeholderColor | PropTypes.string | Color that will be applied for text input placeholder. Defaults to: "gray" |

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)

| Code | Text | Implications | | :------------ |:----------------| :------------| | 1 | Unexpected error | Unexpected error has occured |

Session Errors (100-199)

| Code | Text | Implications | | :------------ |:----------------| :------------| | 100 | Error fetching session context | An error occured while attempting to retrieve context required to complete session | | 101 | Invalid encryption key | The key intended to encrypt the users payment details is invalid | | 102 | Encryption failed | An error occured while attempting to encrypt users payment details | | 103 | Error completing session | An error occured while attempting to submit encrypted payment details to CPP | | 104 | Invalid sign | The signature in the complete session response was invalid | | 105 | Session expired | The session has expired (create a new session to continue) | | 106 | Session already completed | The session has already been completed (create a new session to continue) | | 107 | Invalid complete session response | The session response data is invalid | | 108 | Payment type is required | The required 'type' parameter was missing from the complete session call | | 109 | Unsupported payment type | The payment type submitted does not match the types specified in the session |

Card Errors (200-299)

| Code | Text | Implications | | :------------ |:----------------| :------------| | 200 | Empty card | No card details were entered. | | 201 | Invalid card | User entered invalid card details. See additional 'status' property for more details { number: "valid", expiry: "invalid", cvc: "incomplete" }, possible statuses are: 'valid', 'invalid' or 'incomplete'. |