React Native SDK
Target most up-to-date API base URL
We encourage you to always target the most up-to-date API base URL when sending requests to our platform. Have a look at our dedicated guide for a full overview.
To allow you a smooth transition, previous API base URLs remain available until further notice.
Our native SDK helps you communicate with the Client API. It offers:
- Convenient wrappers for API responses.
- Handling of all the details concerning the encryption of payment details.
- Caching of payment product logos and caching of images to offer additional information about payment products.
- Localisation of various labels and messages.
- User-friendly formatting of payment data such as card numbers and expiry dates.
- Validation of input.
- Checks to determine to which issuer a card number is associated.
Find the source code of the SDK on GitHub, including installation instructions.
To understand how to use this SDK, have a look at the following documentation:
- Mobile/Client Integration – familiarise yourself with various concepts.
- Client API Reference – the SDK wraps the Client API and (among other things) exposes the responses of the webservice calls as objects. Understanding the Client API will help you understand these SDK objects as well.
- The SDK on GitHub – the SDK contains a working example application which can help you understand how the SDK is best used.
- This current document will help you understand the global flow when creating payment pages using the SDK.
Once you are all set, read the next chapters on how to prepare and use the SDK.
For development and testing purposes, you can use our API Explorer. It allows you to easily query our Server API. We do not recommend using it on the live environment.
To create payments, you need to integrate the SDK with your project at first. All versions of the SDK are publicly available in our repository. To simplify integration, we have prepared a package below for quick access.
The SDK is available via npm.js.
npm
You can add the SDK as a dependency to your project by running the following command: adding the following code snippet to your package.json where ‘x.y.z’ is the version number:
npm install onlinepayments-sdk-client-reactnative
After the successful integration of the SDK with your project, you can proceed to the process of integration with the entire payment system. The complete payment process consists of these steps:
- Initialisation of Session and PaymentContext objects
- Receiving possible payment methods
- Receiving and displaying payment method details
- Validation of provided data
- Encryption and transfer of payment data
- Finalising transaction
1. Initialise Session and PaymentContext objects
Firstly, you need to create a Session enabling communication between the Server API and the client. Your app must have its own server, acting as an intermediary between our Client and Server API.
Since the customer initiates the payment in their app, the Client application requests the Server application to create a Session. The Server application can achieve this by using Create Session functionality from the Server SDK.
Try our API Explorer to send a CreateSession request.
After configuring and connecting your application to the Server API, you receive a response containing information about the created Session. A typical response looks like this:
{
"assetUrl": "https://assets.test.cdn.v-psp.com/s2s/515c2c0bd13d5dd4bd42",
"clientApiUrl": "https://payment.preprod.direct.worldline-solutions.com/",
"clientSessionId": "68a4b0b183a34016b4b694b97938f75b",
"customerId": "cf7d7aafd42e4a1cb9e4b0624a5041b1",
"invalidTokens": []
}
Now pass assetUrl, clientApiUrl, clientSessionId and customerId to the Client application. Once the application receives a response from the Server application with information about the Session, create a local Session object on the Client application side.
Next, create a PaymentContext object. It contains information about the form of payment, currency, country, amount, etc. You will use the PaymentContext and Session objects throughout the payment process.
Each Session has a fixed 3-hour lifespan. If it expires, you need to create a new Session
There are different payment methods available for different PaymentContext objects. If you change any variable, you will have to start the process again. Only the Session can remain the same if the payment is made with the same consumer.
2. Receive possible payment methods
The next step is to get and display the possible payment options. To do so, create a BasicPaymentProductsResponseListener and use the previously created Session and PaymentContext to invoke the GetBasicPaymentItems method which sends GetPaymentProducts to our Server API.
Have a look at the code sample below showing how to initialise an instance of PaymentContext class, how to initialise an instance of BasicPaymentProductsResponseListener , and use them to get the BasicPaymentProducts list with the Session object:
const paymentContext: PaymentContext = {
amountOfMoney: {
amount: 100,
currencyCode: ‘EUR’
},
countryCode: ‘NL’,
isRecurring: false
};
session.getBasicPaymentProducts(
paymentContext,
new BasicPaymentProductsListener(
(paymentProducts) => {
// Allow the customer to select a payment item and an optional
// account on file from the list of payment products
// represented by paymentProducts.
},
(errorResponse) => {
// Indicate that an error has occurred.
},
(exception) => {
// Indicate that an error has occurred.
}
)
);
3. Receive and display payment method details
Payment items are instances of BasicPaymentProduct . Your app can use these items to create a screen that lists them all. If you only have one payment item, you can skip this screen. However, you might also want to display the AccountOnFile selection.
If you are fine with the look-and-feel of the example app, you do not need to make any changes. If you only have one payment item, you can skip this screen. However, you might also want to display the AccountOnFile selection.
For some payment products, customers can indicate that they want our platform to store their credentials for Card On File. We refer to the stored data as an account on file or token. You can reuse this account on file / token for subsequent payments if your customers chose the same payment method.
The list of available payment products that the SDK receives from the Client API also contains the accounts on file for each payment product. Your application can present this list to the user.
Depending on the method chosen by the customer, consider cases of different data flows:
If the user has chosen a native form of payment, you need to use the SDK of the payment provider and handle the response only in the last step to inform the user about the payment status. Read more about native payments in the dedicated chapter.
For payments with a third-party payment provider, you receive data with the redirection address in the payment properties. Redirect your customers in their browser to the third-party payment portal to continue the payment process. After the successful payment, your app needs to handle the redirection to the Client app.
The standard payment process is a card payment. Once your customers have selected a payment item or a stored account on file, the Client SDK can request the necessary information your customers needs to provide for the payment.
An object representing the BasicPaymentProduct payment method provides a list of the fields your app needs to render, including displaying hints and validation rules. If your customers select an account on file, information already available can be prefilled in the input fields instead of requesting it from your customers. The prefilled data on behalf of the customer is in line with applicable regulations. Depending on the individual use case, your customers still might have to provide some data (i.e. the CVC).
4. Validate provided data
Now your application needs to validate the data your customers enter in your application’s interface. To do so, use the data validation component. The data entry interface must be fully transparent and understandable for your customers. We recommend ToolTips, which have individual fields or display appropriate validation errors.
5. Encrypt and transfer payment data
Based on the collected data, you need to create a PaymentRequest instance. This class has a tokenize property used to indicate whether the application should store the customer’s credentials for recurring payments. Use the following code sample for payment requests without tokenisation and without accounts on file:
const paymentRequest = new PaymentRequest(paymentProduct);
If you wish to tokenise the payment request, you can either supply it in the constructor or by setting the property at a later moment:
const paymentRequestTokenized = PaymentRequest(paymentProduct, undefined, true);
// Or set the property on an existing payment request
paymentRequest.tokenize = true;
// Or set the property on an existing payment request
paymentRequest.tokenize = true;
An account on file can be supplied in a similar manner:
const paymentRequestWithAccountOnFile =
PaymentRequest(paymentProduct, accountOnFile);
// Or set the property on an existing payment request
paymentRequest.accountOnFile= accountOnFile;
Once you configure a payment request, supply the values for the payment product fields. Use the identifiers of the fields, such as "cardNumber” and "cvv" to set the field values for the payment request:
paymentRequest.setValue("cardNumber", "1234567890");
paymentRequest.setValue("cvv", "123");
Now you can validate the payment request. As a result, a list of errors is available. For any validation error, you need to provide feedback to the customer. For more information, read the dedicated chapter.
const errors = await paymentRequest.validate();
if (errors.length) {
// The payment request is valid, and can be encrypted and sent to
// our platform via the merchant's server.
}
else {
// Notify the user that some fields contain invalid data.
}
After the PaymentRequest validation, encrypt the request and send it to your Server application. Have a look at the code sample showing how to use an instance of Session to encrypt a request:
const preparePaymentRequest = new PreparePaymentRequest(paymentRequest);
session.preparePaymentRequest(
preparePaymentRequest,
new PaymentRequestPreparedListener(
(preparedPaymentRequest) => {
// Submit the information contained in the encrypted
// payment request represented by preparedPaymentRequest
// to our platform via your server.
},
(errorResponse) => {
// Indicate that an error has occurred.
},
(exception) => {
// Indicate that an error has occurred.
}
)
);
See a more detailed description of the encryption process in the dedicated chapter.
6. Finalise transaction
After receiving the encrypted data, pass it to your server application to finalise the payment by sending a CreatePayment request.
The response may require additional actions from the Client specified in the MerchantAction object. In most cases, this involves redirecting the customer to an external party (i.e. for a 3-D Secure check). Once your customers complete this check, our platform processes the actual transaction. Read the Server SDK documentation for more information.
Finally, you have to pass the information to the Client application to display the transaction result to your customers.
Full overview of the payment flow in the Mobile/Client Integration guide.
SDK Objects
The SDK includes several objects. Choose the object of your interest from the list below to read more about it:
- Session
- PaymentContext
- BasicPaymentProduct
- PaymentProduct
- AccountOnFile
- DisplayHints
- PaymentRequest
- PreparedPaymentRequest
- ErrorResponse
Session
Session is the main component of the SDK. The object:
- Is the entry point to interact with our native SDKs
- Contains all functions that can be called on the Client API
- Is responsible for converting the responses of the API into plain Dart objects with the use of listeners
To establish communication with the Client API, it is crucial to initialize the Session properly. Mandatory properties for initialization include:
- client session identifier
- customer identifier
- client-api-url
- asset-base-url
You will get these parameters using the CreateSession from the Server API endpoint. Refer to the Server SDKs and the Server API to learn more.
During initialiation, determine if the application is in production and specify the application identifier. An additional parameter allows you to control whether network requests and responses are logged to the console.
This logging feature is disabled by default and should always be disabled in production.
The application identifier is used in the native SDK's Device Metadata when communicating with the Client API.
Properties |
---|
|
Device Metadata
The Device Metadata includes the following data:
Properties |
---|
|
PaymentContext
Instances of the PaymentContext class contain the most relevant payment information such as
- amountOfMoney
- currency
- countryCode
- isRecurring – an indication of whether the payment is a single payment or Card On File.
This object:
- Takes part the next steps of the transaction.
- Should remain in the same form after initialisation – you should use the same object through the entire transaction process.
AmountOfMoney
The AmountOfMoney model provides information about the payment amount, consisting of the amount expressed as a long type and the currency specified by currencyCode.
Note that amount includes currency fractions. The object below is equal to 1 EUR.
See example below:
"amountOfMoney": {
"amount": 100,
"currencyCode": "EUR"
},
BasicPaymentProduct
The BasicPaymentProduct model represents a primary payment product. It contains a list of available payment methods. The customer can select one method from this list. Each instance contains:
- An identifier.
- A field indicating the payment method of this product.
- A field indicating whether our platform can store the payment data as an account on file for subsequent payments.
- A field indicating whether the method allows Card On File.
- A field indicating whether the payment method uses redirection to a third party.
- A list of previously saved accounts on file for this payment product.
- Displays hints to render the BasicPaymentProduct appropriately, containing:
- An index indicating at which position the payment product belongs in a list of payment products
- A label
- A logo
- Information about related AccountOnFile instances.
- Two fields containing specific information about product 302 (Apple Pay) and 320 (Google Pay).
PaymentProduct
The Payment Product class extends the BasicPaymentProduct class and supplements the model with the PaymentProductField list. When a customer selects a payment item or an account on file, they must provide additional information such as an address, a bank account number, a credit card number, or an expiry date to process the actual payment.
Each payment item can have several fields that the customer needs to complete for processing payments. Instances of PaymentProductField represent information about the fields of payment items.
To retrieve instances of PaymentProduct, use the following code snippet:
const paymentProductRequest: PaymentProductRequest = {
productId,
paymentContext
};
session.getPaymentProduct(
paymentProductRequest,
new PaymentProductListener(
(paymentProduct) => {
// Allow the customer to select a payment item and an optional
// account on file from the list of payment products
// represented by paymentProducts.
},
(errorResponse) => {
// Indicate that an error has occurred.
},
(exception) => {
// Indicate that an error has occurred.
}
)
);
PaymentProductField
PaymentProductField represents fields of payment items. Each field has:
- An identifier
- Type
- Information about how to present the field to the customer in the user interface.
- A definition of restrictions that apply to the value of the field.
- A list of 'ValidationErrorMessages'.
The model includes a built-in data validation method to determine whether a given value is valid for the field. The method is based on DataRestrictions. It returns ValidationErrorMessages and methods for masking and uncasting the value by means of the built-in StringFormatter.
The code snippet below shows how to retrieve the field with the "cvv" identifier from a payment product.
const field = paymentProduct.getPaymentProductFieldById("cvv");
if (field !== undefined) {
const isRequired = field.dataRestrictions.isRequired;
const obfuscate = field.displayHints?.obfuscate;
const errorMessages = await field.validateValue("123");
const isValid = errorMessages.length === 0;
}
In this process, we:
- Inspect the data restrictions of the field to see whether this field is required or optional.
- Inspect the display hints of the field to see whether the values a customer provides should be obfuscated in a user interface.
- Validate the value "123".
- Inspect the number of validation errors to see whether the provided value is valid.
AccountOnFile
The AccountOnFile represents information about an account on file for a certain payment product. It includes:
- An identifier for the account on file.
- An identifier for the corresponding payment product.
- A collection of key-value pairs stored as a part of the account on file.
- Display hints that contain information about how to render the account on file.
- A method that produces a label describing the account on file.
Retrieve instances of AccountOnFile as instances of BasicPaymentProduct using the following code:
function getSelectedAccountOnFile(paymentProduct: BasicPaymentProduct, accountOnFileId: string) {
for (var aof of paymentProduct.accountsOnFile) {
if (aof.id === accountOnFileId) {
return aof;
}
}
return undefined;
}
DisplayHints
DisplayHints are objects containing hints, divided into three types:
- PaymentProductDisplayHints: The most important information about BasicPaymentProduct, i.e., a name and a logo. An additional property is displayOrderwhich indicates the appropriate display order according to the order index in relation to other BasicPaymentProducts. Use them to display the BasicPaymentProduct selection list.
- AccountOnFileDisplayHints: The list containing the ProductFields key-value pairs and the corresponding mask to apply the mask (e.g. asterisks) to the corresponding value from AccountOnFile.
- PaymentProductFieldDisplayHints: Defines the way of displaying PaymentProductFields. In addition to the name and placeholder, it contains PreferredInputType, based on which you can choose:
- The appropriate type of keyboard you should use.
- Whether the element must always be displayed as AlwaysShow.
- Whether the Obfuscate value should be obfuscated, as well as the value of Mask – a reference to the assigned ToolTip and FormElement.
Tooltip
Tooltip facilitates data entry. It can be available in the display hints for a PaymentProductField. It can contain an explanation text or a graphic, i.e. a photo of a card with an obfuscated CVV.
FormElement
A simplified description of the visual element instructing you to use it appropriately as either text, list, currency, date or boolean.
PaymentRequest
This class wraps the relationship between the selected PaymentProduct, AccountOnFile and the entered values. It allows you to easily extract masked or unmasked values. It contains a method of validating the entered data.
Check the dedicated encryption chapter for more information.
PreparedPaymentRequest
The instance of PreparePaymentRequest class is the result of encrypting a request using an instance of Session. It has two properties, encryptedFields and encodedClientMetaInfo – the strings that should be sent to our platform.
Check the dedicated encryption chapter for more information.
ErrorResponse
If an API call failed due to an API related error, the ErrorResponse object will contain more information about the error. It contains a message, an optional ApiError and an optional Throwable.
ApiError
ApiError contains an errorId and an optional list of API errors which can be used to help determine the exact error that occured.
The application identifier is used in the native SDK's Device Metadata when communicating with the Client API.
Properties |
---|
|
Device Metadata
The Device Metadata includes the following data:
Properties |
---|
|
PaymentContext
Instances of the PaymentContext class contain the most relevant payment information such as
- amountOfMoney
- currency
- countryCode
- isRecurring – an indication of whether the payment is a single payment or Card On File.
This object:
- Takes part the next steps of the transaction.
- Should remain in the same form after initialisation – you should use the same object through the entire transaction process.
AmountOfMoney
The AmountOfMoney model provides information about the payment amount, consisting of the amount expressed as a long type and the currency specified by currencyCode.
Note that amount includes currency fractions. The object below is equal to 1 EUR.
See example below:
"amountOfMoney": {
"amount": 100,
"currencyCode": "EUR"
},
BasicPaymentProduct
The BasicPaymentProduct model represents a primary payment product. It contains a list of available payment methods. The customer can select one method from this list. Each instance contains:
- An identifier.
- A field indicating the payment method of this product.
- A field indicating whether our platform can store the payment data as an account on file for subsequent payments.
- A field indicating whether the method allows Card On File.
- A field indicating whether the payment method uses redirection to a third party.
- A list of previously saved accounts on file for this payment product.
- Displays hints to render the BasicPaymentProduct appropriately, containing:
- An index indicating at which position the payment product belongs in a list of payment products
- A label
- A logo
- Information about related AccountOnFile instances.
- Two fields containing specific information about product 302 (Apple Pay) and 320 (Google Pay).
PaymentProduct
The Payment Product class extends the BasicPaymentProduct class and supplements the model with the PaymentProductField list. When a customer selects a payment item or an account on file, they must provide additional information such as an address, a bank account number, a credit card number, or an expiry date to process the actual payment.
Each payment item can have several fields that the customer needs to complete for processing payments. Instances of PaymentProductField represent information about the fields of payment items.
To retrieve instances of PaymentProduct, use the following code snippet:
const paymentProductRequest: PaymentProductRequest = {
productId,
paymentContext
};
session.getPaymentProduct(
paymentProductRequest,
new PaymentProductListener(
(paymentProduct) => {
// Allow the customer to select a payment item and an optional
// account on file from the list of payment products
// represented by paymentProducts.
},
(errorResponse) => {
// Indicate that an error has occurred.
},
(exception) => {
// Indicate that an error has occurred.
}
)
);
PaymentProductField
PaymentProductField represents fields of payment items. Each field has:
- An identifier
- Type
- Information about how to present the field to the customer in the user interface.
- A definition of restrictions that apply to the value of the field.
- A list of 'ValidationErrorMessages'.
The model includes a built-in data validation method to determine whether a given value is valid for the field. The method is based on DataRestrictions. It returns ValidationErrorMessages and methods for masking and uncasting the value by means of the built-in StringFormatter.
The code snippet below shows how to retrieve the field with the "cvv" identifier from a payment product.
const field = paymentProduct.getPaymentProductFieldById("cvv");
if (field !== undefined) {
const isRequired = field.dataRestrictions.isRequired;
const obfuscate = field.displayHints?.obfuscate;
const errorMessages = await field.validateValue("123");
const isValid = errorMessages.length === 0;
}
In this process, we:
- Inspect the data restrictions of the field to see whether this field is required or optional.
- Inspect the display hints of the field to see whether the values a customer provides should be obfuscated in a user interface.
- Validate the value "123".
- Inspect the number of validation errors to see whether the provided value is valid.
AccountOnFile
The AccountOnFile represents information about an account on file for a certain payment product. It includes:
- An identifier for the account on file.
- An identifier for the corresponding payment product.
- A collection of key-value pairs stored as a part of the account on file.
- Display hints that contain information about how to render the account on file.
- A method that produces a label describing the account on file.
Retrieve instances of AccountOnFile as instances of BasicPaymentProduct using the following code:
function getSelectedAccountOnFile(paymentProduct: BasicPaymentProduct, accountOnFileId: string) {
for (var aof of paymentProduct.accountsOnFile) {
if (aof.id === accountOnFileId) {
return aof;
}
}
return undefined;
}
DisplayHints
DisplayHints are objects containing hints, divided into three types:
- PaymentProductDisplayHints: The most important information about BasicPaymentProduct, i.e., a name and a logo. An additional property is displayOrderwhich indicates the appropriate display order according to the order index in relation to other BasicPaymentProducts. Use them to display the BasicPaymentProduct selection list.
- AccountOnFileDisplayHints: The list containing the ProductFields key-value pairs and the corresponding mask to apply the mask (e.g. asterisks) to the corresponding value from AccountOnFile.
- PaymentProductFieldDisplayHints: Defines the way of displaying PaymentProductFields. In addition to the name and placeholder, it contains PreferredInputType, based on which you can choose:
- The appropriate type of keyboard you should use.
- Whether the element must always be displayed as AlwaysShow.
- Whether the Obfuscate value should be obfuscated, as well as the value of Mask – a reference to the assigned ToolTip and FormElement.
Tooltip
Tooltip facilitates data entry. It can be available in the display hints for a PaymentProductField. It can contain an explanation text or a graphic, i.e. a photo of a card with an obfuscated CVV.
FormElement
A simplified description of the visual element instructing you to use it appropriately as either text, list, currency, date or boolean.
PaymentRequest
This class wraps the relationship between the selected PaymentProduct, AccountOnFile and the entered values. It allows you to easily extract masked or unmasked values. It contains a method of validating the entered data.
Check the dedicated encryption chapter for more information.
PreparedPaymentRequest
The instance of PreparePaymentRequest class is the result of encrypting a request using an instance of Session. It has two properties, encryptedFields and encodedClientMetaInfo – the strings that should be sent to our platform.
Check the dedicated encryption chapter for more information.
ErrorResponse
If an API call failed due to an API related error, the ErrorResponse object will contain more information about the error. It contains a message, an optional ApiError and an optional Throwable.
ApiError
ApiError contains an errorId and an optional list of API errors which can be used to help determine the exact error that occured.
Use additional features
The SDK has a lot more to offer. Have a look at the following features, as they will help you build the perfect solution.
Encrypt sensitive data
One of the biggest assets of the SDK is its encryption tool. It offers great security when transferring sensitive data (i.e. card numbers, expiry date, CVC code). An entire encryption/transfer flow looks like this: